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