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 " vnc=<display>[,<optargs>]\n" 814 " select display type\n", QEMU_ARCH_ALL) 815STEXI 816@item -display @var{type} 817@findex -display 818Select type of display to use. This option is a replacement for the 819old style -sdl/-curses/... options. Valid values for @var{type} are 820@table @option 821@item sdl 822Display video output via SDL (usually in a separate graphics 823window; see the SDL documentation for other possibilities). 824@item curses 825Display video output via curses. For graphics device models which 826support a text mode, QEMU can display this output using a 827curses/ncurses interface. Nothing is displayed when the graphics 828device is in graphical mode or if the graphics device does not support 829a text mode. Generally only the VGA device models support text mode. 830@item none 831Do not display video output. The guest will still see an emulated 832graphics card, but its output will not be displayed to the QEMU 833user. This option differs from the -nographic option in that it 834only affects what is done with video output; -nographic also changes 835the destination of the serial and parallel port data. 836@item vnc 837Start a VNC server on display <arg> 838@end table 839ETEXI 840 841DEF("nographic", 0, QEMU_OPTION_nographic, 842 "-nographic disable graphical output and redirect serial I/Os to console\n", 843 QEMU_ARCH_ALL) 844STEXI 845@item -nographic 846@findex -nographic 847Normally, QEMU uses SDL to display the VGA output. With this option, 848you can totally disable graphical output so that QEMU is a simple 849command line application. The emulated serial port is redirected on 850the console and muxed with the monitor (unless redirected elsewhere 851explicitly). Therefore, you can still use QEMU to debug a Linux kernel 852with a serial console. Use @key{C-a h} for help on switching between 853the console and monitor. 854ETEXI 855 856DEF("curses", 0, QEMU_OPTION_curses, 857 "-curses use a curses/ncurses interface instead of SDL\n", 858 QEMU_ARCH_ALL) 859STEXI 860@item -curses 861@findex -curses 862Normally, QEMU uses SDL to display the VGA output. With this option, 863QEMU can display the VGA output when in text mode using a 864curses/ncurses interface. Nothing is displayed in graphical mode. 865ETEXI 866 867DEF("no-frame", 0, QEMU_OPTION_no_frame, 868 "-no-frame open SDL window without a frame and window decorations\n", 869 QEMU_ARCH_ALL) 870STEXI 871@item -no-frame 872@findex -no-frame 873Do not use decorations for SDL windows and start them using the whole 874available screen space. This makes the using QEMU in a dedicated desktop 875workspace more convenient. 876ETEXI 877 878DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 879 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 880 QEMU_ARCH_ALL) 881STEXI 882@item -alt-grab 883@findex -alt-grab 884Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 885affects the special keys (for fullscreen, monitor-mode switching, etc). 886ETEXI 887 888DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 889 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 890 QEMU_ARCH_ALL) 891STEXI 892@item -ctrl-grab 893@findex -ctrl-grab 894Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 895affects the special keys (for fullscreen, monitor-mode switching, etc). 896ETEXI 897 898DEF("no-quit", 0, QEMU_OPTION_no_quit, 899 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 900STEXI 901@item -no-quit 902@findex -no-quit 903Disable SDL window close capability. 904ETEXI 905 906DEF("sdl", 0, QEMU_OPTION_sdl, 907 "-sdl enable SDL\n", QEMU_ARCH_ALL) 908STEXI 909@item -sdl 910@findex -sdl 911Enable SDL. 912ETEXI 913 914DEF("spice", HAS_ARG, QEMU_OPTION_spice, 915 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 916 " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 917 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 918 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6]\n" 919 " [,tls-ciphers=<list>]\n" 920 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 921 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 922 " [,sasl][,password=<secret>][,disable-ticketing]\n" 923 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 924 " [,jpeg-wan-compression=[auto|never|always]]\n" 925 " [,zlib-glz-wan-compression=[auto|never|always]]\n" 926 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 927 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 928 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 929 " enable spice\n" 930 " at least one of {port, tls-port} is mandatory\n", 931 QEMU_ARCH_ALL) 932STEXI 933@item -spice @var{option}[,@var{option}[,...]] 934@findex -spice 935Enable the spice remote desktop protocol. Valid options are 936 937@table @option 938 939@item port=<nr> 940Set the TCP port spice is listening on for plaintext channels. 941 942@item addr=<addr> 943Set the IP address spice is listening on. Default is any address. 944 945@item ipv4 946@item ipv6 947Force using the specified IP version. 948 949@item password=<secret> 950Set the password you need to authenticate. 951 952@item sasl 953Require that the client use SASL to authenticate with the spice. 954The exact choice of authentication method used is controlled from the 955system / user's SASL configuration file for the 'qemu' service. This 956is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 957unprivileged user, an environment variable SASL_CONF_PATH can be used 958to make it search alternate locations for the service config. 959While some SASL auth methods can also provide data encryption (eg GSSAPI), 960it is recommended that SASL always be combined with the 'tls' and 961'x509' settings to enable use of SSL and server certificates. This 962ensures a data encryption preventing compromise of authentication 963credentials. 964 965@item disable-ticketing 966Allow client connects without authentication. 967 968@item disable-copy-paste 969Disable copy paste between the client and the guest. 970 971@item disable-agent-file-xfer 972Disable spice-vdagent based file-xfer between the client and the guest. 973 974@item tls-port=<nr> 975Set the TCP port spice is listening on for encrypted channels. 976 977@item x509-dir=<dir> 978Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 979 980@item x509-key-file=<file> 981@item x509-key-password=<file> 982@item x509-cert-file=<file> 983@item x509-cacert-file=<file> 984@item x509-dh-key-file=<file> 985The x509 file names can also be configured individually. 986 987@item tls-ciphers=<list> 988Specify which ciphers to use. 989 990@item tls-channel=[main|display|cursor|inputs|record|playback] 991@item plaintext-channel=[main|display|cursor|inputs|record|playback] 992Force specific channel to be used with or without TLS encryption. The 993options can be specified multiple times to configure multiple 994channels. The special name "default" can be used to set the default 995mode. For channels which are not explicitly forced into one mode the 996spice client is allowed to pick tls/plaintext as he pleases. 997 998@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 999Configure image compression (lossless). 1000Default is auto_glz. 1001 1002@item jpeg-wan-compression=[auto|never|always] 1003@item zlib-glz-wan-compression=[auto|never|always] 1004Configure wan image compression (lossy for slow links). 1005Default is auto. 1006 1007@item streaming-video=[off|all|filter] 1008Configure video stream detection. Default is filter. 1009 1010@item agent-mouse=[on|off] 1011Enable/disable passing mouse events via vdagent. Default is on. 1012 1013@item playback-compression=[on|off] 1014Enable/disable audio stream compression (using celt 0.5.1). Default is on. 1015 1016@item seamless-migration=[on|off] 1017Enable/disable spice seamless migration. Default is off. 1018 1019@end table 1020ETEXI 1021 1022DEF("portrait", 0, QEMU_OPTION_portrait, 1023 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1024 QEMU_ARCH_ALL) 1025STEXI 1026@item -portrait 1027@findex -portrait 1028Rotate graphical output 90 deg left (only PXA LCD). 1029ETEXI 1030 1031DEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 1032 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 1033 QEMU_ARCH_ALL) 1034STEXI 1035@item -rotate @var{deg} 1036@findex -rotate 1037Rotate graphical output some deg left (only PXA LCD). 1038ETEXI 1039 1040DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1041 "-vga [std|cirrus|vmware|qxl|xenfb|none]\n" 1042 " select video card type\n", QEMU_ARCH_ALL) 1043STEXI 1044@item -vga @var{type} 1045@findex -vga 1046Select type of VGA card to emulate. Valid values for @var{type} are 1047@table @option 1048@item cirrus 1049Cirrus Logic GD5446 Video card. All Windows versions starting from 1050Windows 95 should recognize and use this graphic card. For optimal 1051performances, use 16 bit color depth in the guest and the host OS. 1052(This one is the default) 1053@item std 1054Standard VGA card with Bochs VBE extensions. If your guest OS 1055supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 1056to use high resolution modes (>= 1280x1024x16) then you should use 1057this option. 1058@item vmware 1059VMWare SVGA-II compatible adapter. Use it if you have sufficiently 1060recent XFree86/XOrg server or Windows guest with a driver for this 1061card. 1062@item qxl 1063QXL paravirtual graphic card. It is VGA compatible (including VESA 10642.0 VBE support). Works best with qxl guest drivers installed though. 1065Recommended choice when using the spice protocol. 1066@item none 1067Disable VGA card. 1068@end table 1069ETEXI 1070 1071DEF("full-screen", 0, QEMU_OPTION_full_screen, 1072 "-full-screen start in full screen\n", QEMU_ARCH_ALL) 1073STEXI 1074@item -full-screen 1075@findex -full-screen 1076Start in full screen. 1077ETEXI 1078 1079DEF("g", 1, QEMU_OPTION_g , 1080 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1081 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 1082STEXI 1083@item -g @var{width}x@var{height}[x@var{depth}] 1084@findex -g 1085Set the initial graphical resolution and depth (PPC, SPARC only). 1086ETEXI 1087 1088DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1089 "-vnc display start a VNC server on display\n", QEMU_ARCH_ALL) 1090STEXI 1091@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 1092@findex -vnc 1093Normally, QEMU uses SDL to display the VGA output. With this option, 1094you can have QEMU listen on VNC display @var{display} and redirect the VGA 1095display over the VNC session. It is very useful to enable the usb 1096tablet device when using this option (option @option{-usbdevice 1097tablet}). When using the VNC display, you must use the @option{-k} 1098parameter to set the keyboard layout if you are not using en-us. Valid 1099syntax for the @var{display} is 1100 1101@table @option 1102 1103@item @var{host}:@var{d} 1104 1105TCP connections will only be allowed from @var{host} on display @var{d}. 1106By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 1107be omitted in which case the server will accept connections from any host. 1108 1109@item unix:@var{path} 1110 1111Connections will be allowed over UNIX domain sockets where @var{path} is the 1112location of a unix socket to listen for connections on. 1113 1114@item none 1115 1116VNC is initialized but not started. The monitor @code{change} command 1117can be used to later start the VNC server. 1118 1119@end table 1120 1121Following the @var{display} value there may be one or more @var{option} flags 1122separated by commas. Valid options are 1123 1124@table @option 1125 1126@item reverse 1127 1128Connect to a listening VNC client via a ``reverse'' connection. The 1129client is specified by the @var{display}. For reverse network 1130connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 1131is a TCP port number, not a display number. 1132 1133@item websocket 1134 1135Opens an additional TCP listening port dedicated to VNC Websocket connections. 1136By definition the Websocket port is 5700+@var{display}. If @var{host} is 1137specified connections will only be allowed from this host. 1138As an alternative the Websocket port could be specified by using 1139@code{websocket}=@var{port}. 1140TLS encryption for the Websocket connection is supported if the required 1141certificates are specified with the VNC option @option{x509}. 1142 1143@item password 1144 1145Require that password based authentication is used for client connections. 1146 1147The password must be set separately using the @code{set_password} command in 1148the @ref{pcsys_monitor}. The syntax to change your password is: 1149@code{set_password <protocol> <password>} where <protocol> could be either 1150"vnc" or "spice". 1151 1152If you would like to change <protocol> password expiration, you should use 1153@code{expire_password <protocol> <expiration-time>} where expiration time could 1154be one of the following options: now, never, +seconds or UNIX time of 1155expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 1156to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 1157date and time). 1158 1159You can also use keywords "now" or "never" for the expiration time to 1160allow <protocol> password to expire immediately or never expire. 1161 1162@item tls 1163 1164Require that client use TLS when communicating with the VNC server. This 1165uses anonymous TLS credentials so is susceptible to a man-in-the-middle 1166attack. It is recommended that this option be combined with either the 1167@option{x509} or @option{x509verify} options. 1168 1169@item x509=@var{/path/to/certificate/dir} 1170 1171Valid if @option{tls} is specified. Require that x509 credentials are used 1172for negotiating the TLS session. The server will send its x509 certificate 1173to the client. It is recommended that a password be set on the VNC server 1174to provide authentication of the client when this is used. The path following 1175this option specifies where the x509 certificates are to be loaded from. 1176See the @ref{vnc_security} section for details on generating certificates. 1177 1178@item x509verify=@var{/path/to/certificate/dir} 1179 1180Valid if @option{tls} is specified. Require that x509 credentials are used 1181for negotiating the TLS session. The server will send its x509 certificate 1182to the client, and request that the client send its own x509 certificate. 1183The server will validate the client's certificate against the CA certificate, 1184and reject clients when validation fails. If the certificate authority is 1185trusted, this is a sufficient authentication mechanism. You may still wish 1186to set a password on the VNC server as a second authentication layer. The 1187path following this option specifies where the x509 certificates are to 1188be loaded from. See the @ref{vnc_security} section for details on generating 1189certificates. 1190 1191@item sasl 1192 1193Require that the client use SASL to authenticate with the VNC server. 1194The exact choice of authentication method used is controlled from the 1195system / user's SASL configuration file for the 'qemu' service. This 1196is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 1197unprivileged user, an environment variable SASL_CONF_PATH can be used 1198to make it search alternate locations for the service config. 1199While some SASL auth methods can also provide data encryption (eg GSSAPI), 1200it is recommended that SASL always be combined with the 'tls' and 1201'x509' settings to enable use of SSL and server certificates. This 1202ensures a data encryption preventing compromise of authentication 1203credentials. See the @ref{vnc_security} section for details on using 1204SASL authentication. 1205 1206@item acl 1207 1208Turn on access control lists for checking of the x509 client certificate 1209and SASL party. For x509 certs, the ACL check is made against the 1210certificate's distinguished name. This is something that looks like 1211@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 1212made against the username, which depending on the SASL plugin, may 1213include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 1214When the @option{acl} flag is set, the initial access list will be 1215empty, with a @code{deny} policy. Thus no one will be allowed to 1216use the VNC server until the ACLs have been loaded. This can be 1217achieved using the @code{acl} monitor command. 1218 1219@item lossy 1220 1221Enable lossy compression methods (gradient, JPEG, ...). If this 1222option is set, VNC client may receive lossy framebuffer updates 1223depending on its encoding settings. Enabling this option can save 1224a lot of bandwidth at the expense of quality. 1225 1226@item non-adaptive 1227 1228Disable adaptive encodings. Adaptive encodings are enabled by default. 1229An adaptive encoding will try to detect frequently updated screen regions, 1230and send updates in these regions using a lossy encoding (like JPEG). 1231This can be really helpful to save bandwidth when playing videos. Disabling 1232adaptive encodings allows to restore the original static behavior of encodings 1233like Tight. 1234 1235@item share=[allow-exclusive|force-shared|ignore] 1236 1237Set display sharing policy. 'allow-exclusive' allows clients to ask 1238for exclusive access. As suggested by the rfb spec this is 1239implemented by dropping other connections. Connecting multiple 1240clients in parallel requires all clients asking for a shared session 1241(vncviewer: -shared switch). This is the default. 'force-shared' 1242disables exclusive client access. Useful for shared desktop sessions, 1243where you don't want someone forgetting specify -shared disconnect 1244everybody else. 'ignore' completely ignores the shared flag and 1245allows everybody connect unconditionally. Doesn't conform to the rfb 1246spec but is traditional QEMU behavior. 1247 1248@end table 1249ETEXI 1250 1251STEXI 1252@end table 1253ETEXI 1254ARCHHEADING(, QEMU_ARCH_I386) 1255 1256ARCHHEADING(i386 target only:, QEMU_ARCH_I386) 1257STEXI 1258@table @option 1259ETEXI 1260 1261DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1262 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1263 QEMU_ARCH_I386) 1264STEXI 1265@item -win2k-hack 1266@findex -win2k-hack 1267Use it when installing Windows 2000 to avoid a disk full bug. After 1268Windows 2000 is installed, you no longer need this option (this option 1269slows down the IDE transfers). 1270ETEXI 1271 1272HXCOMM Deprecated by -rtc 1273DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 1274 1275DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1276 "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1277 QEMU_ARCH_I386) 1278STEXI 1279@item -no-fd-bootchk 1280@findex -no-fd-bootchk 1281Disable boot signature checking for floppy disks in BIOS. May 1282be needed to boot from old floppy disks. 1283ETEXI 1284 1285DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1286 "-no-acpi disable ACPI\n", QEMU_ARCH_I386) 1287STEXI 1288@item -no-acpi 1289@findex -no-acpi 1290Disable ACPI (Advanced Configuration and Power Interface) support. Use 1291it if your guest OS complains about ACPI problems (PC target machine 1292only). 1293ETEXI 1294 1295DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1296 "-no-hpet disable HPET\n", QEMU_ARCH_I386) 1297STEXI 1298@item -no-hpet 1299@findex -no-hpet 1300Disable HPET support. 1301ETEXI 1302 1303DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1304 "-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" 1305 " ACPI table description\n", QEMU_ARCH_I386) 1306STEXI 1307@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}]...] 1308@findex -acpitable 1309Add ACPI table with specified header fields and context from specified files. 1310For file=, take whole ACPI table from the specified files, including all 1311ACPI headers (possible overridden by other options). 1312For data=, only data 1313portion of the table is used, all header information is specified in the 1314command line. 1315ETEXI 1316 1317DEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1318 "-smbios file=binary\n" 1319 " load SMBIOS entry from binary file\n" 1320 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1321 " specify SMBIOS type 0 fields\n" 1322 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1323 " [,uuid=uuid][,sku=str][,family=str]\n" 1324 " specify SMBIOS type 1 fields\n", QEMU_ARCH_I386) 1325STEXI 1326@item -smbios file=@var{binary} 1327@findex -smbios 1328Load SMBIOS entry from binary file. 1329 1330@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}] 1331Specify SMBIOS type 0 fields 1332 1333@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}] 1334Specify SMBIOS type 1 fields 1335ETEXI 1336 1337STEXI 1338@end table 1339ETEXI 1340DEFHEADING() 1341 1342DEFHEADING(Network options:) 1343STEXI 1344@table @option 1345ETEXI 1346 1347HXCOMM Legacy slirp options (now moved to -net user): 1348#ifdef CONFIG_SLIRP 1349DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1350DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1351DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1352#ifndef _WIN32 1353DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1354#endif 1355#endif 1356 1357DEF("net", HAS_ARG, QEMU_OPTION_net, 1358 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 1359 " create a new Network Interface Card and connect it to VLAN 'n'\n" 1360#ifdef CONFIG_SLIRP 1361 "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n" 1362 " [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n" 1363 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1364#ifndef _WIN32 1365 "[,smb=dir[,smbserver=addr]]\n" 1366#endif 1367 " connect the user mode network stack to VLAN 'n', configure its\n" 1368 " DHCP server and enabled optional services\n" 1369#endif 1370#ifdef _WIN32 1371 "-net tap[,vlan=n][,name=str],ifname=name\n" 1372 " connect the host TAP network interface to VLAN 'n'\n" 1373#else 1374 "-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" 1375 " connect the host TAP network interface to VLAN 'n'\n" 1376 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1377 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1378 " to deconfigure it\n" 1379 " use '[down]script=no' to disable script execution\n" 1380 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1381 " configure it\n" 1382 " use 'fd=h' to connect to an already opened TAP interface\n" 1383 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1384 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1385 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1386 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1387 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 1388 " use vhost=on to enable experimental in kernel accelerator\n" 1389 " (only has effect for virtio guests which use MSIX)\n" 1390 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 1391 " use 'vhostfd=h' to connect to an already opened vhost net device\n" 1392 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1393 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 1394 "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n" 1395 " connects a host TAP network interface to a host bridge device 'br'\n" 1396 " (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n" 1397 " (default=" DEFAULT_BRIDGE_HELPER ")\n" 1398#endif 1399 "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n" 1400 " connect the vlan 'n' to another VLAN using a socket connection\n" 1401 "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 1402 " connect the vlan 'n' to multicast maddr and port\n" 1403 " use 'localaddr=addr' to specify the host address to send packets from\n" 1404 "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n" 1405 " connect the vlan 'n' to another VLAN using an UDP tunnel\n" 1406#ifdef CONFIG_VDE 1407 "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 1408 " connect the vlan 'n' to port 'n' of a vde switch running\n" 1409 " on host and listening for incoming connections on 'socketpath'.\n" 1410 " Use group 'groupname' and mode 'octalmode' to change default\n" 1411 " ownership and permissions for communication port.\n" 1412#endif 1413#ifdef CONFIG_NETMAP 1414 "-net netmap,ifname=name[,devname=nmname]\n" 1415 " attach to the existing netmap-enabled network interface 'name', or to a\n" 1416 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 1417 " netmap device, defaults to '/dev/netmap')\n" 1418#endif 1419 "-net dump[,vlan=n][,file=f][,len=n]\n" 1420 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 1421 "-net none use it alone to have zero network devices. If no -net option\n" 1422 " is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL) 1423DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 1424 "-netdev [" 1425#ifdef CONFIG_SLIRP 1426 "user|" 1427#endif 1428 "tap|" 1429 "bridge|" 1430#ifdef CONFIG_VDE 1431 "vde|" 1432#endif 1433#ifdef CONFIG_NETMAP 1434 "netmap|" 1435#endif 1436 "socket|" 1437 "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL) 1438STEXI 1439@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 1440@findex -net 1441Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 1442= 0 is the default). The NIC is an e1000 by default on the PC 1443target. Optionally, the MAC address can be changed to @var{mac}, the 1444device address set to @var{addr} (PCI cards only), 1445and a @var{name} can be assigned for use in monitor commands. 1446Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 1447that the card should have; this option currently only affects virtio cards; set 1448@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 1449NIC is created. QEMU can emulate several different models of network card. 1450Valid values for @var{type} are 1451@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 1452@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 1453@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 1454Not all devices are supported on all targets. Use @code{-net nic,model=help} 1455for a list of available devices for your target. 1456 1457@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1458@findex -netdev 1459@item -net user[,@var{option}][,@var{option}][,...] 1460Use the user mode network stack which requires no administrator 1461privilege to run. Valid options are: 1462 1463@table @option 1464@item vlan=@var{n} 1465Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 1466 1467@item id=@var{id} 1468@item name=@var{name} 1469Assign symbolic name for use in monitor commands. 1470 1471@item net=@var{addr}[/@var{mask}] 1472Set IP network address the guest will see. Optionally specify the netmask, 1473either in the form a.b.c.d or as number of valid top-most bits. Default is 147410.0.2.0/24. 1475 1476@item host=@var{addr} 1477Specify the guest-visible address of the host. Default is the 2nd IP in the 1478guest network, i.e. x.x.x.2. 1479 1480@item restrict=on|off 1481If this option is enabled, the guest will be isolated, i.e. it will not be 1482able to contact the host and no guest IP packets will be routed over the host 1483to the outside. This option does not affect any explicitly set forwarding rules. 1484 1485@item hostname=@var{name} 1486Specifies the client hostname reported by the built-in DHCP server. 1487 1488@item dhcpstart=@var{addr} 1489Specify the first of the 16 IPs the built-in DHCP server can assign. Default 1490is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 1491 1492@item dns=@var{addr} 1493Specify the guest-visible address of the virtual nameserver. The address must 1494be different from the host address. Default is the 3rd IP in the guest network, 1495i.e. x.x.x.3. 1496 1497@item dnssearch=@var{domain} 1498Provides an entry for the domain-search list sent by the built-in 1499DHCP server. More than one domain suffix can be transmitted by specifying 1500this option multiple times. If supported, this will cause the guest to 1501automatically try to append the given domain suffix(es) in case a domain name 1502can not be resolved. 1503 1504Example: 1505@example 1506qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 1507@end example 1508 1509@item tftp=@var{dir} 1510When using the user mode network stack, activate a built-in TFTP 1511server. The files in @var{dir} will be exposed as the root of a TFTP server. 1512The TFTP client on the guest must be configured in binary mode (use the command 1513@code{bin} of the Unix TFTP client). 1514 1515@item bootfile=@var{file} 1516When using the user mode network stack, broadcast @var{file} as the BOOTP 1517filename. In conjunction with @option{tftp}, this can be used to network boot 1518a guest from a local directory. 1519 1520Example (using pxelinux): 1521@example 1522qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 1523@end example 1524 1525@item smb=@var{dir}[,smbserver=@var{addr}] 1526When using the user mode network stack, activate a built-in SMB 1527server so that Windows OSes can access to the host files in @file{@var{dir}} 1528transparently. The IP address of the SMB server can be set to @var{addr}. By 1529default the 4th IP in the guest network is used, i.e. x.x.x.4. 1530 1531In the guest Windows OS, the line: 1532@example 153310.0.2.4 smbserver 1534@end example 1535must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 1536or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 1537 1538Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 1539 1540Note that a SAMBA server must be installed on the host OS. 1541QEMU was tested successfully with smbd versions from Red Hat 9, 1542Fedora Core 3 and OpenSUSE 11.x. 1543 1544@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 1545Redirect incoming TCP or UDP connections to the host port @var{hostport} to 1546the guest IP address @var{guestaddr} on guest port @var{guestport}. If 1547@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 1548given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 1549be bound to a specific host interface. If no connection type is set, TCP is 1550used. This option can be given multiple times. 1551 1552For example, to redirect host X11 connection from screen 1 to guest 1553screen 0, use the following: 1554 1555@example 1556# on the host 1557qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 1558# this host xterm should open in the guest X11 server 1559xterm -display :1 1560@end example 1561 1562To redirect telnet connections from host port 5555 to telnet port on 1563the guest, use the following: 1564 1565@example 1566# on the host 1567qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 1568telnet localhost 5555 1569@end example 1570 1571Then when you use on the host @code{telnet localhost 5555}, you 1572connect to the guest telnet server. 1573 1574@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 1575@item guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 1576Forward guest TCP connections to the IP address @var{server} on port @var{port} 1577to the character device @var{dev} or to a program executed by @var{cmd:command} 1578which gets spawned for each connection. This option can be given multiple times. 1579 1580You can either use a chardev directly and have that one used throughout QEMU's 1581lifetime, like in the following example: 1582 1583@example 1584# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 1585# the guest accesses it 1586qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 1587@end example 1588 1589Or you can execute a command on every TCP connection established by the guest, 1590so that QEMU behaves similar to an inetd process for that virtual server: 1591 1592@example 1593# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 1594# and connect the TCP stream to its stdin/stdout 1595qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 1596@end example 1597 1598@end table 1599 1600Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 1601processed and applied to -net user. Mixing them with the new configuration 1602syntax gives undefined results. Their use for new applications is discouraged 1603as they will be removed from future versions. 1604 1605@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1606@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1607Connect the host TAP network interface @var{name} to VLAN @var{n}. 1608 1609Use the network script @var{file} to configure it and the network script 1610@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 1611automatically provides one. The default network configure script is 1612@file{/etc/qemu-ifup} and the default network deconfigure script is 1613@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 1614to disable script execution. 1615 1616If running QEMU as an unprivileged user, use the network helper 1617@var{helper} to configure the TAP interface. The default network 1618helper executable is @file{/path/to/qemu-bridge-helper}. 1619 1620@option{fd}=@var{h} can be used to specify the handle of an already 1621opened host TAP interface. 1622 1623Examples: 1624 1625@example 1626#launch a QEMU instance with the default network script 1627qemu-system-i386 linux.img -net nic -net tap 1628@end example 1629 1630@example 1631#launch a QEMU instance with two NICs, each one connected 1632#to a TAP device 1633qemu-system-i386 linux.img \ 1634 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 1635 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 1636@end example 1637 1638@example 1639#launch a QEMU instance with the default network helper to 1640#connect a TAP device to bridge br0 1641qemu-system-i386 linux.img \ 1642 -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 1643@end example 1644 1645@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 1646@item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 1647Connect a host TAP network interface to a host bridge device. 1648 1649Use the network helper @var{helper} to configure the TAP interface and 1650attach it to the bridge. The default network helper executable is 1651@file{/path/to/qemu-bridge-helper} and the default bridge 1652device is @file{br0}. 1653 1654Examples: 1655 1656@example 1657#launch a QEMU instance with the default network helper to 1658#connect a TAP device to bridge br0 1659qemu-system-i386 linux.img -net bridge -net nic,model=virtio 1660@end example 1661 1662@example 1663#launch a QEMU instance with the default network helper to 1664#connect a TAP device to bridge qemubr0 1665qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 1666@end example 1667 1668@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1669@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1670 1671Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 1672machine using a TCP socket connection. If @option{listen} is 1673specified, QEMU waits for incoming connections on @var{port} 1674(@var{host} is optional). @option{connect} is used to connect to 1675another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 1676specifies an already opened TCP socket. 1677 1678Example: 1679@example 1680# launch a first QEMU instance 1681qemu-system-i386 linux.img \ 1682 -net nic,macaddr=52:54:00:12:34:56 \ 1683 -net socket,listen=:1234 1684# connect the VLAN 0 of this instance to the VLAN 0 1685# of the first instance 1686qemu-system-i386 linux.img \ 1687 -net nic,macaddr=52:54:00:12:34:57 \ 1688 -net socket,connect=127.0.0.1:1234 1689@end example 1690 1691@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1692@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1693 1694Create a VLAN @var{n} shared with another QEMU virtual 1695machines using a UDP multicast socket, effectively making a bus for 1696every QEMU with same multicast address @var{maddr} and @var{port}. 1697NOTES: 1698@enumerate 1699@item 1700Several QEMU can be running on different hosts and share same bus (assuming 1701correct multicast setup for these hosts). 1702@item 1703mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 1704@url{http://user-mode-linux.sf.net}. 1705@item 1706Use @option{fd=h} to specify an already opened UDP multicast socket. 1707@end enumerate 1708 1709Example: 1710@example 1711# launch one QEMU instance 1712qemu-system-i386 linux.img \ 1713 -net nic,macaddr=52:54:00:12:34:56 \ 1714 -net socket,mcast=230.0.0.1:1234 1715# launch another QEMU instance on same "bus" 1716qemu-system-i386 linux.img \ 1717 -net nic,macaddr=52:54:00:12:34:57 \ 1718 -net socket,mcast=230.0.0.1:1234 1719# launch yet another QEMU instance on same "bus" 1720qemu-system-i386 linux.img \ 1721 -net nic,macaddr=52:54:00:12:34:58 \ 1722 -net socket,mcast=230.0.0.1:1234 1723@end example 1724 1725Example (User Mode Linux compat.): 1726@example 1727# launch QEMU instance (note mcast address selected 1728# is UML's default) 1729qemu-system-i386 linux.img \ 1730 -net nic,macaddr=52:54:00:12:34:56 \ 1731 -net socket,mcast=239.192.168.1:1102 1732# launch UML 1733/path/to/linux ubd0=/path/to/root_fs eth0=mcast 1734@end example 1735 1736Example (send packets from host's 1.2.3.4): 1737@example 1738qemu-system-i386 linux.img \ 1739 -net nic,macaddr=52:54:00:12:34:56 \ 1740 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 1741@end example 1742 1743@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 1744@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 1745Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 1746listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 1747and MODE @var{octalmode} to change default ownership and permissions for 1748communication port. This option is only available if QEMU has been compiled 1749with vde support enabled. 1750 1751Example: 1752@example 1753# launch vde switch 1754vde_switch -F -sock /tmp/myswitch 1755# launch QEMU instance 1756qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 1757@end example 1758 1759@item -netdev hubport,id=@var{id},hubid=@var{hubid} 1760 1761Create a hub port on QEMU "vlan" @var{hubid}. 1762 1763The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 1764netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 1765required hub automatically. 1766 1767@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 1768Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 1769At most @var{len} bytes (64k by default) per packet are stored. The file format is 1770libpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 1771 1772@item -net none 1773Indicate that no network devices should be configured. It is used to 1774override the default configuration (@option{-net nic -net user}) which 1775is activated if no @option{-net} options are provided. 1776ETEXI 1777 1778STEXI 1779@end table 1780ETEXI 1781DEFHEADING() 1782 1783DEFHEADING(Character device options:) 1784STEXI 1785 1786The general form of a character device option is: 1787@table @option 1788ETEXI 1789 1790DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 1791 "-chardev null,id=id[,mux=on|off]\n" 1792 "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n" 1793 " [,server][,nowait][,telnet][,mux=on|off] (tcp)\n" 1794 "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n" 1795 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 1796 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 1797 "-chardev msmouse,id=id[,mux=on|off]\n" 1798 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 1799 " [,mux=on|off]\n" 1800 "-chardev ringbuf,id=id[,size=size]\n" 1801 "-chardev file,id=id,path=path[,mux=on|off]\n" 1802 "-chardev pipe,id=id,path=path[,mux=on|off]\n" 1803#ifdef _WIN32 1804 "-chardev console,id=id[,mux=on|off]\n" 1805 "-chardev serial,id=id,path=path[,mux=on|off]\n" 1806#else 1807 "-chardev pty,id=id[,mux=on|off]\n" 1808 "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n" 1809#endif 1810#ifdef CONFIG_BRLAPI 1811 "-chardev braille,id=id[,mux=on|off]\n" 1812#endif 1813#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 1814 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 1815 "-chardev serial,id=id,path=path[,mux=on|off]\n" 1816 "-chardev tty,id=id,path=path[,mux=on|off]\n" 1817#endif 1818#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 1819 "-chardev parallel,id=id,path=path[,mux=on|off]\n" 1820 "-chardev parport,id=id,path=path[,mux=on|off]\n" 1821#endif 1822#if defined(CONFIG_SPICE) 1823 "-chardev spicevmc,id=id,name=name[,debug=debug]\n" 1824 "-chardev spiceport,id=id,name=name[,debug=debug]\n" 1825#endif 1826 , QEMU_ARCH_ALL 1827) 1828 1829STEXI 1830@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 1831@findex -chardev 1832Backend is one of: 1833@option{null}, 1834@option{socket}, 1835@option{udp}, 1836@option{msmouse}, 1837@option{vc}, 1838@option{ringbuf}, 1839@option{file}, 1840@option{pipe}, 1841@option{console}, 1842@option{serial}, 1843@option{pty}, 1844@option{stdio}, 1845@option{braille}, 1846@option{tty}, 1847@option{parallel}, 1848@option{parport}, 1849@option{spicevmc}. 1850@option{spiceport}. 1851The specific backend will determine the applicable options. 1852 1853All devices must have an id, which can be any string up to 127 characters long. 1854It is used to uniquely identify this device in other command line directives. 1855 1856A character device may be used in multiplexing mode by multiple front-ends. 1857The key sequence of @key{Control-a} and @key{c} will rotate the input focus 1858between attached front-ends. Specify @option{mux=on} to enable this mode. 1859 1860Options to each backend are described below. 1861 1862@item -chardev null ,id=@var{id} 1863A void device. This device will not emit any data, and will drop any data it 1864receives. The null backend does not take any options. 1865 1866@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] 1867 1868Create a two-way stream socket, which can be either a TCP or a unix socket. A 1869unix socket will be created if @option{path} is specified. Behaviour is 1870undefined if TCP options are specified for a unix socket. 1871 1872@option{server} specifies that the socket shall be a listening socket. 1873 1874@option{nowait} specifies that QEMU should not block waiting for a client to 1875connect to a listening socket. 1876 1877@option{telnet} specifies that traffic on the socket should interpret telnet 1878escape sequences. 1879 1880TCP and unix socket options are given below: 1881 1882@table @option 1883 1884@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 1885 1886@option{host} for a listening socket specifies the local address to be bound. 1887For a connecting socket species the remote host to connect to. @option{host} is 1888optional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 1889 1890@option{port} for a listening socket specifies the local port to be bound. For a 1891connecting socket specifies the port on the remote host to connect to. 1892@option{port} can be given as either a port number or a service name. 1893@option{port} is required. 1894 1895@option{to} is only relevant to listening sockets. If it is specified, and 1896@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 1897to and including @option{to} until it succeeds. @option{to} must be specified 1898as a port number. 1899 1900@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 1901If neither is specified the socket may use either protocol. 1902 1903@option{nodelay} disables the Nagle algorithm. 1904 1905@item unix options: path=@var{path} 1906 1907@option{path} specifies the local path of the unix socket. @option{path} is 1908required. 1909 1910@end table 1911 1912@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 1913 1914Sends all traffic from the guest to a remote host over UDP. 1915 1916@option{host} specifies the remote host to connect to. If not specified it 1917defaults to @code{localhost}. 1918 1919@option{port} specifies the port on the remote host to connect to. @option{port} 1920is required. 1921 1922@option{localaddr} specifies the local address to bind to. If not specified it 1923defaults to @code{0.0.0.0}. 1924 1925@option{localport} specifies the local port to bind to. If not specified any 1926available local port will be used. 1927 1928@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 1929If neither is specified the device may use either protocol. 1930 1931@item -chardev msmouse ,id=@var{id} 1932 1933Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 1934take any options. 1935 1936@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 1937 1938Connect to a QEMU text console. @option{vc} may optionally be given a specific 1939size. 1940 1941@option{width} and @option{height} specify the width and height respectively of 1942the console, in pixels. 1943 1944@option{cols} and @option{rows} specify that the console be sized to fit a text 1945console with the given dimensions. 1946 1947@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 1948 1949Create a ring buffer with fixed size @option{size}. 1950@var{size} must be a power of two, and defaults to @code{64K}). 1951 1952@item -chardev file ,id=@var{id} ,path=@var{path} 1953 1954Log all traffic received from the guest to a file. 1955 1956@option{path} specifies the path of the file to be opened. This file will be 1957created if it does not already exist, and overwritten if it does. @option{path} 1958is required. 1959 1960@item -chardev pipe ,id=@var{id} ,path=@var{path} 1961 1962Create a two-way connection to the guest. The behaviour differs slightly between 1963Windows hosts and other hosts: 1964 1965On Windows, a single duplex pipe will be created at 1966@file{\\.pipe\@option{path}}. 1967 1968On other hosts, 2 pipes will be created called @file{@option{path}.in} and 1969@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 1970received by the guest. Data written by the guest can be read from 1971@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 1972be present. 1973 1974@option{path} forms part of the pipe path as described above. @option{path} is 1975required. 1976 1977@item -chardev console ,id=@var{id} 1978 1979Send traffic from the guest to QEMU's standard output. @option{console} does not 1980take any options. 1981 1982@option{console} is only available on Windows hosts. 1983 1984@item -chardev serial ,id=@var{id} ,path=@option{path} 1985 1986Send traffic from the guest to a serial device on the host. 1987 1988On Unix hosts serial will actually accept any tty device, 1989not only serial lines. 1990 1991@option{path} specifies the name of the serial device to open. 1992 1993@item -chardev pty ,id=@var{id} 1994 1995Create a new pseudo-terminal on the host and connect to it. @option{pty} does 1996not take any options. 1997 1998@option{pty} is not available on Windows hosts. 1999 2000@item -chardev stdio ,id=@var{id} [,signal=on|off] 2001Connect to standard input and standard output of the QEMU process. 2002 2003@option{signal} controls if signals are enabled on the terminal, that includes 2004exiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2005default, use @option{signal=off} to disable it. 2006 2007@option{stdio} is not available on Windows hosts. 2008 2009@item -chardev braille ,id=@var{id} 2010 2011Connect to a local BrlAPI server. @option{braille} does not take any options. 2012 2013@item -chardev tty ,id=@var{id} ,path=@var{path} 2014 2015@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2016DragonFlyBSD hosts. It is an alias for @option{serial}. 2017 2018@option{path} specifies the path to the tty. @option{path} is required. 2019 2020@item -chardev parallel ,id=@var{id} ,path=@var{path} 2021@item -chardev parport ,id=@var{id} ,path=@var{path} 2022 2023@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 2024 2025Connect to a local parallel port. 2026 2027@option{path} specifies the path to the parallel port device. @option{path} is 2028required. 2029 2030@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2031 2032@option{spicevmc} is only available when spice support is built in. 2033 2034@option{debug} debug level for spicevmc 2035 2036@option{name} name of spice channel to connect to 2037 2038Connect to a spice virtual machine channel, such as vdiport. 2039 2040@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2041 2042@option{spiceport} is only available when spice support is built in. 2043 2044@option{debug} debug level for spicevmc 2045 2046@option{name} name of spice port to connect to 2047 2048Connect to a spice port, allowing a Spice client to handle the traffic 2049identified by a name (preferably a fqdn). 2050ETEXI 2051 2052STEXI 2053@end table 2054ETEXI 2055DEFHEADING() 2056 2057DEFHEADING(Device URL Syntax:) 2058STEXI 2059 2060In addition to using normal file images for the emulated storage devices, 2061QEMU can also use networked resources such as iSCSI devices. These are 2062specified using a special URL syntax. 2063 2064@table @option 2065@item iSCSI 2066iSCSI support allows QEMU to access iSCSI resources directly and use as 2067images for the guest storage. Both disk and cdrom images are supported. 2068 2069Syntax for specifying iSCSI LUNs is 2070``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 2071 2072By default qemu will use the iSCSI initiator-name 2073'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 2074line or a configuration file. 2075 2076 2077Example (without authentication): 2078@example 2079qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2080 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2081 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 2082@end example 2083 2084Example (CHAP username/password via URL): 2085@example 2086qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 2087@end example 2088 2089Example (CHAP username/password via environment variables): 2090@example 2091LIBISCSI_CHAP_USERNAME="user" \ 2092LIBISCSI_CHAP_PASSWORD="password" \ 2093qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 2094@end example 2095 2096iSCSI support is an optional feature of QEMU and only available when 2097compiled and linked against libiscsi. 2098ETEXI 2099DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2100 "-iscsi [user=user][,password=password]\n" 2101 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 2102 " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 2103 " iSCSI session parameters\n", QEMU_ARCH_ALL) 2104STEXI 2105 2106iSCSI parameters such as username and password can also be specified via 2107a configuration file. See qemu-doc for more information and examples. 2108 2109@item NBD 2110QEMU supports NBD (Network Block Devices) both using TCP protocol as well 2111as Unix Domain Sockets. 2112 2113Syntax for specifying a NBD device using TCP 2114``nbd:<server-ip>:<port>[:exportname=<export>]'' 2115 2116Syntax for specifying a NBD device using Unix Domain Sockets 2117``nbd:unix:<domain-socket>[:exportname=<export>]'' 2118 2119 2120Example for TCP 2121@example 2122qemu-system-i386 --drive file=nbd:192.0.2.1:30000 2123@end example 2124 2125Example for Unix Domain Sockets 2126@example 2127qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 2128@end example 2129 2130@item SSH 2131QEMU supports SSH (Secure Shell) access to remote disks. 2132 2133Examples: 2134@example 2135qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 2136qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 2137@end example 2138 2139Currently authentication must be done using ssh-agent. Other 2140authentication methods may be supported in future. 2141 2142@item Sheepdog 2143Sheepdog is a distributed storage system for QEMU. 2144QEMU supports using either local sheepdog devices or remote networked 2145devices. 2146 2147Syntax for specifying a sheepdog device 2148@example 2149sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 2150@end example 2151 2152Example 2153@example 2154qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2155@end example 2156 2157See also @url{http://http://www.osrg.net/sheepdog/}. 2158 2159@item GlusterFS 2160GlusterFS is an user space distributed file system. 2161QEMU supports the use of GlusterFS volumes for hosting VM disk images using 2162TCP, Unix Domain Sockets and RDMA transport protocols. 2163 2164Syntax for specifying a VM disk image on GlusterFS volume is 2165@example 2166gluster[+transport]://[server[:port]]/volname/image[?socket=...] 2167@end example 2168 2169 2170Example 2171@example 2172qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img 2173@end example 2174 2175See also @url{http://www.gluster.org}. 2176ETEXI 2177 2178STEXI 2179@end table 2180ETEXI 2181 2182DEFHEADING(Bluetooth(R) options:) 2183STEXI 2184@table @option 2185ETEXI 2186 2187DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 2188 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 2189 "-bt hci,host[:id]\n" \ 2190 " use host's HCI with the given name\n" \ 2191 "-bt hci[,vlan=n]\n" \ 2192 " emulate a standard HCI in virtual scatternet 'n'\n" \ 2193 "-bt vhci[,vlan=n]\n" \ 2194 " add host computer to virtual scatternet 'n' using VHCI\n" \ 2195 "-bt device:dev[,vlan=n]\n" \ 2196 " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2197 QEMU_ARCH_ALL) 2198STEXI 2199@item -bt hci[...] 2200@findex -bt 2201Defines the function of the corresponding Bluetooth HCI. -bt options 2202are matched with the HCIs present in the chosen machine type. For 2203example when emulating a machine with only one HCI built into it, only 2204the first @code{-bt hci[...]} option is valid and defines the HCI's 2205logic. The Transport Layer is decided by the machine type. Currently 2206the machines @code{n800} and @code{n810} have one HCI and all other 2207machines have none. 2208 2209@anchor{bt-hcis} 2210The following three types are recognized: 2211 2212@table @option 2213@item -bt hci,null 2214(default) The corresponding Bluetooth HCI assumes no internal logic 2215and will not respond to any HCI commands or emit events. 2216 2217@item -bt hci,host[:@var{id}] 2218(@code{bluez} only) The corresponding HCI passes commands / events 2219to / from the physical HCI identified by the name @var{id} (default: 2220@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 2221capable systems like Linux. 2222 2223@item -bt hci[,vlan=@var{n}] 2224Add a virtual, standard HCI that will participate in the Bluetooth 2225scatternet @var{n} (default @code{0}). Similarly to @option{-net} 2226VLANs, devices inside a bluetooth network @var{n} can only communicate 2227with other devices in the same network (scatternet). 2228@end table 2229 2230@item -bt vhci[,vlan=@var{n}] 2231(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 2232to the host bluetooth stack instead of to the emulated target. This 2233allows the host and target machines to participate in a common scatternet 2234and communicate. Requires the Linux @code{vhci} driver installed. Can 2235be used as following: 2236 2237@example 2238qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 2239@end example 2240 2241@item -bt device:@var{dev}[,vlan=@var{n}] 2242Emulate a bluetooth device @var{dev} and place it in network @var{n} 2243(default @code{0}). QEMU can only emulate one type of bluetooth devices 2244currently: 2245 2246@table @option 2247@item keyboard 2248Virtual wireless keyboard implementing the HIDP bluetooth profile. 2249@end table 2250ETEXI 2251 2252STEXI 2253@end table 2254ETEXI 2255DEFHEADING() 2256 2257#ifdef CONFIG_TPM 2258DEFHEADING(TPM device options:) 2259 2260DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 2261 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 2262 " use path to provide path to a character device; default is /dev/tpm0\n" 2263 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 2264 " not provided it will be searched for in /sys/class/misc/tpm?/device\n", 2265 QEMU_ARCH_ALL) 2266STEXI 2267 2268The general form of a TPM device option is: 2269@table @option 2270 2271@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 2272@findex -tpmdev 2273Backend type must be: 2274@option{passthrough}. 2275 2276The specific backend type will determine the applicable options. 2277The @code{-tpmdev} option creates the TPM backend and requires a 2278@code{-device} option that specifies the TPM frontend interface model. 2279 2280Options to each backend are described below. 2281 2282Use 'help' to print all available TPM backend types. 2283@example 2284qemu -tpmdev help 2285@end example 2286 2287@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} 2288 2289(Linux-host only) Enable access to the host's TPM using the passthrough 2290driver. 2291 2292@option{path} specifies the path to the host's TPM device, i.e., on 2293a Linux host this would be @code{/dev/tpm0}. 2294@option{path} is optional and by default @code{/dev/tpm0} is used. 2295 2296@option{cancel-path} specifies the path to the host TPM device's sysfs 2297entry allowing for cancellation of an ongoing TPM command. 2298@option{cancel-path} is optional and by default QEMU will search for the 2299sysfs entry to use. 2300 2301Some notes about using the host's TPM with the passthrough driver: 2302 2303The TPM device accessed by the passthrough driver must not be 2304used by any other application on the host. 2305 2306Since the host's firmware (BIOS/UEFI) has already initialized the TPM, 2307the VM's firmware (BIOS/UEFI) will not be able to initialize the 2308TPM again and may therefore not show a TPM-specific menu that would 2309otherwise allow the user to configure the TPM, e.g., allow the user to 2310enable/disable or activate/deactivate the TPM. 2311Further, if TPM ownership is released from within a VM then the host's TPM 2312will get disabled and deactivated. To enable and activate the 2313TPM again afterwards, the host has to be rebooted and the user is 2314required to enter the firmware's menu to enable and activate the TPM. 2315If the TPM is left disabled and/or deactivated most TPM commands will fail. 2316 2317To create a passthrough TPM use the following two options: 2318@example 2319-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 2320@end example 2321Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by 2322@code{tpmdev=tpm0} in the device option. 2323 2324@end table 2325 2326ETEXI 2327 2328DEFHEADING() 2329 2330#endif 2331 2332DEFHEADING(Linux/Multiboot boot specific:) 2333STEXI 2334 2335When using these options, you can use a given Linux or Multiboot 2336kernel without installing it in the disk image. It can be useful 2337for easier testing of various kernels. 2338 2339@table @option 2340ETEXI 2341 2342DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2343 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 2344STEXI 2345@item -kernel @var{bzImage} 2346@findex -kernel 2347Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel 2348or in multiboot format. 2349ETEXI 2350 2351DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2352 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 2353STEXI 2354@item -append @var{cmdline} 2355@findex -append 2356Use @var{cmdline} as kernel command line 2357ETEXI 2358 2359DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2360 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 2361STEXI 2362@item -initrd @var{file} 2363@findex -initrd 2364Use @var{file} as initial ram disk. 2365 2366@item -initrd "@var{file1} arg=foo,@var{file2}" 2367 2368This syntax is only available with multiboot. 2369 2370Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 2371first module. 2372ETEXI 2373 2374DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2375 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2376STEXI 2377@item -dtb @var{file} 2378@findex -dtb 2379Use @var{file} as a device tree binary (dtb) image and pass it to the kernel 2380on boot. 2381ETEXI 2382 2383STEXI 2384@end table 2385ETEXI 2386DEFHEADING() 2387 2388DEFHEADING(Debug/Expert options:) 2389STEXI 2390@table @option 2391ETEXI 2392 2393DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 2394 "-serial dev redirect the serial port to char device 'dev'\n", 2395 QEMU_ARCH_ALL) 2396STEXI 2397@item -serial @var{dev} 2398@findex -serial 2399Redirect the virtual serial port to host character device 2400@var{dev}. The default device is @code{vc} in graphical mode and 2401@code{stdio} in non graphical mode. 2402 2403This option can be used several times to simulate up to 4 serial 2404ports. 2405 2406Use @code{-serial none} to disable all serial ports. 2407 2408Available character devices are: 2409@table @option 2410@item vc[:@var{W}x@var{H}] 2411Virtual console. Optionally, a width and height can be given in pixel with 2412@example 2413vc:800x600 2414@end example 2415It is also possible to specify width or height in characters: 2416@example 2417vc:80Cx24C 2418@end example 2419@item pty 2420[Linux only] Pseudo TTY (a new PTY is automatically allocated) 2421@item none 2422No device is allocated. 2423@item null 2424void device 2425@item chardev:@var{id} 2426Use a named character device defined with the @code{-chardev} option. 2427@item /dev/XXX 2428[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 2429parameters are set according to the emulated ones. 2430@item /dev/parport@var{N} 2431[Linux only, parallel port only] Use host parallel port 2432@var{N}. Currently SPP and EPP parallel port features can be used. 2433@item file:@var{filename} 2434Write output to @var{filename}. No character can be read. 2435@item stdio 2436[Unix only] standard input/output 2437@item pipe:@var{filename} 2438name pipe @var{filename} 2439@item COM@var{n} 2440[Windows only] Use host serial port @var{n} 2441@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 2442This implements UDP Net Console. 2443When @var{remote_host} or @var{src_ip} are not specified 2444they default to @code{0.0.0.0}. 2445When not using a specified @var{src_port} a random port is automatically chosen. 2446 2447If you just want a simple readonly console you can use @code{netcat} or 2448@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 2449@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 2450will appear in the netconsole session. 2451 2452If you plan to send characters back via netconsole or you want to stop 2453and start QEMU a lot of times, you should have QEMU use the same 2454source port each time by using something like @code{-serial 2455udp::4555@@:4556} to QEMU. Another approach is to use a patched 2456version of netcat which can listen to a TCP port and send and receive 2457characters via udp. If you have a patched version of netcat which 2458activates telnet remote echo and single char transfer, then you can 2459use the following options to step up a netcat redirector to allow 2460telnet on port 5555 to access the QEMU port. 2461@table @code 2462@item QEMU Options: 2463-serial udp::4555@@:4556 2464@item netcat options: 2465-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 2466@item telnet options: 2467localhost 5555 2468@end table 2469 2470@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay] 2471The TCP Net Console has two modes of operation. It can send the serial 2472I/O to a location or wait for a connection from a location. By default 2473the TCP Net Console is sent to @var{host} at the @var{port}. If you use 2474the @var{server} option QEMU will wait for a client socket application 2475to connect to the port before continuing, unless the @code{nowait} 2476option was specified. The @code{nodelay} option disables the Nagle buffering 2477algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only 2478one TCP connection at a time is accepted. You can use @code{telnet} to 2479connect to the corresponding character device. 2480@table @code 2481@item Example to send tcp console to 192.168.0.2 port 4444 2482-serial tcp:192.168.0.2:4444 2483@item Example to listen and wait on port 4444 for connection 2484-serial tcp::4444,server 2485@item Example to not wait and listen on ip 192.168.0.100 port 4444 2486-serial tcp:192.168.0.100:4444,server,nowait 2487@end table 2488 2489@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 2490The telnet protocol is used instead of raw tcp sockets. The options 2491work the same as if you had specified @code{-serial tcp}. The 2492difference is that the port acts like a telnet server or client using 2493telnet option negotiation. This will also allow you to send the 2494MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 2495sequence. Typically in unix telnet you do it with Control-] and then 2496type "send break" followed by pressing the enter key. 2497 2498@item unix:@var{path}[,server][,nowait] 2499A unix domain socket is used instead of a tcp socket. The option works the 2500same as if you had specified @code{-serial tcp} except the unix domain socket 2501@var{path} is used for connections. 2502 2503@item mon:@var{dev_string} 2504This is a special option to allow the monitor to be multiplexed onto 2505another serial port. The monitor is accessed with key sequence of 2506@key{Control-a} and then pressing @key{c}. 2507@var{dev_string} should be any one of the serial devices specified 2508above. An example to multiplex the monitor onto a telnet server 2509listening on port 4444 would be: 2510@table @code 2511@item -serial mon:telnet::4444,server,nowait 2512@end table 2513When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 2514QEMU any more but will be passed to the guest instead. 2515 2516@item braille 2517Braille device. This will use BrlAPI to display the braille output on a real 2518or fake device. 2519 2520@item msmouse 2521Three button serial mouse. Configure the guest to use Microsoft protocol. 2522@end table 2523ETEXI 2524 2525DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 2526 "-parallel dev redirect the parallel port to char device 'dev'\n", 2527 QEMU_ARCH_ALL) 2528STEXI 2529@item -parallel @var{dev} 2530@findex -parallel 2531Redirect the virtual parallel port to host device @var{dev} (same 2532devices as the serial port). On Linux hosts, @file{/dev/parportN} can 2533be used to use hardware devices connected on the corresponding host 2534parallel port. 2535 2536This option can be used several times to simulate up to 3 parallel 2537ports. 2538 2539Use @code{-parallel none} to disable all parallel ports. 2540ETEXI 2541 2542DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 2543 "-monitor dev redirect the monitor to char device 'dev'\n", 2544 QEMU_ARCH_ALL) 2545STEXI 2546@item -monitor @var{dev} 2547@findex -monitor 2548Redirect the monitor to host device @var{dev} (same devices as the 2549serial port). 2550The default device is @code{vc} in graphical mode and @code{stdio} in 2551non graphical mode. 2552Use @code{-monitor none} to disable the default monitor. 2553ETEXI 2554DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 2555 "-qmp dev like -monitor but opens in 'control' mode\n", 2556 QEMU_ARCH_ALL) 2557STEXI 2558@item -qmp @var{dev} 2559@findex -qmp 2560Like -monitor but opens in 'control' mode. 2561ETEXI 2562 2563DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 2564 "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL) 2565STEXI 2566@item -mon [chardev=]name[,mode=readline|control][,default] 2567@findex -mon 2568Setup monitor on chardev @var{name}. 2569ETEXI 2570 2571DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 2572 "-debugcon dev redirect the debug console to char device 'dev'\n", 2573 QEMU_ARCH_ALL) 2574STEXI 2575@item -debugcon @var{dev} 2576@findex -debugcon 2577Redirect the debug console to host device @var{dev} (same devices as the 2578serial port). The debug console is an I/O port which is typically port 25790xe9; writing to that I/O port sends output to this device. 2580The default device is @code{vc} in graphical mode and @code{stdio} in 2581non graphical mode. 2582ETEXI 2583 2584DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 2585 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 2586STEXI 2587@item -pidfile @var{file} 2588@findex -pidfile 2589Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 2590from a script. 2591ETEXI 2592 2593DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 2594 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 2595STEXI 2596@item -singlestep 2597@findex -singlestep 2598Run the emulation in single step mode. 2599ETEXI 2600 2601DEF("S", 0, QEMU_OPTION_S, \ 2602 "-S freeze CPU at startup (use 'c' to start execution)\n", 2603 QEMU_ARCH_ALL) 2604STEXI 2605@item -S 2606@findex -S 2607Do not start CPU at startup (you must type 'c' in the monitor). 2608ETEXI 2609 2610DEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 2611 "-realtime [mlock=on|off]\n" 2612 " run qemu with realtime features\n" 2613 " mlock=on|off controls mlock support (default: on)\n", 2614 QEMU_ARCH_ALL) 2615STEXI 2616@item -realtime mlock=on|off 2617@findex -realtime 2618Run qemu with realtime features. 2619mlocking qemu and guest memory can be enabled via @option{mlock=on} 2620(enabled by default). 2621ETEXI 2622 2623DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 2624 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 2625STEXI 2626@item -gdb @var{dev} 2627@findex -gdb 2628Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 2629connections will likely be TCP-based, but also UDP, pseudo TTY, or even 2630stdio are reasonable use case. The latter is allowing to start QEMU from 2631within gdb and establish the connection via a pipe: 2632@example 2633(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 2634@end example 2635ETEXI 2636 2637DEF("s", 0, QEMU_OPTION_s, \ 2638 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 2639 QEMU_ARCH_ALL) 2640STEXI 2641@item -s 2642@findex -s 2643Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 2644(@pxref{gdb_usage}). 2645ETEXI 2646 2647DEF("d", HAS_ARG, QEMU_OPTION_d, \ 2648 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 2649 QEMU_ARCH_ALL) 2650STEXI 2651@item -d @var{item1}[,...] 2652@findex -d 2653Enable logging of specified items. Use '-d help' for a list of log items. 2654ETEXI 2655 2656DEF("D", HAS_ARG, QEMU_OPTION_D, \ 2657 "-D logfile output log to logfile (default stderr)\n", 2658 QEMU_ARCH_ALL) 2659STEXI 2660@item -D @var{logfile} 2661@findex -D 2662Output log in @var{logfile} instead of to stderr 2663ETEXI 2664 2665DEF("L", HAS_ARG, QEMU_OPTION_L, \ 2666 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 2667 QEMU_ARCH_ALL) 2668STEXI 2669@item -L @var{path} 2670@findex -L 2671Set the directory for the BIOS, VGA BIOS and keymaps. 2672ETEXI 2673 2674DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 2675 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 2676STEXI 2677@item -bios @var{file} 2678@findex -bios 2679Set the filename for the BIOS. 2680ETEXI 2681 2682DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 2683 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 2684STEXI 2685@item -enable-kvm 2686@findex -enable-kvm 2687Enable KVM full virtualization support. This option is only available 2688if KVM support is enabled when compiling. 2689ETEXI 2690 2691DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 2692 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 2693DEF("xen-create", 0, QEMU_OPTION_xen_create, 2694 "-xen-create create domain using xen hypercalls, bypassing xend\n" 2695 " warning: should not be used when xend is in use\n", 2696 QEMU_ARCH_ALL) 2697DEF("xen-attach", 0, QEMU_OPTION_xen_attach, 2698 "-xen-attach attach to existing xen domain\n" 2699 " xend will use this when starting QEMU\n", 2700 QEMU_ARCH_ALL) 2701STEXI 2702@item -xen-domid @var{id} 2703@findex -xen-domid 2704Specify xen guest domain @var{id} (XEN only). 2705@item -xen-create 2706@findex -xen-create 2707Create domain using xen hypercalls, bypassing xend. 2708Warning: should not be used when xend is in use (XEN only). 2709@item -xen-attach 2710@findex -xen-attach 2711Attach to existing xen domain. 2712xend will use this when starting QEMU (XEN only). 2713ETEXI 2714 2715DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 2716 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 2717STEXI 2718@item -no-reboot 2719@findex -no-reboot 2720Exit instead of rebooting. 2721ETEXI 2722 2723DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 2724 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 2725STEXI 2726@item -no-shutdown 2727@findex -no-shutdown 2728Don't exit QEMU on guest shutdown, but instead only stop the emulation. 2729This allows for instance switching to monitor to commit changes to the 2730disk image. 2731ETEXI 2732 2733DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 2734 "-loadvm [tag|id]\n" \ 2735 " start right away with a saved state (loadvm in monitor)\n", 2736 QEMU_ARCH_ALL) 2737STEXI 2738@item -loadvm @var{file} 2739@findex -loadvm 2740Start right away with a saved state (@code{loadvm} in monitor) 2741ETEXI 2742 2743#ifndef _WIN32 2744DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 2745 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 2746#endif 2747STEXI 2748@item -daemonize 2749@findex -daemonize 2750Daemonize the QEMU process after initialization. QEMU will not detach from 2751standard IO until it is ready to receive connections on any of its devices. 2752This option is a useful way for external programs to launch QEMU without having 2753to cope with initialization race conditions. 2754ETEXI 2755 2756DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 2757 "-option-rom rom load a file, rom, into the option ROM space\n", 2758 QEMU_ARCH_ALL) 2759STEXI 2760@item -option-rom @var{file} 2761@findex -option-rom 2762Load the contents of @var{file} as an option ROM. 2763This option is useful to load things like EtherBoot. 2764ETEXI 2765 2766DEF("clock", HAS_ARG, QEMU_OPTION_clock, \ 2767 "-clock force the use of the given methods for timer alarm.\n" \ 2768 " To see what timers are available use '-clock help'\n", 2769 QEMU_ARCH_ALL) 2770STEXI 2771@item -clock @var{method} 2772@findex -clock 2773Force the use of the given methods for timer alarm. To see what timers 2774are available use @code{-clock help}. 2775ETEXI 2776 2777HXCOMM Options deprecated by -rtc 2778DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 2779DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 2780 2781DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 2782 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 2783 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 2784 QEMU_ARCH_ALL) 2785 2786STEXI 2787 2788@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 2789@findex -rtc 2790Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 2791UTC or local time, respectively. @code{localtime} is required for correct date in 2792MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 2793format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 2794 2795By default the RTC is driven by the host system time. This allows to use the 2796RTC as accurate reference clock inside the guest, specifically if the host 2797time is smoothly following an accurate external reference clock, e.g. via NTP. 2798If you want to isolate the guest time from the host, you can set @option{clock} 2799to @code{rt} instead. To even prevent it from progressing during suspension, 2800you can set it to @code{vm}. 2801 2802Enable @option{driftfix} (i386 targets only) if you experience time drift problems, 2803specifically with Windows' ACPI HAL. This option will try to figure out how 2804many timer interrupts were not processed by the Windows guest and will 2805re-inject them. 2806ETEXI 2807 2808DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 2809 "-icount [N|auto]\n" \ 2810 " enable virtual instruction counter with 2^N clock ticks per\n" \ 2811 " instruction\n", QEMU_ARCH_ALL) 2812STEXI 2813@item -icount [@var{N}|auto] 2814@findex -icount 2815Enable virtual instruction counter. The virtual cpu will execute one 2816instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 2817then the virtual cpu speed will be automatically adjusted to keep virtual 2818time within a few seconds of real time. 2819 2820Note that while this option can give deterministic behavior, it does not 2821provide cycle accurate emulation. Modern CPUs contain superscalar out of 2822order cores with complex cache hierarchies. The number of instructions 2823executed often has little or no correlation with actual performance. 2824ETEXI 2825 2826DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 2827 "-watchdog i6300esb|ib700\n" \ 2828 " enable virtual hardware watchdog [default=none]\n", 2829 QEMU_ARCH_ALL) 2830STEXI 2831@item -watchdog @var{model} 2832@findex -watchdog 2833Create a virtual hardware watchdog device. Once enabled (by a guest 2834action), the watchdog must be periodically polled by an agent inside 2835the guest or else the guest will be restarted. 2836 2837The @var{model} is the model of hardware watchdog to emulate. Choices 2838for model are: @code{ib700} (iBASE 700) which is a very simple ISA 2839watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O 2840controller hub) which is a much more featureful PCI-based dual-timer 2841watchdog. Choose a model for which your guest has drivers. 2842 2843Use @code{-watchdog help} to list available hardware models. Only one 2844watchdog can be enabled for a guest. 2845ETEXI 2846 2847DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 2848 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 2849 " action when watchdog fires [default=reset]\n", 2850 QEMU_ARCH_ALL) 2851STEXI 2852@item -watchdog-action @var{action} 2853@findex -watchdog-action 2854 2855The @var{action} controls what QEMU will do when the watchdog timer 2856expires. 2857The default is 2858@code{reset} (forcefully reset the guest). 2859Other possible actions are: 2860@code{shutdown} (attempt to gracefully shutdown the guest), 2861@code{poweroff} (forcefully poweroff the guest), 2862@code{pause} (pause the guest), 2863@code{debug} (print a debug message and continue), or 2864@code{none} (do nothing). 2865 2866Note that the @code{shutdown} action requires that the guest responds 2867to ACPI signals, which it may not be able to do in the sort of 2868situations where the watchdog would have expired, and thus 2869@code{-watchdog-action shutdown} is not recommended for production use. 2870 2871Examples: 2872 2873@table @code 2874@item -watchdog i6300esb -watchdog-action pause 2875@item -watchdog ib700 2876@end table 2877ETEXI 2878 2879DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 2880 "-echr chr set terminal escape character instead of ctrl-a\n", 2881 QEMU_ARCH_ALL) 2882STEXI 2883 2884@item -echr @var{numeric_ascii_value} 2885@findex -echr 2886Change the escape character used for switching to the monitor when using 2887monitor and serial sharing. The default is @code{0x01} when using the 2888@code{-nographic} option. @code{0x01} is equal to pressing 2889@code{Control-a}. You can select a different character from the ascii 2890control keys where 1 through 26 map to Control-a through Control-z. For 2891instance you could use the either of the following to change the escape 2892character to Control-t. 2893@table @code 2894@item -echr 0x14 2895@item -echr 20 2896@end table 2897ETEXI 2898 2899DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 2900 "-virtioconsole c\n" \ 2901 " set virtio console\n", QEMU_ARCH_ALL) 2902STEXI 2903@item -virtioconsole @var{c} 2904@findex -virtioconsole 2905Set virtio console. 2906 2907This option is maintained for backward compatibility. 2908 2909Please use @code{-device virtconsole} for the new way of invocation. 2910ETEXI 2911 2912DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 2913 "-show-cursor show cursor\n", QEMU_ARCH_ALL) 2914STEXI 2915@item -show-cursor 2916@findex -show-cursor 2917Show cursor. 2918ETEXI 2919 2920DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 2921 "-tb-size n set TB size\n", QEMU_ARCH_ALL) 2922STEXI 2923@item -tb-size @var{n} 2924@findex -tb-size 2925Set TB size. 2926ETEXI 2927 2928DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 2929 "-incoming p prepare for incoming migration, listen on port p\n", 2930 QEMU_ARCH_ALL) 2931STEXI 2932@item -incoming @var{port} 2933@findex -incoming 2934Prepare for incoming migration, listen on @var{port}. 2935ETEXI 2936 2937DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 2938 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 2939STEXI 2940@item -nodefaults 2941@findex -nodefaults 2942Don't create default devices. Normally, QEMU sets the default devices like serial 2943port, parallel port, virtual console, monitor device, VGA adapter, floppy and 2944CD-ROM drive and others. The @code{-nodefaults} option will disable all those 2945default devices. 2946ETEXI 2947 2948#ifndef _WIN32 2949DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 2950 "-chroot dir chroot to dir just before starting the VM\n", 2951 QEMU_ARCH_ALL) 2952#endif 2953STEXI 2954@item -chroot @var{dir} 2955@findex -chroot 2956Immediately before starting guest execution, chroot to the specified 2957directory. Especially useful in combination with -runas. 2958ETEXI 2959 2960#ifndef _WIN32 2961DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 2962 "-runas user change to user id user just before starting the VM\n", 2963 QEMU_ARCH_ALL) 2964#endif 2965STEXI 2966@item -runas @var{user} 2967@findex -runas 2968Immediately before starting guest execution, drop root privileges, switching 2969to the specified user. 2970ETEXI 2971 2972DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 2973 "-prom-env variable=value\n" 2974 " set OpenBIOS nvram variables\n", 2975 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 2976STEXI 2977@item -prom-env @var{variable}=@var{value} 2978@findex -prom-env 2979Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 2980ETEXI 2981DEF("semihosting", 0, QEMU_OPTION_semihosting, 2982 "-semihosting semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA) 2983STEXI 2984@item -semihosting 2985@findex -semihosting 2986Semihosting mode (ARM, M68K, Xtensa only). 2987ETEXI 2988DEF("old-param", 0, QEMU_OPTION_old_param, 2989 "-old-param old param mode\n", QEMU_ARCH_ARM) 2990STEXI 2991@item -old-param 2992@findex -old-param (ARM) 2993Old param mode (ARM only). 2994ETEXI 2995 2996DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 2997 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n", 2998 QEMU_ARCH_ALL) 2999STEXI 3000@item -sandbox @var{arg} 3001@findex -sandbox 3002Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 3003disable it. The default is 'off'. 3004ETEXI 3005 3006DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3007 "-readconfig <file>\n", QEMU_ARCH_ALL) 3008STEXI 3009@item -readconfig @var{file} 3010@findex -readconfig 3011Read device configuration from @var{file}. This approach is useful when you want to spawn 3012QEMU process with many command line options but you don't want to exceed the command line 3013character limit. 3014ETEXI 3015DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3016 "-writeconfig <file>\n" 3017 " read/write config file\n", QEMU_ARCH_ALL) 3018STEXI 3019@item -writeconfig @var{file} 3020@findex -writeconfig 3021Write device configuration to @var{file}. The @var{file} can be either filename to save 3022command line and device configuration into file or dash @code{-}) character to print the 3023output to stdout. This can be later used as input file for @code{-readconfig} option. 3024ETEXI 3025DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, 3026 "-nodefconfig\n" 3027 " do not load default config files at startup\n", 3028 QEMU_ARCH_ALL) 3029STEXI 3030@item -nodefconfig 3031@findex -nodefconfig 3032Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup. 3033The @code{-nodefconfig} option will prevent QEMU from loading any of those config files. 3034ETEXI 3035DEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3036 "-no-user-config\n" 3037 " do not load user-provided config files at startup\n", 3038 QEMU_ARCH_ALL) 3039STEXI 3040@item -no-user-config 3041@findex -no-user-config 3042The @code{-no-user-config} option makes QEMU not load any of the user-provided 3043config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config 3044files from @var{datadir}. 3045ETEXI 3046DEF("trace", HAS_ARG, QEMU_OPTION_trace, 3047 "-trace [events=<file>][,file=<file>]\n" 3048 " specify tracing options\n", 3049 QEMU_ARCH_ALL) 3050STEXI 3051HXCOMM This line is not accurate, as some sub-options are backend-specific but 3052HXCOMM HX does not support conditional compilation of text. 3053@item -trace [events=@var{file}][,file=@var{file}] 3054@findex -trace 3055 3056Specify tracing options. 3057 3058@table @option 3059@item events=@var{file} 3060Immediately enable events listed in @var{file}. 3061The file must contain one event name (as listed in the @var{trace-events} file) 3062per line. 3063This option is only available if QEMU has been compiled with 3064either @var{simple} or @var{stderr} tracing backend. 3065@item file=@var{file} 3066Log output traces to @var{file}. 3067 3068This option is only available if QEMU has been compiled with 3069the @var{simple} tracing backend. 3070@end table 3071ETEXI 3072 3073HXCOMM Internal use 3074DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 3075DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3076 3077#ifdef __linux__ 3078DEF("enable-fips", 0, QEMU_OPTION_enablefips, 3079 "-enable-fips enable FIPS 140-2 compliance\n", 3080 QEMU_ARCH_ALL) 3081#endif 3082STEXI 3083@item -enable-fips 3084@findex -enable-fips 3085Enable FIPS 140-2 compliance mode. 3086ETEXI 3087 3088HXCOMM Deprecated by -machine accel=tcg property 3089DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3090 3091HXCOMM Deprecated by kvm-pit driver properties 3092DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 3093 "", QEMU_ARCH_I386) 3094 3095HXCOMM Deprecated (ignored) 3096DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 3097 3098HXCOMM Deprecated by -machine kernel_irqchip=on|off property 3099DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 3100 3101HXCOMM Deprecated (ignored) 3102DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 3103 3104DEF("object", HAS_ARG, QEMU_OPTION_object, 3105 "-object TYPENAME[,PROP1=VALUE1,...]\n" 3106 " create an new object of type TYPENAME setting properties\n" 3107 " in the order they are specified. Note that the 'id'\n" 3108 " property must be set. These objects are placed in the\n" 3109 " '/objects' path.\n", 3110 QEMU_ARCH_ALL) 3111STEXI 3112@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3113@findex -object 3114Create an new object of type @var{typename} setting properties 3115in the order they are specified. Note that the 'id' 3116property must be set. These objects are placed in the 3117'/objects' path. 3118ETEXI 3119 3120DEF("msg", HAS_ARG, QEMU_OPTION_msg, 3121 "-msg timestamp[=on|off]\n" 3122 " change the format of messages\n" 3123 " on|off controls leading timestamps (default:on)\n", 3124 QEMU_ARCH_ALL) 3125STEXI 3126@item -msg timestamp[=on|off] 3127@findex -msg 3128prepend a timestamp to each log message.(default:on) 3129ETEXI 3130 3131HXCOMM This is the last statement. Insert new options before this line! 3132STEXI 3133@end table 3134ETEXI 3135
