15824d651Sblueswir1HXCOMM Use DEFHEADING() to define headings in both help text and texi 25824d651Sblueswir1HXCOMM Text between STEXI and ETEXI are copied to texi version and 35824d651Sblueswir1HXCOMM discarded from C version 4ad96090aSBlue SwirlHXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to 5ad96090aSBlue SwirlHXCOMM construct option structures, enums and help message for specified 6ad96090aSBlue SwirlHXCOMM architectures. 75824d651Sblueswir1HXCOMM HXCOMM can be used for comments, discarded from both texi and C 85824d651Sblueswir1 943f187a5SPaolo BonziniDEFHEADING(Standard options) 105824d651Sblueswir1STEXI 115824d651Sblueswir1@table @option 125824d651Sblueswir1ETEXI 135824d651Sblueswir1 145824d651Sblueswir1DEF("help", 0, QEMU_OPTION_h, 15ad96090aSBlue Swirl "-h or -help display this help and exit\n", QEMU_ARCH_ALL) 165824d651Sblueswir1STEXI 175824d651Sblueswir1@item -h 186616b2adSStefan Weil@findex -h 195824d651Sblueswir1Display help and exit 205824d651Sblueswir1ETEXI 215824d651Sblueswir1 229bd7e6d9SpbrookDEF("version", 0, QEMU_OPTION_version, 23ad96090aSBlue Swirl "-version display version information and exit\n", QEMU_ARCH_ALL) 249bd7e6d9SpbrookSTEXI 259bd7e6d9Spbrook@item -version 266616b2adSStefan Weil@findex -version 279bd7e6d9SpbrookDisplay version information and exit 289bd7e6d9SpbrookETEXI 299bd7e6d9Spbrook 3080f52a66SJan KiszkaDEF("machine", HAS_ARG, QEMU_OPTION_machine, \ 3180f52a66SJan Kiszka "-machine [type=]name[,prop[=value][,...]]\n" 32585f6036SPeter Maydell " selects emulated machine ('-machine help' for list)\n" 3380f52a66SJan Kiszka " property accel=accel1[:accel2[:...]] selects accelerator\n" 346a48ffaaSJan Kiszka " supported accelerators are kvm, xen, tcg (default: tcg)\n" 3532c18a2dSMatt Gingell " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n" 36d1048befSDon Slutz " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 3796404013SPeter Maydell " kvm_shadow_mem=size of KVM shadow MMU in bytes\n" 388490fc78SLuiz Capitulino " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 39a52a7fdfSLe Tan " mem-merge=on|off controls memory merge support (default: on)\n" 4079814179STiejun Chen " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n" 412eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 429850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4387252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 44902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 45902c053dSGreg Kurz " enforce-config-section=on|off enforce configuration section migration (default=off)\n", 4680f52a66SJan Kiszka QEMU_ARCH_ALL) 475824d651Sblueswir1STEXI 4880f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 4980f52a66SJan Kiszka@findex -machine 50585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 5180f52a66SJan Kiszkaavailable machines. Supported machine properties are: 5280f52a66SJan Kiszka@table @option 5380f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 5480f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 5580f52a66SJan Kiszkakvm, xen, or tcg can be available. By default, tcg is used. If there is more 5680f52a66SJan Kiszkathan one accelerator specified, the next one is used if the previous one fails 5780f52a66SJan Kiszkato initialize. 586a48ffaaSJan Kiszka@item kernel_irqchip=on|off 5932c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 6079814179STiejun Chen@item gfx_passthru=on|off 6179814179STiejun ChenEnables IGD GFX passthrough support for the chosen machine when available. 62d1048befSDon Slutz@item vmport=on|off|auto 63d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 64d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 65d1048befSDon Slutzis on. 6639d6960aSJan Kiszka@item kvm_shadow_mem=size 6739d6960aSJan KiszkaDefines the size of the KVM shadow MMU. 68ddb97f1dSJason Baron@item dump-guest-core=on|off 69ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 708490fc78SLuiz Capitulino@item mem-merge=on|off 718490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 728490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 738490fc78SLuiz Capitulino(enabled by default). 742eb1cd07STony Krowiak@item aes-key-wrap=on|off 752eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 762eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 772eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 782eb1cd07STony Krowiak@item dea-key-wrap=on|off 792eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 802eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 812eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 8287252e1bSXiao Guangrong@item nvdimm=on|off 8387252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 8480f52a66SJan Kiszka@end table 855824d651Sblueswir1ETEXI 865824d651Sblueswir1 8780f52a66SJan KiszkaHXCOMM Deprecated by -machine 8880f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 8980f52a66SJan Kiszka 905824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 91585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 925824d651Sblueswir1STEXI 935824d651Sblueswir1@item -cpu @var{model} 946616b2adSStefan Weil@findex -cpu 95585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 965824d651Sblueswir1ETEXI 975824d651Sblueswir1 988d4e9146SKONRAD FredericDEF("accel", HAS_ARG, QEMU_OPTION_accel, 998d4e9146SKONRAD Frederic "-accel [accel=]accelerator[,thread=single|multi]\n" 1008d4e9146SKONRAD Frederic " select accelerator ('-accel help for list')\n" 1018d4e9146SKONRAD Frederic " thread=single|multi (enable multi-threaded TCG)", QEMU_ARCH_ALL) 1028d4e9146SKONRAD FredericSTEXI 1038d4e9146SKONRAD Frederic@item -accel @var{name}[,prop=@var{value}[,...]] 1048d4e9146SKONRAD Frederic@findex -accel 1058d4e9146SKONRAD FredericThis is used to enable an accelerator. Depending on the target architecture, 1068d4e9146SKONRAD Frederickvm, xen, or tcg can be available. By default, tcg is used. If there is more 1078d4e9146SKONRAD Fredericthan one accelerator specified, the next one is used if the previous one fails 1088d4e9146SKONRAD Fredericto initialize. 1098d4e9146SKONRAD Frederic@table @option 1108d4e9146SKONRAD Frederic@item thread=single|multi 1118d4e9146SKONRAD FredericControls number of TCG threads. When the TCG is multi-threaded there will be one 1128d4e9146SKONRAD Fredericthread per vCPU therefor taking advantage of additional host cores. The default 1138d4e9146SKONRAD Fredericis to enable multi-threading where both the back-end and front-ends support it and 1148d4e9146SKONRAD Fredericno incompatible TCG features have been enabled (e.g. icount/replay). 1158d4e9146SKONRAD Frederic@end table 1168d4e9146SKONRAD FredericETEXI 1178d4e9146SKONRAD Frederic 1185824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 11912b7f57eSMichael Tokarev "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 1206be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1216be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 122ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 12358a04db1SAndre Przywara " cores= number of CPU cores on one socket\n" 12458a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 125ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 126ad96090aSBlue Swirl QEMU_ARCH_ALL) 1275824d651Sblueswir1STEXI 12812b7f57eSMichael Tokarev@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1296616b2adSStefan Weil@findex -smp 1305824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1315824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1325824d651Sblueswir1to 4. 13358a04db1SAndre PrzywaraFor the PC target, the number of @var{cores} per socket, the number 13458a04db1SAndre Przywaraof @var{threads} per cores and the total number of @var{sockets} can be 13558a04db1SAndre Przywaraspecified. Missing values will be computed. If any on the three values is 13658a04db1SAndre Przywaragiven, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 13758a04db1SAndre Przywaraspecifies the maximum number of hotpluggable CPUs. 1385824d651Sblueswir1ETEXI 1395824d651Sblueswir1 140268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 141e0ee9fd0SEduardo Habkost "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 142e0ee9fd0SEduardo Habkost "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n", QEMU_ARCH_ALL) 143268a362cSaliguoriSTEXI 144e0ee9fd0SEduardo Habkost@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 145e0ee9fd0SEduardo Habkost@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 1466616b2adSStefan Weil@findex -numa 1477febe36fSPaolo BonziniSimulate a multi node NUMA system. If @samp{mem}, @samp{memdev} 1484932b897SLuiz Capitulinoand @samp{cpus} are omitted, resources are split equally. Also, note 1494932b897SLuiz Capitulinothat the -@option{numa} option doesn't allocate any of the specified 1504932b897SLuiz Capitulinoresources. That is, it just assigns existing resources to NUMA nodes. This 1514932b897SLuiz Capitulinomeans that one still has to use the @option{-m}, @option{-smp} options 1527febe36fSPaolo Bonzinito allocate RAM and VCPUs respectively, and possibly @option{-object} 1537febe36fSPaolo Bonzinito specify the memory backend for the @samp{memdev} suboption. 1547febe36fSPaolo Bonzini 1557febe36fSPaolo Bonzini@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one 1567febe36fSPaolo Bonzininode uses @samp{memdev}, all of them have to use it. 157268a362cSaliguoriETEXI 158268a362cSaliguori 15910adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 16010adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 16110adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 16210adb8beSMarkus ArmbrusterSTEXI 16310adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 16410adb8beSMarkus Armbruster@findex -add-fd 16510adb8beSMarkus Armbruster 16610adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 16710adb8beSMarkus Armbruster 16810adb8beSMarkus Armbruster@table @option 16910adb8beSMarkus Armbruster@item fd=@var{fd} 17010adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 17110adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 17210adb8beSMarkus Armbruster@item set=@var{set} 17310adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 17410adb8beSMarkus Armbruster@item opaque=@var{opaque} 17510adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 17610adb8beSMarkus Armbruster@end table 17710adb8beSMarkus Armbruster 17810adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 17910adb8beSMarkus Armbruster@example 18010adb8beSMarkus Armbrusterqemu-system-i386 18110adb8beSMarkus Armbruster-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 18210adb8beSMarkus Armbruster-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 18310adb8beSMarkus Armbruster-drive file=/dev/fdset/2,index=0,media=disk 18410adb8beSMarkus Armbruster@end example 18510adb8beSMarkus ArmbrusterETEXI 18610adb8beSMarkus Armbruster 18710adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 18810adb8beSMarkus Armbruster "-set group.id.arg=value\n" 18910adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 19010adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 19110adb8beSMarkus ArmbrusterSTEXI 19210adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 19310adb8beSMarkus Armbruster@findex -set 194e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 19510adb8beSMarkus ArmbrusterETEXI 19610adb8beSMarkus Armbruster 19710adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 1983751d7c4SPaolo Bonzini "-global driver.property=value\n" 1993751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 20010adb8beSMarkus Armbruster " set a global default for a driver property\n", 20110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 20210adb8beSMarkus ArmbrusterSTEXI 20310adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 2043751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 20510adb8beSMarkus Armbruster@findex -global 20610adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 20710adb8beSMarkus Armbruster 20810adb8beSMarkus Armbruster@example 20910adb8beSMarkus Armbrusterqemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk 21010adb8beSMarkus Armbruster@end example 21110adb8beSMarkus Armbruster 21210adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 21310adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 21410adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 2153751d7c4SPaolo Bonzini 216ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 217ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 218ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 21910adb8beSMarkus ArmbrusterETEXI 22010adb8beSMarkus Armbruster 22110adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 22210adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 223c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 22410adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 22510adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 22610adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 22710adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 22810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 22910adb8beSMarkus ArmbrusterSTEXI 230c8a6ae8bSAmos Kong@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] 23110adb8beSMarkus Armbruster@findex -boot 23210adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 233d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 23410adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 23510adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 23610adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 23710adb8beSMarkus Armbruster@option{once}. 23810adb8beSMarkus Armbruster 23910adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 24010adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 24110adb8beSMarkus Armbruster 24210adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 24310adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 24410adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 24510adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 24610adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 24710adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 24810adb8beSMarkus Armbruster 24910adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 25010adb8beSMarkus Armbrusterwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 25110adb8beSMarkus Armbrusterreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 25210adb8beSMarkus Armbrustersystem support it. 25310adb8beSMarkus Armbruster 254c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 255c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 256c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 257c8a6ae8bSAmos Kong 25810adb8beSMarkus Armbruster@example 25910adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 26010adb8beSMarkus Armbrusterqemu-system-i386 -boot order=nc 26110adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 26210adb8beSMarkus Armbrusterqemu-system-i386 -boot once=d 26310adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 26410adb8beSMarkus Armbrusterqemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 26510adb8beSMarkus Armbruster@end example 26610adb8beSMarkus Armbruster 26710adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 26810adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 26910adb8beSMarkus ArmbrusterETEXI 27010adb8beSMarkus Armbruster 27110adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 27289f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 2736e1d3c1cSIgor Mammedov " configure guest RAM\n" 2740daba1f0SAlexander Graf " size: initial amount of guest memory\n" 275c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 276b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 277b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 2786e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 27910adb8beSMarkus ArmbrusterSTEXI 2809fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 28110adb8beSMarkus Armbruster@findex -m 2829fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 2839fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 2849fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 2859fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 2869fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 2879fcc0794SLuiz Capitulino 2889fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 2899fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 2909fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 2919fcc0794SLuiz Capitulino 2929fcc0794SLuiz Capitulino@example 2939fcc0794SLuiz Capitulinoqemu-system-x86_64 -m 1G,slots=3,maxmem=4G 2949fcc0794SLuiz Capitulino@end example 2959fcc0794SLuiz Capitulino 2969fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 2979fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 29810adb8beSMarkus ArmbrusterETEXI 29910adb8beSMarkus Armbruster 30010adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 30110adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 30210adb8beSMarkus ArmbrusterSTEXI 30310adb8beSMarkus Armbruster@item -mem-path @var{path} 30410adb8beSMarkus Armbruster@findex -mem-path 30510adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 30610adb8beSMarkus ArmbrusterETEXI 30710adb8beSMarkus Armbruster 30810adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 30910adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 31010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 31110adb8beSMarkus ArmbrusterSTEXI 31210adb8beSMarkus Armbruster@item -mem-prealloc 31310adb8beSMarkus Armbruster@findex -mem-prealloc 31410adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 31510adb8beSMarkus ArmbrusterETEXI 31610adb8beSMarkus Armbruster 31710adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 31810adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 31910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 32010adb8beSMarkus ArmbrusterSTEXI 32110adb8beSMarkus Armbruster@item -k @var{language} 32210adb8beSMarkus Armbruster@findex -k 32310adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 32410adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 32532945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 32610adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 32710adb8beSMarkus Armbrusterhosts. 32810adb8beSMarkus Armbruster 32910adb8beSMarkus ArmbrusterThe available layouts are: 33010adb8beSMarkus Armbruster@example 33110adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 33210adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 33310adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 33410adb8beSMarkus Armbruster@end example 33510adb8beSMarkus Armbruster 33610adb8beSMarkus ArmbrusterThe default is @code{en-us}. 33710adb8beSMarkus ArmbrusterETEXI 33810adb8beSMarkus Armbruster 33910adb8beSMarkus Armbruster 34010adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 34110adb8beSMarkus Armbruster "-audio-help print list of audio drivers and their options\n", 34210adb8beSMarkus Armbruster QEMU_ARCH_ALL) 34310adb8beSMarkus ArmbrusterSTEXI 34410adb8beSMarkus Armbruster@item -audio-help 34510adb8beSMarkus Armbruster@findex -audio-help 34610adb8beSMarkus ArmbrusterWill show the audio subsystem help: list of drivers, tunable 34710adb8beSMarkus Armbrusterparameters. 34810adb8beSMarkus ArmbrusterETEXI 34910adb8beSMarkus Armbruster 35010adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 35110adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 35210adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 35310adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 35410adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 35510adb8beSMarkus ArmbrusterSTEXI 35610adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 35710adb8beSMarkus Armbruster@findex -soundhw 35810adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 35910adb8beSMarkus Armbrusteravailable sound hardware. 36010adb8beSMarkus Armbruster 36110adb8beSMarkus Armbruster@example 36210adb8beSMarkus Armbrusterqemu-system-i386 -soundhw sb16,adlib disk.img 36310adb8beSMarkus Armbrusterqemu-system-i386 -soundhw es1370 disk.img 36410adb8beSMarkus Armbrusterqemu-system-i386 -soundhw ac97 disk.img 36510adb8beSMarkus Armbrusterqemu-system-i386 -soundhw hda disk.img 36610adb8beSMarkus Armbrusterqemu-system-i386 -soundhw all disk.img 36710adb8beSMarkus Armbrusterqemu-system-i386 -soundhw help 36810adb8beSMarkus Armbruster@end example 36910adb8beSMarkus Armbruster 37010adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 37110adb8beSMarkus Armbrusterrequire manually specifying clocking. 37210adb8beSMarkus Armbruster 37310adb8beSMarkus Armbruster@example 37410adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 37510adb8beSMarkus Armbruster@end example 37610adb8beSMarkus ArmbrusterETEXI 37710adb8beSMarkus Armbruster 37810adb8beSMarkus ArmbrusterDEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 37910adb8beSMarkus Armbruster "-balloon none disable balloon device\n" 38010adb8beSMarkus Armbruster "-balloon virtio[,addr=str]\n" 38110adb8beSMarkus Armbruster " enable virtio balloon device (default)\n", QEMU_ARCH_ALL) 38210adb8beSMarkus ArmbrusterSTEXI 38310adb8beSMarkus Armbruster@item -balloon none 38410adb8beSMarkus Armbruster@findex -balloon 38510adb8beSMarkus ArmbrusterDisable balloon device. 38610adb8beSMarkus Armbruster@item -balloon virtio[,addr=@var{addr}] 38710adb8beSMarkus ArmbrusterEnable virtio balloon device (default), optionally with PCI address 38810adb8beSMarkus Armbruster@var{addr}. 38910adb8beSMarkus ArmbrusterETEXI 39010adb8beSMarkus Armbruster 39110adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 39210adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 39310adb8beSMarkus Armbruster " add device (based on driver)\n" 39410adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 39510adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 39610adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 39710adb8beSMarkus Armbruster QEMU_ARCH_ALL) 39810adb8beSMarkus ArmbrusterSTEXI 39910adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 40010adb8beSMarkus Armbruster@findex -device 40110adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 40210adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 40310adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 40410adb8beSMarkus Armbruster@code{-device @var{driver},help}. 405f8490451SCorey Minyard 406f8490451SCorey MinyardSome drivers are: 407f8490451SCorey Minyard@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}] 408f8490451SCorey Minyard 409f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 410f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 411f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 412f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 413f8490451SCorey Minyard 414f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 415f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 416f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 417f8490451SCorey Minyardit. 418f8490451SCorey Minyard 419f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 420f8490451SCorey Minyard 421f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 422f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 423f8490451SCorey Minyardto an external entity that provides the IPMI services. 424f8490451SCorey Minyard 425f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 426f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 427f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 428f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 429f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 430f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 431f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 432f8490451SCorey Minyardexposed to any outside network. 433f8490451SCorey Minyard 434f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 435f8490451SCorey Minyarddetails on the external interface. 436f8490451SCorey Minyard 437f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 438f8490451SCorey Minyard 439f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 440f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 441f8490451SCorey Minyard 442f8490451SCorey Minyard@table @option 443f8490451SCorey Minyard@item bmc=@var{id} 444f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 445f8490451SCorey Minyard@item ioport=@var{val} 446f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 447f8490451SCorey Minyard@item irq=@var{val} 448f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 449f8490451SCorey Minyardset this to 0. 450f8490451SCorey Minyard@end table 451f8490451SCorey Minyard 452f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 453f8490451SCorey Minyard 454f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 455f8490451SCorey Minyard0xe4 and the default interrupt is 5. 456f8490451SCorey Minyard 45710adb8beSMarkus ArmbrusterETEXI 45810adb8beSMarkus Armbruster 45910adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 4608f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 46110adb8beSMarkus Armbruster " set the name of the guest\n" 4628f480de0SDr. David Alan Gilbert " string1 sets the window title and string2 the process name (on Linux)\n" 4638f480de0SDr. David Alan Gilbert " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 4648f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 46510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 46610adb8beSMarkus ArmbrusterSTEXI 46710adb8beSMarkus Armbruster@item -name @var{name} 46810adb8beSMarkus Armbruster@findex -name 46910adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 47010adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 47110adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 47210adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 4738f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 47410adb8beSMarkus ArmbrusterETEXI 47510adb8beSMarkus Armbruster 47610adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 47710adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 47810adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 47910adb8beSMarkus ArmbrusterSTEXI 48010adb8beSMarkus Armbruster@item -uuid @var{uuid} 48110adb8beSMarkus Armbruster@findex -uuid 48210adb8beSMarkus ArmbrusterSet system UUID. 48310adb8beSMarkus ArmbrusterETEXI 48410adb8beSMarkus Armbruster 48510adb8beSMarkus ArmbrusterSTEXI 48610adb8beSMarkus Armbruster@end table 48710adb8beSMarkus ArmbrusterETEXI 48810adb8beSMarkus ArmbrusterDEFHEADING() 48910adb8beSMarkus Armbruster 49043f187a5SPaolo BonziniDEFHEADING(Block device options) 49110adb8beSMarkus ArmbrusterSTEXI 49210adb8beSMarkus Armbruster@table @option 49310adb8beSMarkus ArmbrusterETEXI 49410adb8beSMarkus Armbruster 4955824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 496ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 497ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 4985824d651Sblueswir1STEXI 4995824d651Sblueswir1@item -fda @var{file} 500f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 5016616b2adSStefan Weil@findex -fda 5026616b2adSStefan Weil@findex -fdb 50392a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 5045824d651Sblueswir1ETEXI 5055824d651Sblueswir1 5065824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 507ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 508ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 5095824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 510ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 511ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 5125824d651Sblueswir1STEXI 5135824d651Sblueswir1@item -hda @var{file} 514f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 515f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 516f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 5176616b2adSStefan Weil@findex -hda 5186616b2adSStefan Weil@findex -hdb 5196616b2adSStefan Weil@findex -hdc 5206616b2adSStefan Weil@findex -hdd 5215824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 5225824d651Sblueswir1ETEXI 5235824d651Sblueswir1 5245824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 525ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 526ad96090aSBlue Swirl QEMU_ARCH_ALL) 5275824d651Sblueswir1STEXI 5285824d651Sblueswir1@item -cdrom @var{file} 5296616b2adSStefan Weil@findex -cdrom 5305824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 5315824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 5325824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 5335824d651Sblueswir1ETEXI 5345824d651Sblueswir1 5355824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 5365824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 5375824d651Sblueswir1 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" 53892196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 539d1db760dSStefan Hajnoczi " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n" 540d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 541fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 5422f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 5433e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 5443e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 5453e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 5463e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 5472024c1dfSBenoît Canet " [[,iops_size=is]]\n" 54876f4afb4SAlberto Garcia " [[,group=g]]\n" 549ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 5505824d651Sblueswir1STEXI 5515824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 5526616b2adSStefan Weil@findex -drive 5535824d651Sblueswir1 5545824d651Sblueswir1Define a new drive. Valid options are: 5555824d651Sblueswir1 556b3f046c2SKevin Wolf@table @option 5575824d651Sblueswir1@item file=@var{file} 5585824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 5595824d651Sblueswir1this drive. If the filename contains comma, you must double it 5605824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 5610f5314a2SRonnie Sahlberg 5620f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 5630f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 5645824d651Sblueswir1@item if=@var{interface} 5655824d651Sblueswir1This option defines on which type on interface the drive is connected. 5665824d651Sblueswir1Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. 5675824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 5685824d651Sblueswir1These options define where is connected the drive by defining the bus number and 5695824d651Sblueswir1the unit id. 5705824d651Sblueswir1@item index=@var{index} 5715824d651Sblueswir1This option defines where is connected the drive by using an index in the list 5725824d651Sblueswir1of available connectors of a given interface type. 5735824d651Sblueswir1@item media=@var{media} 5745824d651Sblueswir1This option defines the type of the media: disk or cdrom. 5755824d651Sblueswir1@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] 5765824d651Sblueswir1These options have the same definition as they have in @option{-hdachs}. 5775824d651Sblueswir1@item snapshot=@var{snapshot} 5789d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 5799d85d557SMichael Tokarev(see @option{-snapshot}). 5805824d651Sblueswir1@item cache=@var{cache} 58192196b2fSStefan Hajnoczi@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. 5825c6c3a6cSChristoph Hellwig@item aio=@var{aio} 5835c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 584a9384affSPaolo Bonzini@item discard=@var{discard} 585a9384affSPaolo Bonzini@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. 5865824d651Sblueswir1@item format=@var{format} 5875824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 588d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 5895824d651Sblueswir1an untrusted format header. 5905824d651Sblueswir1@item serial=@var{serial} 5915824d651Sblueswir1This option specifies the serial number to assign to the device. 592c2cc47a4SMarkus Armbruster@item addr=@var{addr} 593c2cc47a4SMarkus ArmbrusterSpecify the controller's PCI address (if=virtio only). 594ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 595ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 596ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 597ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 598ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 599ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 600ae73e591SLuiz Capitulino@item readonly 601ae73e591SLuiz CapitulinoOpen drive @option{file} as read-only. Guest write attempts will fail. 602fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 603fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 604fb0490f6SStefan Hajnoczifile sectors into the image file. 605465bee1dSPeter Lieven@item detect-zeroes=@var{detect-zeroes} 606465bee1dSPeter Lieven@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 607465bee1dSPeter Lievenconversion of plain zero writes by the OS to driver specific optimized 608465bee1dSPeter Lievenzero write commands. You may even choose "unmap" if @var{discard} is set 609465bee1dSPeter Lievento "unmap" to allow a zero write to be converted to an UNMAP operation. 6105824d651Sblueswir1@end table 6115824d651Sblueswir1 612a13e5e05SKevin WolfBy default, the @option{cache=writeback} mode is used. It will report data 613a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 614a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 615a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 616a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 617a13e5e05SKevin Wolfdata corruption. 6185824d651Sblueswir1 619a13e5e05SKevin WolfFor such guests, you should consider using @option{cache=writethrough}. This 620a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 621a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 622a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 6235824d651Sblueswir1 624c304d317SAurelien JarnoThe host page cache can be avoided entirely with @option{cache=none}. This will 625a13e5e05SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform 626a13e5e05SKevin Wolfan internal copy of the data. Note that this is considered a writeback mode and 627a13e5e05SKevin Wolfthe guest OS must handle the disk write cache correctly in order to avoid data 628a13e5e05SKevin Wolfcorruption on host crashes. 6295824d651Sblueswir1 63092196b2fSStefan HajnocziThe host page cache can be avoided while only sending write notifications to 631a13e5e05SKevin Wolfthe guest when the data has been flushed to the disk using 632a13e5e05SKevin Wolf@option{cache=directsync}. 6335824d651Sblueswir1 634016f5cf6SAlexander GrafIn case you don't care about data integrity over host failures, use 635a13e5e05SKevin Wolf@option{cache=unsafe}. This option tells QEMU that it never needs to write any 636a13e5e05SKevin Wolfdata to the disk but can instead keep things in cache. If anything goes wrong, 637e7d81004SStefan Weillike your host losing power, the disk storage getting disconnected accidentally, 638a13e5e05SKevin Wolfetc. your image will most probably be rendered unusable. When using 639c3177288SAlexander Grafthe @option{-snapshot} option, unsafe caching is always used. 640016f5cf6SAlexander Graf 641fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 642fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 643fb0490f6SStefan Hajnocziis off. 644fb0490f6SStefan Hajnoczi 6455824d651Sblueswir1Instead of @option{-cdrom} you can use: 6465824d651Sblueswir1@example 6473804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=cdrom 6485824d651Sblueswir1@end example 6495824d651Sblueswir1 6505824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 6515824d651Sblueswir1use: 6525824d651Sblueswir1@example 6533804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,media=disk 6543804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,media=disk 6553804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=disk 6563804da9dSStefan Weilqemu-system-i386 -drive file=file,index=3,media=disk 6575824d651Sblueswir1@end example 6585824d651Sblueswir1 659587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 660587ed6beSCorey Bryant@example 661587ed6beSCorey Bryantqemu-system-i386 662587ed6beSCorey Bryant-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 663587ed6beSCorey Bryant-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 664587ed6beSCorey Bryant-drive file=/dev/fdset/2,index=0,media=disk 665587ed6beSCorey Bryant@end example 666587ed6beSCorey Bryant 6675824d651Sblueswir1You can connect a CDROM to the slave of ide0: 6685824d651Sblueswir1@example 6693804da9dSStefan Weilqemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 6705824d651Sblueswir1@end example 6715824d651Sblueswir1 6725824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 6735824d651Sblueswir1@example 6743804da9dSStefan Weilqemu-system-i386 -drive if=ide,index=1,media=cdrom 6755824d651Sblueswir1@end example 6765824d651Sblueswir1 6775824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 6785824d651Sblueswir1@example 6793804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,if=floppy 6803804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,if=floppy 6815824d651Sblueswir1@end example 6825824d651Sblueswir1 6835824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 6845824d651Sblueswir1incremented: 6855824d651Sblueswir1@example 6863804da9dSStefan Weilqemu-system-i386 -drive file=a -drive file=b" 6875824d651Sblueswir1@end example 6885824d651Sblueswir1is interpreted like: 6895824d651Sblueswir1@example 6903804da9dSStefan Weilqemu-system-i386 -hda a -hdb b 6915824d651Sblueswir1@end example 6925824d651Sblueswir1ETEXI 6935824d651Sblueswir1 6945824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 695ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 696ad96090aSBlue Swirl QEMU_ARCH_ALL) 6975824d651Sblueswir1STEXI 6984e257e5eSKevin Wolf@item -mtdblock @var{file} 6996616b2adSStefan Weil@findex -mtdblock 7004e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 7015824d651Sblueswir1ETEXI 7025824d651Sblueswir1 7035824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 704ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 7055824d651Sblueswir1STEXI 7064e257e5eSKevin Wolf@item -sd @var{file} 7076616b2adSStefan Weil@findex -sd 7084e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 7095824d651Sblueswir1ETEXI 7105824d651Sblueswir1 7115824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 712ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 7135824d651Sblueswir1STEXI 7144e257e5eSKevin Wolf@item -pflash @var{file} 7156616b2adSStefan Weil@findex -pflash 7164e257e5eSKevin WolfUse @var{file} as a parallel flash image. 7175824d651Sblueswir1ETEXI 7185824d651Sblueswir1 7195824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 720ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 721ad96090aSBlue Swirl QEMU_ARCH_ALL) 7225824d651Sblueswir1STEXI 7235824d651Sblueswir1@item -snapshot 7246616b2adSStefan Weil@findex -snapshot 7255824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 7265824d651Sblueswir1the raw disk image you use is not written back. You can however force 7275824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 7285824d651Sblueswir1ETEXI 7295824d651Sblueswir1 73010adb8beSMarkus ArmbrusterDEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ 73110adb8beSMarkus Armbruster "-hdachs c,h,s[,t]\n" \ 73210adb8beSMarkus Armbruster " force hard disk 0 physical geometry and the optional BIOS\n" \ 73310adb8beSMarkus Armbruster " translation (t=none or lba) (usually QEMU can guess them)\n", 734ad96090aSBlue Swirl QEMU_ARCH_ALL) 735c902760fSMarcelo TosattiSTEXI 73610adb8beSMarkus Armbruster@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] 73710adb8beSMarkus Armbruster@findex -hdachs 73810adb8beSMarkus ArmbrusterForce hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= 73910adb8beSMarkus Armbruster@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS 74010adb8beSMarkus Armbrustertranslation mode (@var{t}=none, lba or auto). Usually QEMU can guess 74110adb8beSMarkus Armbrusterall those parameters. This option is useful for old MS-DOS disk 74210adb8beSMarkus Armbrusterimages. 743c70a01e4SMarkus ArmbrusterETEXI 74474db920cSGautham R Shenoy 74574db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 7462c30dd74SAneesh Kumar K.V "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 747*b8bbdb88SPradeep Jagadeesh " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n" 748*b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 749*b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 750*b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 751*b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 752*b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-size=is]]\n", 75374db920cSGautham R Shenoy QEMU_ARCH_ALL) 75474db920cSGautham R Shenoy 75574db920cSGautham R ShenoySTEXI 75674db920cSGautham R Shenoy 75784a87cc4SM. Mohan Kumar@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}] 75874db920cSGautham R Shenoy@findex -fsdev 7597c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 7607c92a3d2SAneesh Kumar K.V@table @option 7617c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 7627c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 763f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 7647c92a3d2SAneesh Kumar K.V@item id=@var{id} 7657c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 7667c92a3d2SAneesh Kumar K.V@item path=@var{path} 7677c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 7687c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 7697c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 7707c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 7712c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 7727c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 773b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 7742c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 7757c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 7762c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 7772c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 7787c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 7797c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 780d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 781f67e3ffdSM. Mohan Kumaronly for local fsdriver. Other fsdrivers (like handle, proxy) don't take 782d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 7837c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 7847c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 7857c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 7867c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 7877c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 7882c74c2cbSM. Mohan Kumar@item readonly 7892c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 7902c74c2cbSM. Mohan Kumarread-write access is given. 79184a87cc4SM. Mohan Kumar@item socket=@var{socket} 79284a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 79384a87cc4SM. Mohan Kumarwith virtfs-proxy-helper 794f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 795f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 796f67e3ffdSM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 797f67e3ffdSM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 79874db920cSGautham R Shenoy@end table 7997c92a3d2SAneesh Kumar K.V 8007c92a3d2SAneesh Kumar K.V-fsdev option is used along with -device driver "virtio-9p-pci". 8017c92a3d2SAneesh Kumar K.V@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 8027c92a3d2SAneesh Kumar K.VOptions for virtio-9p-pci driver are: 8037c92a3d2SAneesh Kumar K.V@table @option 8047c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 8057c92a3d2SAneesh Kumar K.VSpecifies the id value specified along with -fsdev option 8067c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 8077c92a3d2SAneesh Kumar K.VSpecifies the tag name to be used by the guest to mount this export point 8087c92a3d2SAneesh Kumar K.V@end table 8097c92a3d2SAneesh Kumar K.V 81074db920cSGautham R ShenoyETEXI 81174db920cSGautham R Shenoy 8123d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 8132c30dd74SAneesh Kumar K.V "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 81484a87cc4SM. Mohan Kumar " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 8153d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 8163d54abc7SGautham R Shenoy 8173d54abc7SGautham R ShenoySTEXI 8183d54abc7SGautham R Shenoy 81984a87cc4SM. Mohan Kumar@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}] 8203d54abc7SGautham R Shenoy@findex -virtfs 8213d54abc7SGautham R Shenoy 8227c92a3d2SAneesh Kumar K.VThe general form of a Virtual File system pass-through options are: 8237c92a3d2SAneesh Kumar K.V@table @option 8247c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 8257c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 826f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 8277c92a3d2SAneesh Kumar K.V@item id=@var{id} 8287c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 8297c92a3d2SAneesh Kumar K.V@item path=@var{path} 8307c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 8317c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 8327c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 8337c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 8342c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 8357c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 836b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 8372c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 8387c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 8392c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 8402c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 8417c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 8427c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 843d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 844f67e3ffdSM. Mohan Kumarfor local fsdriver. Other fsdrivers (like handle, proxy) don't take security 845d9b36a6eSM. Mohan Kumarmodel as a parameter. 8467c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 8477c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 8487c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 8497c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 8507c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 8512c74c2cbSM. Mohan Kumar@item readonly 8522c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 8532c74c2cbSM. Mohan Kumarread-write access is given. 85484a87cc4SM. Mohan Kumar@item socket=@var{socket} 85584a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 85684a87cc4SM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 85784a87cc4SM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 858f67e3ffdSM. Mohan Kumar@item sock_fd 859f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 860f67e3ffdSM. Mohan Kumardescriptor for interfacing with virtfs-proxy-helper 8613d54abc7SGautham R Shenoy@end table 8623d54abc7SGautham R ShenoyETEXI 8633d54abc7SGautham R Shenoy 8649db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 8659db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 8669db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 8679db221aeSAneesh Kumar K.VSTEXI 8689db221aeSAneesh Kumar K.V@item -virtfs_synth 8699db221aeSAneesh Kumar K.V@findex -virtfs_synth 8709db221aeSAneesh Kumar K.VCreate synthetic file system image 8719db221aeSAneesh Kumar K.VETEXI 8729db221aeSAneesh Kumar K.V 8735824d651Sblueswir1STEXI 8745824d651Sblueswir1@end table 8755824d651Sblueswir1ETEXI 8765824d651Sblueswir1DEFHEADING() 8775824d651Sblueswir1 87843f187a5SPaolo BonziniDEFHEADING(USB options) 87910adb8beSMarkus ArmbrusterSTEXI 88010adb8beSMarkus Armbruster@table @option 88110adb8beSMarkus ArmbrusterETEXI 88210adb8beSMarkus Armbruster 88310adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 88410adb8beSMarkus Armbruster "-usb enable the USB driver (will be the default soon)\n", 88510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 88610adb8beSMarkus ArmbrusterSTEXI 88710adb8beSMarkus Armbruster@item -usb 88810adb8beSMarkus Armbruster@findex -usb 88910adb8beSMarkus ArmbrusterEnable the USB driver (will be the default soon) 89010adb8beSMarkus ArmbrusterETEXI 89110adb8beSMarkus Armbruster 89210adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 89310adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 89410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 89510adb8beSMarkus ArmbrusterSTEXI 89610adb8beSMarkus Armbruster 89710adb8beSMarkus Armbruster@item -usbdevice @var{devname} 89810adb8beSMarkus Armbruster@findex -usbdevice 89910adb8beSMarkus ArmbrusterAdd the USB device @var{devname}. @xref{usb_devices}. 90010adb8beSMarkus Armbruster 90110adb8beSMarkus Armbruster@table @option 90210adb8beSMarkus Armbruster 90310adb8beSMarkus Armbruster@item mouse 90410adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 90510adb8beSMarkus Armbruster 90610adb8beSMarkus Armbruster@item tablet 90710adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 90810adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 90910adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 91010adb8beSMarkus Armbruster 91110adb8beSMarkus Armbruster@item disk:[format=@var{format}]:@var{file} 91210adb8beSMarkus ArmbrusterMass storage device based on file. The optional @var{format} argument 913d33c8a7dSMichael Tokarevwill be used rather than detecting the format. Can be used to specify 91410adb8beSMarkus Armbruster@code{format=raw} to avoid interpreting an untrusted format header. 91510adb8beSMarkus Armbruster 91610adb8beSMarkus Armbruster@item host:@var{bus}.@var{addr} 91710adb8beSMarkus ArmbrusterPass through the host device identified by @var{bus}.@var{addr} (Linux only). 91810adb8beSMarkus Armbruster 91910adb8beSMarkus Armbruster@item host:@var{vendor_id}:@var{product_id} 92010adb8beSMarkus ArmbrusterPass through the host device identified by @var{vendor_id}:@var{product_id} 92110adb8beSMarkus Armbruster(Linux only). 92210adb8beSMarkus Armbruster 92310adb8beSMarkus Armbruster@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} 92410adb8beSMarkus ArmbrusterSerial converter to host character device @var{dev}, see @code{-serial} for the 92510adb8beSMarkus Armbrusteravailable devices. 92610adb8beSMarkus Armbruster 92710adb8beSMarkus Armbruster@item braille 92810adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 92910adb8beSMarkus Armbrusteror fake device. 93010adb8beSMarkus Armbruster 93110adb8beSMarkus Armbruster@item net:@var{options} 93210adb8beSMarkus ArmbrusterNetwork adapter that supports CDC ethernet and RNDIS protocols. 93310adb8beSMarkus Armbruster 93410adb8beSMarkus Armbruster@end table 93510adb8beSMarkus ArmbrusterETEXI 93610adb8beSMarkus Armbruster 93710adb8beSMarkus ArmbrusterSTEXI 93810adb8beSMarkus Armbruster@end table 93910adb8beSMarkus ArmbrusterETEXI 94010adb8beSMarkus ArmbrusterDEFHEADING() 94110adb8beSMarkus Armbruster 94243f187a5SPaolo BonziniDEFHEADING(Display options) 9435824d651Sblueswir1STEXI 9445824d651Sblueswir1@table @option 9455824d651Sblueswir1ETEXI 9465824d651Sblueswir1 9471472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 9481472a95bSJes Sorensen "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 94987eb2bacSSamuel Thibault " [,window_close=on|off][,gl=on|off]\n" 950f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 951f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 952f04ec5afSRobert Ho "-display curses\n" 953f04ec5afSRobert Ho "-display none" 954f04ec5afSRobert Ho " select display type\n" 955f04ec5afSRobert Ho "The default display is equivalent to\n" 956f04ec5afSRobert Ho#if defined(CONFIG_GTK) 957f04ec5afSRobert Ho "\t\"-display gtk\"\n" 958f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 959f04ec5afSRobert Ho "\t\"-display sdl\"\n" 960f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 961f04ec5afSRobert Ho "\t\"-display cocoa\"\n" 962f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 963f04ec5afSRobert Ho "\t\"-vnc localhost:0,to=99,id=default\"\n" 964f04ec5afSRobert Ho#else 965f04ec5afSRobert Ho "\t\"-display none\"\n" 966f04ec5afSRobert Ho#endif 967f04ec5afSRobert Ho , QEMU_ARCH_ALL) 9681472a95bSJes SorensenSTEXI 9691472a95bSJes Sorensen@item -display @var{type} 9701472a95bSJes Sorensen@findex -display 9711472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 9721472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 9731472a95bSJes Sorensen@table @option 9741472a95bSJes Sorensen@item sdl 9751472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 9761472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 9771472a95bSJes Sorensen@item curses 9781472a95bSJes SorensenDisplay video output via curses. For graphics device models which 9791472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 9801472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 9811472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 9821472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 9834171d32eSJes Sorensen@item none 9844171d32eSJes SorensenDo not display video output. The guest will still see an emulated 9854171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 9864171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 9874171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 9884171d32eSJes Sorensenthe destination of the serial and parallel port data. 989881249c7SJan Kiszka@item gtk 990881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 991881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 992881249c7SJan Kiszkaruntime. 9933264ff12SJes Sorensen@item vnc 9943264ff12SJes SorensenStart a VNC server on display <arg> 9951472a95bSJes Sorensen@end table 9961472a95bSJes SorensenETEXI 9971472a95bSJes Sorensen 9985824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 999ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1000ad96090aSBlue Swirl QEMU_ARCH_ALL) 10015824d651Sblueswir1STEXI 10025824d651Sblueswir1@item -nographic 10036616b2adSStefan Weil@findex -nographic 1004dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1005dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1006dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1007dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1008dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1009dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1010dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1011dc0a3e44SColin Lordswitching between the console and monitor. 10125824d651Sblueswir1ETEXI 10135824d651Sblueswir1 10145824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1015f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1016ad96090aSBlue Swirl QEMU_ARCH_ALL) 10175824d651Sblueswir1STEXI 10185824d651Sblueswir1@item -curses 1019b8f490ebSMarkus Armbruster@findex -curses 1020dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1021dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1022dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1023dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1024dc0a3e44SColin Lordmode. 10255824d651Sblueswir1ETEXI 10265824d651Sblueswir1 10275824d651Sblueswir1DEF("no-frame", 0, QEMU_OPTION_no_frame, 1028ad96090aSBlue Swirl "-no-frame open SDL window without a frame and window decorations\n", 1029ad96090aSBlue Swirl QEMU_ARCH_ALL) 10305824d651Sblueswir1STEXI 10315824d651Sblueswir1@item -no-frame 10326616b2adSStefan Weil@findex -no-frame 10335824d651Sblueswir1Do not use decorations for SDL windows and start them using the whole 10345824d651Sblueswir1available screen space. This makes the using QEMU in a dedicated desktop 10355824d651Sblueswir1workspace more convenient. 10365824d651Sblueswir1ETEXI 10375824d651Sblueswir1 10385824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1039ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1040ad96090aSBlue Swirl QEMU_ARCH_ALL) 10415824d651Sblueswir1STEXI 10425824d651Sblueswir1@item -alt-grab 10436616b2adSStefan Weil@findex -alt-grab 1044de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1045de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 10465824d651Sblueswir1ETEXI 10475824d651Sblueswir1 10480ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1049ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1050ad96090aSBlue Swirl QEMU_ARCH_ALL) 10510ca9f8a4SDustin KirklandSTEXI 10520ca9f8a4SDustin Kirkland@item -ctrl-grab 10536616b2adSStefan Weil@findex -ctrl-grab 1054de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1055de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 10560ca9f8a4SDustin KirklandETEXI 10570ca9f8a4SDustin Kirkland 10585824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1059ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 10605824d651Sblueswir1STEXI 10615824d651Sblueswir1@item -no-quit 10626616b2adSStefan Weil@findex -no-quit 10635824d651Sblueswir1Disable SDL window close capability. 10645824d651Sblueswir1ETEXI 10655824d651Sblueswir1 10665824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1067f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 10685824d651Sblueswir1STEXI 10695824d651Sblueswir1@item -sdl 10706616b2adSStefan Weil@findex -sdl 10715824d651Sblueswir1Enable SDL. 10725824d651Sblueswir1ETEXI 10735824d651Sblueswir1 107429b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 107527af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 107627af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 107727af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1078fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 107927af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 108027af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 108127af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 108227af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 108327af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 108427af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 108527af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 108627af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 10875ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 10885ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 10897b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 109027af7788SYonit Halperin " enable spice\n" 109127af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 109227af7788SYonit Halperin QEMU_ARCH_ALL) 109329b0040bSGerd HoffmannSTEXI 109429b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 109529b0040bSGerd Hoffmann@findex -spice 109629b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 109729b0040bSGerd Hoffmann 109829b0040bSGerd Hoffmann@table @option 109929b0040bSGerd Hoffmann 110029b0040bSGerd Hoffmann@item port=<nr> 1101c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 110229b0040bSGerd Hoffmann 1103333b0eebSGerd Hoffmann@item addr=<addr> 1104333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1105333b0eebSGerd Hoffmann 1106333b0eebSGerd Hoffmann@item ipv4 1107f9cfd655SMarkus Armbruster@itemx ipv6 1108f9cfd655SMarkus Armbruster@itemx unix 1109333b0eebSGerd HoffmannForce using the specified IP version. 1110333b0eebSGerd Hoffmann 111129b0040bSGerd Hoffmann@item password=<secret> 111229b0040bSGerd HoffmannSet the password you need to authenticate. 111329b0040bSGerd Hoffmann 111448b3ed0aSMarc-André Lureau@item sasl 111548b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 111648b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 111748b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 111848b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 111948b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 112048b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 112148b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 112248b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 112348b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 112448b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 112548b3ed0aSMarc-André Lureaucredentials. 112648b3ed0aSMarc-André Lureau 112729b0040bSGerd Hoffmann@item disable-ticketing 112829b0040bSGerd HoffmannAllow client connects without authentication. 112929b0040bSGerd Hoffmann 1130d4970b07SHans de Goede@item disable-copy-paste 1131d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1132d4970b07SHans de Goede 11335ad24e5fSHans de Goede@item disable-agent-file-xfer 11345ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 11355ad24e5fSHans de Goede 1136c448e855SGerd Hoffmann@item tls-port=<nr> 1137c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1138c448e855SGerd Hoffmann 1139c448e855SGerd Hoffmann@item x509-dir=<dir> 1140c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1141c448e855SGerd Hoffmann 1142c448e855SGerd Hoffmann@item x509-key-file=<file> 1143f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1144f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1145f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1146f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1147c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1148c448e855SGerd Hoffmann 1149c448e855SGerd Hoffmann@item tls-ciphers=<list> 1150c448e855SGerd HoffmannSpecify which ciphers to use. 1151c448e855SGerd Hoffmann 1152d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1153f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 115417b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 115517b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 115617b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 115717b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 115817b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 115917b6dea0SGerd Hoffmann 11609f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 11619f04e09eSYonit HalperinConfigure image compression (lossless). 11629f04e09eSYonit HalperinDefault is auto_glz. 11639f04e09eSYonit Halperin 11649f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1165f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 11669f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 11679f04e09eSYonit HalperinDefault is auto. 11689f04e09eSYonit Halperin 116984a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 117093ca519eSLi ZhijianConfigure video stream detection. Default is off. 117184a23f25SGerd Hoffmann 117284a23f25SGerd Hoffmann@item agent-mouse=[on|off] 117384a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 117484a23f25SGerd Hoffmann 117584a23f25SGerd Hoffmann@item playback-compression=[on|off] 117684a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 117784a23f25SGerd Hoffmann 11788c957053SYonit Halperin@item seamless-migration=[on|off] 11798c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 11808c957053SYonit Halperin 1181474114b7SGerd Hoffmann@item gl=[on|off] 1182474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1183474114b7SGerd Hoffmann 11847b525508SMarc-André Lureau@item rendernode=<file> 11857b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 11867b525508SMarc-André Lureauthe first available. (Since 2.9) 11877b525508SMarc-André Lureau 118829b0040bSGerd Hoffmann@end table 118929b0040bSGerd HoffmannETEXI 119029b0040bSGerd Hoffmann 11915824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1192ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1193ad96090aSBlue Swirl QEMU_ARCH_ALL) 11945824d651Sblueswir1STEXI 11955824d651Sblueswir1@item -portrait 11966616b2adSStefan Weil@findex -portrait 11975824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 11985824d651Sblueswir1ETEXI 11995824d651Sblueswir1 12009312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 12019312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 12029312805dSVasily Khoruzhick QEMU_ARCH_ALL) 12039312805dSVasily KhoruzhickSTEXI 12046265c43bSMarkus Armbruster@item -rotate @var{deg} 12059312805dSVasily Khoruzhick@findex -rotate 12069312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 12079312805dSVasily KhoruzhickETEXI 12089312805dSVasily Khoruzhick 12095824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1210a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1211ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 12125824d651Sblueswir1STEXI 1213e4558dcaSmalc@item -vga @var{type} 12146616b2adSStefan Weil@findex -vga 12155824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1216b3f046c2SKevin Wolf@table @option 12175824d651Sblueswir1@item cirrus 12185824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 12195824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 12205824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 122141eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 12225824d651Sblueswir1@item std 12235824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 12245824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 12255824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 122641eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 12275824d651Sblueswir1@item vmware 12285824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 12295824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 12305824d651Sblueswir1card. 1231a19cbfb3SGerd Hoffmann@item qxl 1232a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1233a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1234a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 123533632788SMark Cave-Ayland@item tcx 123633632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 123733632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 123833632788SMark Cave-Aylandfixed resolution of 1024x768. 123933632788SMark Cave-Ayland@item cg3 124033632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 124133632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 124233632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1243a94f0c5cSGerd Hoffmann@item virtio 1244a94f0c5cSGerd HoffmannVirtio VGA card. 12455824d651Sblueswir1@item none 12465824d651Sblueswir1Disable VGA card. 12475824d651Sblueswir1@end table 12485824d651Sblueswir1ETEXI 12495824d651Sblueswir1 12505824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1251ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 12525824d651Sblueswir1STEXI 12535824d651Sblueswir1@item -full-screen 12546616b2adSStefan Weil@findex -full-screen 12555824d651Sblueswir1Start in full screen. 12565824d651Sblueswir1ETEXI 12575824d651Sblueswir1 12585824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1259ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1260ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 12615824d651Sblueswir1STEXI 126295d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 12636616b2adSStefan Weil@findex -g 126495d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 12655824d651Sblueswir1ETEXI 12665824d651Sblueswir1 12675824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1268f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 12695824d651Sblueswir1STEXI 12705824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 12716616b2adSStefan Weil@findex -vnc 1272dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1273dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1274dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1275dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1276dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1277dc0a3e44SColin Lord(option @option{-usbdevice tablet}). When using the VNC display, you 1278dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1279dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 12805824d651Sblueswir1 1281b3f046c2SKevin Wolf@table @option 12825824d651Sblueswir1 128399a9a52aSRobert Ho@item to=@var{L} 128499a9a52aSRobert Ho 128599a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 128699a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 128799a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 128899a9a52aSRobert Hoapplication. By default, to=0. 128999a9a52aSRobert Ho 12905824d651Sblueswir1@item @var{host}:@var{d} 12915824d651Sblueswir1 12925824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 12935824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 12945824d651Sblueswir1be omitted in which case the server will accept connections from any host. 12955824d651Sblueswir1 12964e257e5eSKevin Wolf@item unix:@var{path} 12975824d651Sblueswir1 12985824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 12995824d651Sblueswir1location of a unix socket to listen for connections on. 13005824d651Sblueswir1 13015824d651Sblueswir1@item none 13025824d651Sblueswir1 13035824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 13045824d651Sblueswir1can be used to later start the VNC server. 13055824d651Sblueswir1 13065824d651Sblueswir1@end table 13075824d651Sblueswir1 13085824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 13095824d651Sblueswir1separated by commas. Valid options are 13105824d651Sblueswir1 1311b3f046c2SKevin Wolf@table @option 13125824d651Sblueswir1 13135824d651Sblueswir1@item reverse 13145824d651Sblueswir1 13155824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 13165824d651Sblueswir1client is specified by the @var{display}. For reverse network 13175824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 13185824d651Sblueswir1is a TCP port number, not a display number. 13195824d651Sblueswir1 13207536ee4bSTim Hardeck@item websocket 13217536ee4bSTim Hardeck 13227536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1323275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 1324275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 1325275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 1326275e0d61SDaniel P. Berrange 1327275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 1328275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 1329275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 1330275e0d61SDaniel P. Berrange 13313e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 13323e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 13333e305e4aSDaniel P. Berrangerequires encrypted client connections. 13347536ee4bSTim Hardeck 13355824d651Sblueswir1@item password 13365824d651Sblueswir1 13375824d651Sblueswir1Require that password based authentication is used for client connections. 133886ee5bc3SMichal Novotny 133986ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 134086ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 134186ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 134286ee5bc3SMichal Novotny"vnc" or "spice". 134386ee5bc3SMichal Novotny 134486ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 134586ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 134686ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 134786ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 134886ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 134986ee5bc3SMichal Novotnydate and time). 135086ee5bc3SMichal Novotny 135186ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 135286ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 13535824d651Sblueswir1 13543e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 13553e305e4aSDaniel P. Berrange 13563e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 13573e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 13583e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 13593e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 13603e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 13613e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 13623e305e4aSDaniel P. Berrange 13633e305e4aSDaniel P. BerrangeThe @option{tls-creds} parameter obsoletes the @option{tls}, 13643e305e4aSDaniel P. Berrange@option{x509}, and @option{x509verify} options, and as such 13653e305e4aSDaniel P. Berrangeit is not permitted to set both new and old type options at 13663e305e4aSDaniel P. Berrangethe same time. 13673e305e4aSDaniel P. Berrange 13685824d651Sblueswir1@item tls 13695824d651Sblueswir1 13705824d651Sblueswir1Require that client use TLS when communicating with the VNC server. This 13715824d651Sblueswir1uses anonymous TLS credentials so is susceptible to a man-in-the-middle 13725824d651Sblueswir1attack. It is recommended that this option be combined with either the 13734e257e5eSKevin Wolf@option{x509} or @option{x509verify} options. 13745824d651Sblueswir1 13753e305e4aSDaniel P. BerrangeThis option is now deprecated in favor of using the @option{tls-creds} 13763e305e4aSDaniel P. Berrangeargument. 13773e305e4aSDaniel P. Berrange 13785824d651Sblueswir1@item x509=@var{/path/to/certificate/dir} 13795824d651Sblueswir1 13805824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 13815824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 13825824d651Sblueswir1to the client. It is recommended that a password be set on the VNC server 13835824d651Sblueswir1to provide authentication of the client when this is used. The path following 13845824d651Sblueswir1this option specifies where the x509 certificates are to be loaded from. 13855824d651Sblueswir1See the @ref{vnc_security} section for details on generating certificates. 13865824d651Sblueswir1 13873e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 13883e305e4aSDaniel P. Berrangeargument. 13893e305e4aSDaniel P. Berrange 13905824d651Sblueswir1@item x509verify=@var{/path/to/certificate/dir} 13915824d651Sblueswir1 13925824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 13935824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 13945824d651Sblueswir1to the client, and request that the client send its own x509 certificate. 13955824d651Sblueswir1The server will validate the client's certificate against the CA certificate, 13965824d651Sblueswir1and reject clients when validation fails. If the certificate authority is 13975824d651Sblueswir1trusted, this is a sufficient authentication mechanism. You may still wish 13985824d651Sblueswir1to set a password on the VNC server as a second authentication layer. The 13995824d651Sblueswir1path following this option specifies where the x509 certificates are to 14005824d651Sblueswir1be loaded from. See the @ref{vnc_security} section for details on generating 14015824d651Sblueswir1certificates. 14025824d651Sblueswir1 14033e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 14043e305e4aSDaniel P. Berrangeargument. 14053e305e4aSDaniel P. Berrange 14065824d651Sblueswir1@item sasl 14075824d651Sblueswir1 14085824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 14095824d651Sblueswir1The exact choice of authentication method used is controlled from the 14105824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 14115824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 14125824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 14135824d651Sblueswir1to make it search alternate locations for the service config. 14145824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 14155824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 14165824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 14175824d651Sblueswir1ensures a data encryption preventing compromise of authentication 14185824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 14195824d651Sblueswir1SASL authentication. 14205824d651Sblueswir1 14215824d651Sblueswir1@item acl 14225824d651Sblueswir1 14235824d651Sblueswir1Turn on access control lists for checking of the x509 client certificate 14245824d651Sblueswir1and SASL party. For x509 certs, the ACL check is made against the 14255824d651Sblueswir1certificate's distinguished name. This is something that looks like 14265824d651Sblueswir1@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 14275824d651Sblueswir1made against the username, which depending on the SASL plugin, may 14285824d651Sblueswir1include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 14295824d651Sblueswir1When the @option{acl} flag is set, the initial access list will be 14305824d651Sblueswir1empty, with a @code{deny} policy. Thus no one will be allowed to 14315824d651Sblueswir1use the VNC server until the ACLs have been loaded. This can be 14325824d651Sblueswir1achieved using the @code{acl} monitor command. 14335824d651Sblueswir1 14346f9c78c1SCorentin Chary@item lossy 14356f9c78c1SCorentin Chary 14366f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 14376f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 14386f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 14396f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 14406f9c78c1SCorentin Chary 144180e0c8c3SCorentin Chary@item non-adaptive 144280e0c8c3SCorentin Chary 144380e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 144480e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 144580e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 144661cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 14479d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 144880e0c8c3SCorentin Charylike Tight. 144980e0c8c3SCorentin Chary 14508cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 14518cf36489SGerd Hoffmann 14528cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 14538cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 14548cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 14558cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 14568cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 14578cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 14588cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 14598cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 14608cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 1461b65ee4faSStefan Weilspec but is traditional QEMU behavior. 14628cf36489SGerd Hoffmann 1463c5ce8333SGerd Hoffmann@item key-delay-ms 1464c5ce8333SGerd Hoffmann 1465c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 1466c5ce8333SGerd HoffmannDefault is 1. Keyboards are low-bandwidth devices, so this slowdown 1467c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 1468c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 1469c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 1470c5ce8333SGerd Hoffmann 14715824d651Sblueswir1@end table 14725824d651Sblueswir1ETEXI 14735824d651Sblueswir1 14745824d651Sblueswir1STEXI 14755824d651Sblueswir1@end table 14765824d651Sblueswir1ETEXI 1477a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 14785824d651Sblueswir1 147943f187a5SPaolo BonziniARCHHEADING(i386 target only, QEMU_ARCH_I386) 14805824d651Sblueswir1STEXI 14815824d651Sblueswir1@table @option 14825824d651Sblueswir1ETEXI 14835824d651Sblueswir1 14845824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1485ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1486ad96090aSBlue Swirl QEMU_ARCH_I386) 14875824d651Sblueswir1STEXI 14885824d651Sblueswir1@item -win2k-hack 14896616b2adSStefan Weil@findex -win2k-hack 14905824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 14915824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 14925824d651Sblueswir1slows down the IDE transfers). 14935824d651Sblueswir1ETEXI 14945824d651Sblueswir1 14951ed2fc1fSJan KiszkaHXCOMM Deprecated by -rtc 1496ad96090aSBlue SwirlDEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 14975824d651Sblueswir1 14985824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1499ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1500ad96090aSBlue Swirl QEMU_ARCH_I386) 15015824d651Sblueswir1STEXI 15025824d651Sblueswir1@item -no-fd-bootchk 15036616b2adSStefan Weil@findex -no-fd-bootchk 15044eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 15055824d651Sblueswir1be needed to boot from old floppy disks. 15065824d651Sblueswir1ETEXI 15075824d651Sblueswir1 15085824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1509f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 15105824d651Sblueswir1STEXI 15115824d651Sblueswir1@item -no-acpi 15126616b2adSStefan Weil@findex -no-acpi 15135824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 15145824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 15155824d651Sblueswir1only). 15165824d651Sblueswir1ETEXI 15175824d651Sblueswir1 15185824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1519ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 15205824d651Sblueswir1STEXI 15215824d651Sblueswir1@item -no-hpet 15226616b2adSStefan Weil@findex -no-hpet 15235824d651Sblueswir1Disable HPET support. 15245824d651Sblueswir1ETEXI 15255824d651Sblueswir1 15265824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1527104bf02eSMichael Tokarev "-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" 1528ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 15295824d651Sblueswir1STEXI 15305824d651Sblueswir1@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}]...] 15316616b2adSStefan Weil@findex -acpitable 15325824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 1533104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 1534104bf02eSMichael TokarevACPI headers (possible overridden by other options). 1535104bf02eSMichael TokarevFor data=, only data 1536104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 1537104bf02eSMichael Tokarevcommand line. 1538ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 1539ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 1540ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 1541ae123749SLaszlo Ersekspec. 15425824d651Sblueswir1ETEXI 15435824d651Sblueswir1 1544b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1545b6f6e3d3Saliguori "-smbios file=binary\n" 1546ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 1547b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1548b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 1549ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 1550b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1551b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 1552b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 1553b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1554b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 1555b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 1556b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1557b155eb1dSGabriel L. Somlo " [,sku=str]\n" 1558b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 1559b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1560b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 1561b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 1562b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 15633ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 1564b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 1565c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1566b6f6e3d3SaliguoriSTEXI 1567b6f6e3d3Saliguori@item -smbios file=@var{binary} 15686616b2adSStefan Weil@findex -smbios 1569b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 1570b6f6e3d3Saliguori 157184351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1572b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 1573b6f6e3d3Saliguori 1574b6f6e3d3Saliguori@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}] 1575b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 1576b155eb1dSGabriel L. Somlo 1577b155eb1dSGabriel L. Somlo@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}] 1578b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 1579b155eb1dSGabriel L. Somlo 1580b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1581b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 1582b155eb1dSGabriel L. Somlo 1583b155eb1dSGabriel L. Somlo@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}] 1584b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 1585b155eb1dSGabriel L. Somlo 15863ebd6cc8SGabriel L. Somlo@item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}] 1587b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 1588b6f6e3d3SaliguoriETEXI 1589b6f6e3d3Saliguori 15905824d651Sblueswir1STEXI 15915824d651Sblueswir1@end table 15925824d651Sblueswir1ETEXI 1593c70a01e4SMarkus ArmbrusterDEFHEADING() 15945824d651Sblueswir1 159543f187a5SPaolo BonziniDEFHEADING(Network options) 15965824d651Sblueswir1STEXI 15975824d651Sblueswir1@table @option 15985824d651Sblueswir1ETEXI 15995824d651Sblueswir1 1600ad196a9dSJan KiszkaHXCOMM Legacy slirp options (now moved to -net user): 1601ad196a9dSJan Kiszka#ifdef CONFIG_SLIRP 1602ad96090aSBlue SwirlDEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1603ad96090aSBlue SwirlDEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1604ad96090aSBlue SwirlDEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1605ad196a9dSJan Kiszka#ifndef _WIN32 1606ad96090aSBlue SwirlDEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1607ad196a9dSJan Kiszka#endif 1608ad196a9dSJan Kiszka#endif 1609ad196a9dSJan Kiszka 16106a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 16115824d651Sblueswir1#ifdef CONFIG_SLIRP 16120b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 16130b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 16140b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 1615d8eb3864SSamuel Thibault " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n" 161663d2960bSKlaus Stengel " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1617ad196a9dSJan Kiszka#ifndef _WIN32 1618c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 1619ad196a9dSJan Kiszka#endif 16206a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 16216a8b4a5bSThomas Huth " its DHCP server and optional services\n" 16225824d651Sblueswir1#endif 16235824d651Sblueswir1#ifdef _WIN32 16246a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 16256a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 16265824d651Sblueswir1#else 16276a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 1628584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 16296a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 163069e87b32SJason Wang " [,poll-us=n]\n" 16316a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 1632584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 1633a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1634a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1635a7c36ee4SCorey Bryant " to deconfigure it\n" 1636ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 1637a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1638a7c36ee4SCorey Bryant " configure it\n" 16395824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 16402ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1641ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1642f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1643ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1644ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 164582b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 16465430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 16475430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 164882b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 16492ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1650ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 165169e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 165269e87b32SJason Wang " spent on busy polling for vhost net\n" 16536a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 16546a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 16556a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 16566a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 16570df0ff6dSMark McLoughlin#endif 16583fb69aa1SAnton Ivanov#ifdef __linux__ 16596a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 16606a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 16616a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 16626a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 16636a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 16646a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 16653fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 16662f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 16673fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 16683fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 16693fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 16703fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 16713fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 16723fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 16733952651aSGonglei " use 'srcport=' to specify source udp port\n" 16743fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 16753fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 16763fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 16773fb69aa1SAnton Ivanov " well as a weak security measure\n" 16783fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 16793fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 16803fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 16813fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 16823fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 16833fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 16843fb69aa1SAnton Ivanov#endif 16856a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 16866a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 16876a8b4a5bSThomas Huth " using a socket connection\n" 16886a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 16896a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 16903a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 16916a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 16926a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 16936a8b4a5bSThomas Huth " using an UDP tunnel\n" 16945824d651Sblueswir1#ifdef CONFIG_VDE 16956a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 16966a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 16976a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 16985824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 16995824d651Sblueswir1 " ownership and permissions for communication port.\n" 17005824d651Sblueswir1#endif 170158952137SVincenzo Maffione#ifdef CONFIG_NETMAP 17026a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 170358952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 170458952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 170558952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 170658952137SVincenzo Maffione#endif 17076a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 17086a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 17096a8b4a5bSThomas Huth "-netdev hubport,id=str,hubid=n\n" 17106a8b4a5bSThomas Huth " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL) 17116a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 17126a8b4a5bSThomas Huth "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 17136a8b4a5bSThomas Huth " old way to create a new NIC and connect it to VLAN 'n'\n" 17146a8b4a5bSThomas Huth " (use the '-device devtype,netdev=str' option if possible instead)\n" 1715bb9ea79eSaliguori "-net dump[,vlan=n][,file=f][,len=n]\n" 1716bb9ea79eSaliguori " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 1717ca1a8a06SBruce Rogers "-net none use it alone to have zero network devices. If no -net option\n" 17186a8b4a5bSThomas Huth " is provided, the default is '-net nic -net user'\n" 17196a8b4a5bSThomas Huth "-net [" 1720a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 1721a1ea458fSMark McLoughlin "user|" 1722a1ea458fSMark McLoughlin#endif 1723a1ea458fSMark McLoughlin "tap|" 1724a7c36ee4SCorey Bryant "bridge|" 1725a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 1726a1ea458fSMark McLoughlin "vde|" 1727a1ea458fSMark McLoughlin#endif 172858952137SVincenzo Maffione#ifdef CONFIG_NETMAP 172958952137SVincenzo Maffione "netmap|" 173058952137SVincenzo Maffione#endif 17316a8b4a5bSThomas Huth "socket][,vlan=n][,option][,option][,...]\n" 17326a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 17336a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 17345824d651Sblueswir1STEXI 1735ffe6370cSMichael S. Tsirkin@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 17366616b2adSStefan Weil@findex -net 17375824d651Sblueswir1Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 17380d6b0b1dSAnthony Liguori= 0 is the default). The NIC is an e1000 by default on the PC 17395607c388SMarkus Armbrustertarget. Optionally, the MAC address can be changed to @var{mac}, the 17405607c388SMarkus Armbrusterdevice address set to @var{addr} (PCI cards only), 1741ffe6370cSMichael S. Tsirkinand a @var{name} can be assigned for use in monitor commands. 1742ffe6370cSMichael S. TsirkinOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 1743ffe6370cSMichael S. Tsirkinthat the card should have; this option currently only affects virtio cards; set 1744ffe6370cSMichael S. Tsirkin@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 1745071c9394SStefan WeilNIC is created. QEMU can emulate several different models of network card. 17465824d651Sblueswir1Valid values for @var{type} are 1747ffe6370cSMichael S. Tsirkin@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 17485824d651Sblueswir1@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 17495824d651Sblueswir1@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 1750585f6036SPeter MaydellNot all devices are supported on all targets. Use @code{-net nic,model=help} 17515824d651Sblueswir1for a list of available devices for your target. 17525824d651Sblueswir1 175308d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1754b8f490ebSMarkus Armbruster@findex -netdev 1755ad196a9dSJan Kiszka@item -net user[,@var{option}][,@var{option}][,...] 17565824d651Sblueswir1Use the user mode network stack which requires no administrator 1757ad196a9dSJan Kiszkaprivilege to run. Valid options are: 17585824d651Sblueswir1 1759b3f046c2SKevin Wolf@table @option 1760ad196a9dSJan Kiszka@item vlan=@var{n} 1761ad196a9dSJan KiszkaConnect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 1762ad196a9dSJan Kiszka 176308d12022SStefan Hajnoczi@item id=@var{id} 1764f9cfd655SMarkus Armbruster@itemx name=@var{name} 1765ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 1766ad196a9dSJan Kiszka 17670b11c036SSamuel Thibault@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must 17680b11c036SSamuel Thibaultbe enabled. If neither is specified both protocols are enabled. 17690b11c036SSamuel Thibault 1770c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 1771c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 1772c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 1773b0b36e5dSBrad Hards10.0.2.0/24. 1774c92ef6a2SJan Kiszka 1775c92ef6a2SJan Kiszka@item host=@var{addr} 1776c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 1777c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 1778ad196a9dSJan Kiszka 1779d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 1780d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 1781d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 1782d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 1783d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 17847aac531eSYann Bordenave 1785d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 17867aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 17877aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 17887aac531eSYann Bordenave 1789c54ed5bcSJan Kiszka@item restrict=on|off 1790caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 1791ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 1792caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 1793ad196a9dSJan Kiszka 1794ad196a9dSJan Kiszka@item hostname=@var{name} 179563d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 1796ad196a9dSJan Kiszka 1797c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 1798c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 1799b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 1800c92ef6a2SJan Kiszka 1801c92ef6a2SJan Kiszka@item dns=@var{addr} 1802c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 1803c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 1804c92ef6a2SJan Kiszkai.e. x.x.x.3. 1805c92ef6a2SJan Kiszka 1806d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 18077aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 18087aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 18097aac531eSYann Bordenavenetwork, i.e. xxxx::3. 18107aac531eSYann Bordenave 181163d2960bSKlaus Stengel@item dnssearch=@var{domain} 181263d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 181363d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 181463d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 181563d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 181663d2960bSKlaus Stengelcan not be resolved. 181763d2960bSKlaus Stengel 181863d2960bSKlaus StengelExample: 181963d2960bSKlaus Stengel@example 182063d2960bSKlaus Stengelqemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 182163d2960bSKlaus Stengel@end example 182263d2960bSKlaus Stengel 1823ad196a9dSJan Kiszka@item tftp=@var{dir} 1824ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 1825ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 1826ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 1827c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 1828ad196a9dSJan Kiszka 1829ad196a9dSJan Kiszka@item bootfile=@var{file} 1830ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 1831ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 1832ad196a9dSJan Kiszkaa guest from a local directory. 1833ad196a9dSJan Kiszka 1834ad196a9dSJan KiszkaExample (using pxelinux): 1835ad196a9dSJan Kiszka@example 18363804da9dSStefan Weilqemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 1837ad196a9dSJan Kiszka@end example 1838ad196a9dSJan Kiszka 1839c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 1840ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 1841ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 1842c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 1843c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 1844ad196a9dSJan Kiszka 1845ad196a9dSJan KiszkaIn the guest Windows OS, the line: 1846ad196a9dSJan Kiszka@example 1847ad196a9dSJan Kiszka10.0.2.4 smbserver 1848ad196a9dSJan Kiszka@end example 1849ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 1850ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 1851ad196a9dSJan Kiszka 1852ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 1853ad196a9dSJan Kiszka 1854e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 1855e2d8830eSBradQEMU was tested successfully with smbd versions from Red Hat 9, 1856e2d8830eSBradFedora Core 3 and OpenSUSE 11.x. 1857ad196a9dSJan Kiszka 18583c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 1859c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 1860c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 1861c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 18623c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 18633c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 1864c92ef6a2SJan Kiszkaused. This option can be given multiple times. 1865ad196a9dSJan Kiszka 1866ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 1867ad196a9dSJan Kiszkascreen 0, use the following: 1868ad196a9dSJan Kiszka 1869ad196a9dSJan Kiszka@example 1870ad196a9dSJan Kiszka# on the host 18713804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 1872ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 1873ad196a9dSJan Kiszkaxterm -display :1 1874ad196a9dSJan Kiszka@end example 1875ad196a9dSJan Kiszka 1876ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 1877ad196a9dSJan Kiszkathe guest, use the following: 1878ad196a9dSJan Kiszka 1879ad196a9dSJan Kiszka@example 1880ad196a9dSJan Kiszka# on the host 18813804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 1882ad196a9dSJan Kiszkatelnet localhost 5555 1883ad196a9dSJan Kiszka@end example 1884ad196a9dSJan Kiszka 1885ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 1886ad196a9dSJan Kiszkaconnect to the guest telnet server. 1887ad196a9dSJan Kiszka 1888c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 1889f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 18903c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 1891b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 1892b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 1893b412eb61SAlexander Graf 189443ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 1895b412eb61SAlexander Graflifetime, like in the following example: 1896b412eb61SAlexander Graf 1897b412eb61SAlexander Graf@example 1898b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 1899b412eb61SAlexander Graf# the guest accesses it 1900b412eb61SAlexander Grafqemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 1901b412eb61SAlexander Graf@end example 1902b412eb61SAlexander Graf 1903b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 190443ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 1905b412eb61SAlexander Graf 1906b412eb61SAlexander Graf@example 1907b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 1908b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 1909b412eb61SAlexander Grafqemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 1910b412eb61SAlexander Graf@end example 1911ad196a9dSJan Kiszka 1912ad196a9dSJan Kiszka@end table 1913ad196a9dSJan Kiszka 1914ad196a9dSJan KiszkaNote: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 1915ad196a9dSJan Kiszkaprocessed and applied to -net user. Mixing them with the new configuration 1916ad196a9dSJan Kiszkasyntax gives undefined results. Their use for new applications is discouraged 1917ad196a9dSJan Kiszkaas they will be removed from future versions. 19185824d651Sblueswir1 1919584613eaSAlexey Kardashevskiy@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}] 1920584613eaSAlexey Kardashevskiy@itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}] 1921a7c36ee4SCorey BryantConnect the host TAP network interface @var{name} to VLAN @var{n}. 1922a7c36ee4SCorey Bryant 1923a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 19245824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 1925a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 1926a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 1927a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 1928a7c36ee4SCorey Bryantto disable script execution. 1929a7c36ee4SCorey Bryant 1930a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 1931584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 1932584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 1933584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 1934a7c36ee4SCorey Bryant 1935a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 1936a7c36ee4SCorey Bryantopened host TAP interface. 1937a7c36ee4SCorey Bryant 1938a7c36ee4SCorey BryantExamples: 19395824d651Sblueswir1 19405824d651Sblueswir1@example 1941a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 19423804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net tap 19435824d651Sblueswir1@end example 19445824d651Sblueswir1 19455824d651Sblueswir1@example 1946a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 1947a7c36ee4SCorey Bryant#to a TAP device 19483804da9dSStefan Weilqemu-system-i386 linux.img \ 19493804da9dSStefan Weil -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 19505824d651Sblueswir1 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 19515824d651Sblueswir1@end example 19525824d651Sblueswir1 1953a7c36ee4SCorey Bryant@example 1954a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1955a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 19563804da9dSStefan Weilqemu-system-i386 linux.img \ 1957420508fbSAmos Kong -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 1958a7c36ee4SCorey Bryant@end example 1959a7c36ee4SCorey Bryant 196008d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 1961f9cfd655SMarkus Armbruster@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 1962a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 1963a7c36ee4SCorey Bryant 1964a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 1965a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 1966420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 1967a7c36ee4SCorey Bryantdevice is @file{br0}. 1968a7c36ee4SCorey Bryant 1969a7c36ee4SCorey BryantExamples: 1970a7c36ee4SCorey Bryant 1971a7c36ee4SCorey Bryant@example 1972a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1973a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 19743804da9dSStefan Weilqemu-system-i386 linux.img -net bridge -net nic,model=virtio 1975a7c36ee4SCorey Bryant@end example 1976a7c36ee4SCorey Bryant 1977a7c36ee4SCorey Bryant@example 1978a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 1979a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 19803804da9dSStefan Weilqemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 1981a7c36ee4SCorey Bryant@end example 1982a7c36ee4SCorey Bryant 198308d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1984f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 19855824d651Sblueswir1 19865824d651Sblueswir1Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 19875824d651Sblueswir1machine using a TCP socket connection. If @option{listen} is 19885824d651Sblueswir1specified, QEMU waits for incoming connections on @var{port} 19895824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 19905824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 19915824d651Sblueswir1specifies an already opened TCP socket. 19925824d651Sblueswir1 19935824d651Sblueswir1Example: 19945824d651Sblueswir1@example 19955824d651Sblueswir1# launch a first QEMU instance 19963804da9dSStefan Weilqemu-system-i386 linux.img \ 19973804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 19985824d651Sblueswir1 -net socket,listen=:1234 19995824d651Sblueswir1# connect the VLAN 0 of this instance to the VLAN 0 20005824d651Sblueswir1# of the first instance 20013804da9dSStefan Weilqemu-system-i386 linux.img \ 20023804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 20035824d651Sblueswir1 -net socket,connect=127.0.0.1:1234 20045824d651Sblueswir1@end example 20055824d651Sblueswir1 200608d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 2007f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 20085824d651Sblueswir1 20095824d651Sblueswir1Create a VLAN @var{n} shared with another QEMU virtual 20105824d651Sblueswir1machines using a UDP multicast socket, effectively making a bus for 20115824d651Sblueswir1every QEMU with same multicast address @var{maddr} and @var{port}. 20125824d651Sblueswir1NOTES: 20135824d651Sblueswir1@enumerate 20145824d651Sblueswir1@item 20155824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 20165824d651Sblueswir1correct multicast setup for these hosts). 20175824d651Sblueswir1@item 20185824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 20195824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 20205824d651Sblueswir1@item 20215824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 20225824d651Sblueswir1@end enumerate 20235824d651Sblueswir1 20245824d651Sblueswir1Example: 20255824d651Sblueswir1@example 20265824d651Sblueswir1# launch one QEMU instance 20273804da9dSStefan Weilqemu-system-i386 linux.img \ 20283804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 20295824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 20305824d651Sblueswir1# launch another QEMU instance on same "bus" 20313804da9dSStefan Weilqemu-system-i386 linux.img \ 20323804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 20335824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 20345824d651Sblueswir1# launch yet another QEMU instance on same "bus" 20353804da9dSStefan Weilqemu-system-i386 linux.img \ 20363804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:58 \ 20375824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 20385824d651Sblueswir1@end example 20395824d651Sblueswir1 20405824d651Sblueswir1Example (User Mode Linux compat.): 20415824d651Sblueswir1@example 20425824d651Sblueswir1# launch QEMU instance (note mcast address selected 20435824d651Sblueswir1# is UML's default) 20443804da9dSStefan Weilqemu-system-i386 linux.img \ 20453804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 20465824d651Sblueswir1 -net socket,mcast=239.192.168.1:1102 20475824d651Sblueswir1# launch UML 20485824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 20495824d651Sblueswir1@end example 20505824d651Sblueswir1 20513a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 20523a75e74cSMike Ryan@example 20533804da9dSStefan Weilqemu-system-i386 linux.img \ 20543804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 20553a75e74cSMike Ryan -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 20563a75e74cSMike Ryan@end example 20573a75e74cSMike Ryan 20583fb69aa1SAnton Ivanov@item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}] 2059f9cfd655SMarkus Armbruster@itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}] 20603fb69aa1SAnton IvanovConnect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular 20613fb69aa1SAnton Ivanovprotocol to transport Ethernet (and other Layer 2) data frames between 20623fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 20633fb69aa1SAnton Ivanov(from version 3.3 onwards). 20643fb69aa1SAnton Ivanov 20653fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 20663fb69aa1SAnton Ivanov 20673fb69aa1SAnton Ivanov@item src=@var{srcaddr} 20683fb69aa1SAnton Ivanov source address (mandatory) 20693fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 20703fb69aa1SAnton Ivanov destination address (mandatory) 20713fb69aa1SAnton Ivanov@item udp 20723fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 20733fb69aa1SAnton Ivanov@item srcport=@var{srcport} 20743fb69aa1SAnton Ivanov source udp port. 20753fb69aa1SAnton Ivanov@item dstport=@var{dstport} 20763fb69aa1SAnton Ivanov destination udp port. 20773fb69aa1SAnton Ivanov@item ipv6 20783fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 20793fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2080f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 20813fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 20823fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 20833fb69aa1SAnton Ivanovbit. 20843fb69aa1SAnton Ivanov@item cookie64 20853fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 20863fb69aa1SAnton Ivanov@item counter=off 20873fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 20883fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 20893fb69aa1SAnton Ivanov@item pincounter=on 20903fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 20913fb69aa1SAnton Ivanovnetworks which have packet reorder. 20923fb69aa1SAnton Ivanov@item offset=@var{offset} 20933fb69aa1SAnton Ivanov Add an extra offset between header and data 20943fb69aa1SAnton Ivanov 20953fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 20963fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 20973fb69aa1SAnton Ivanov@example 20983fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 20993fb69aa1SAnton Ivanov# on 1.2.3.4 21003fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 21013fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 21023fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 21033fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 21043fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 21053fb69aa1SAnton Ivanovifconfig vmtunnel0 up 21063fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 21073fb69aa1SAnton Ivanov 21083fb69aa1SAnton Ivanov 21093fb69aa1SAnton Ivanov# on 4.3.2.1 21103fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 21113fb69aa1SAnton Ivanov 21123fb69aa1SAnton Ivanovqemu-system-i386 linux.img -net nic -net l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 21133fb69aa1SAnton Ivanov 21143fb69aa1SAnton Ivanov 21153fb69aa1SAnton Ivanov@end example 21163fb69aa1SAnton Ivanov 211708d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2118f9cfd655SMarkus Armbruster@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 21195824d651Sblueswir1Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 21205824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 21215824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2122c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 21235824d651Sblueswir1with vde support enabled. 21245824d651Sblueswir1 21255824d651Sblueswir1Example: 21265824d651Sblueswir1@example 21275824d651Sblueswir1# launch vde switch 21285824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 21295824d651Sblueswir1# launch QEMU instance 21303804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 21315824d651Sblueswir1@end example 21325824d651Sblueswir1 213340e8c26dSStefan Hajnoczi@item -netdev hubport,id=@var{id},hubid=@var{hubid} 213440e8c26dSStefan Hajnoczi 213540e8c26dSStefan HajnocziCreate a hub port on QEMU "vlan" @var{hubid}. 213640e8c26dSStefan Hajnoczi 213740e8c26dSStefan HajnocziThe hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 213840e8c26dSStefan Hajnoczinetdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 213940e8c26dSStefan Hajnoczirequired hub automatically. 214040e8c26dSStefan Hajnoczi 2141b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 214203ce5744SNikolay Nikolaev 214303ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 214403ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 214503ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 214603ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2147b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2148b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 214903ce5744SNikolay Nikolaev 215003ce5744SNikolay NikolaevExample: 215103ce5744SNikolay Nikolaev@example 215203ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 215303ce5744SNikolay Nikolaev -numa node,memdev=mem \ 215403ce5744SNikolay Nikolaev -chardev socket,path=/path/to/socket \ 215503ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 215603ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 215703ce5744SNikolay Nikolaev@end example 215803ce5744SNikolay Nikolaev 2159bb9ea79eSaliguori@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 2160bb9ea79eSaliguoriDump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 2161bb9ea79eSaliguoriAt most @var{len} bytes (64k by default) per packet are stored. The file format is 2162bb9ea79eSaliguorilibpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 2163d3e0c032SThomas HuthNote: For devices created with '-netdev', use '-object filter-dump,...' instead. 2164bb9ea79eSaliguori 21655824d651Sblueswir1@item -net none 21665824d651Sblueswir1Indicate that no network devices should be configured. It is used to 21675824d651Sblueswir1override the default configuration (@option{-net nic -net user}) which 21685824d651Sblueswir1is activated if no @option{-net} options are provided. 21695824d651Sblueswir1ETEXI 21705824d651Sblueswir1 2171c70a01e4SMarkus ArmbrusterSTEXI 2172c70a01e4SMarkus Armbruster@end table 2173c70a01e4SMarkus ArmbrusterETEXI 21747273a2dbSMatthew BoothDEFHEADING() 21757273a2dbSMatthew Booth 217643f187a5SPaolo BonziniDEFHEADING(Character device options) 2177c70a01e4SMarkus ArmbrusterSTEXI 2178c70a01e4SMarkus Armbruster 2179c70a01e4SMarkus ArmbrusterThe general form of a character device option is: 2180c70a01e4SMarkus Armbruster@table @option 2181c70a01e4SMarkus ArmbrusterETEXI 21827273a2dbSMatthew Booth 21837273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2184517b3d40SLin Ma "-chardev help\n" 2185d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21865dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2187d0d7708bSDaniel P. Berrange " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n" 2188a8fb5427SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n" 2189d0d7708bSDaniel P. Berrange "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n" 2190d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 21917273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 219297331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2193d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2194d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 21957273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2196d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2197d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2198d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2199d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 22007273a2dbSMatthew Booth#ifdef _WIN32 2201d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2202d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 22037273a2dbSMatthew Booth#else 2204d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2205d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 22067273a2dbSMatthew Booth#endif 22077273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2208d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 22097273a2dbSMatthew Booth#endif 22107273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 22117273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2212d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2213d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 22147273a2dbSMatthew Booth#endif 22157273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2216d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2217d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 22187273a2dbSMatthew Booth#endif 2219cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2220d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2221d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2222cbcc6336SAlon Levy#endif 2223ad96090aSBlue Swirl , QEMU_ARCH_ALL 22247273a2dbSMatthew Booth) 22257273a2dbSMatthew Booth 22267273a2dbSMatthew BoothSTEXI 222797331287SJan Kiszka@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 22286616b2adSStefan Weil@findex -chardev 22297273a2dbSMatthew BoothBackend is one of: 22307273a2dbSMatthew Booth@option{null}, 22317273a2dbSMatthew Booth@option{socket}, 22327273a2dbSMatthew Booth@option{udp}, 22337273a2dbSMatthew Booth@option{msmouse}, 22347273a2dbSMatthew Booth@option{vc}, 22354f57378fSMarkus Armbruster@option{ringbuf}, 22367273a2dbSMatthew Booth@option{file}, 22377273a2dbSMatthew Booth@option{pipe}, 22387273a2dbSMatthew Booth@option{console}, 22397273a2dbSMatthew Booth@option{serial}, 22407273a2dbSMatthew Booth@option{pty}, 22417273a2dbSMatthew Booth@option{stdio}, 22427273a2dbSMatthew Booth@option{braille}, 22437273a2dbSMatthew Booth@option{tty}, 224488a946d3SGerd Hoffmann@option{parallel}, 2245cbcc6336SAlon Levy@option{parport}, 2246cbcc6336SAlon Levy@option{spicevmc}. 22475a49d3e9SMarc-André Lureau@option{spiceport}. 22487273a2dbSMatthew BoothThe specific backend will determine the applicable options. 22497273a2dbSMatthew Booth 2250517b3d40SLin MaUse "-chardev help" to print all available chardev backend types. 2251517b3d40SLin Ma 22527273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 22537273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 22547273a2dbSMatthew Booth 225597331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2256a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2257a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2258a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2259a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2260a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2261a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2262a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2263a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2264a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2265a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2266a40db1b3SPeter Maydell 2267a40db1b3SPeter Maydell@example 2268a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2269bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2270a40db1b3SPeter Maydell-serial chardev:char0 \ 2271a40db1b3SPeter Maydell-serial chardev:char0 2272a40db1b3SPeter Maydell@end example 2273a40db1b3SPeter Maydell 2274a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2275a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2276a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2277a40db1b3SPeter Maydell 2278a40db1b3SPeter Maydell@example 2279a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2280bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2281a40db1b3SPeter Maydell-parallel chardev:char0 \ 2282a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2283a40db1b3SPeter Maydell-serial chardev:char1 \ 2284a40db1b3SPeter Maydell-serial chardev:char1 2285a40db1b3SPeter Maydell@end example 2286a40db1b3SPeter Maydell 2287a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2288a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2289a40db1b3SPeter Maydellmultiplexer}. 2290a40db1b3SPeter Maydell 2291a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2292a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2293a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2294a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2295a40db1b3SPeter Maydellstdio. 2296a40db1b3SPeter Maydell 2297a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2298a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 229997331287SJan Kiszka 2300d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2301d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2302d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2303d0d7708bSDaniel P. Berrangeopened. 2304d0d7708bSDaniel P. Berrange 2305d0d7708bSDaniel P. BerrangeFurther options to each backend are described below. 23067273a2dbSMatthew Booth 23077273a2dbSMatthew Booth@item -chardev null ,id=@var{id} 23087273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 23097273a2dbSMatthew Boothreceives. The null backend does not take any options. 23107273a2dbSMatthew Booth 2311a8fb5427SDaniel P. Berrange@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}] 23127273a2dbSMatthew Booth 23137273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 23147273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 23157273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 23167273a2dbSMatthew Booth 23177273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 23187273a2dbSMatthew Booth 23197273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 23207273a2dbSMatthew Boothconnect to a listening socket. 23217273a2dbSMatthew Booth 23227273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 23237273a2dbSMatthew Boothescape sequences. 23247273a2dbSMatthew Booth 23255dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 23265dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 23275dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 23285dd1f02bSCorey Minyard 2329a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2330a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2331a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2332a8fb5427SDaniel P. Berrangeargument. 2333a8fb5427SDaniel P. Berrange 23347273a2dbSMatthew BoothTCP and unix socket options are given below: 23357273a2dbSMatthew Booth 23367273a2dbSMatthew Booth@table @option 23377273a2dbSMatthew Booth 23388d533561SAurelien Jarno@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 23397273a2dbSMatthew Booth 23407273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 23417273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 23427273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 23437273a2dbSMatthew Booth 23447273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 23457273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 23467273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 23477273a2dbSMatthew Booth@option{port} is required. 23487273a2dbSMatthew Booth 23497273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 23507273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 23517273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 23527273a2dbSMatthew Boothas a port number. 23537273a2dbSMatthew Booth 23547273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 23557273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 23567273a2dbSMatthew Booth 23577273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 23587273a2dbSMatthew Booth 23597273a2dbSMatthew Booth@item unix options: path=@var{path} 23607273a2dbSMatthew Booth 23617273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 23627273a2dbSMatthew Boothrequired. 23637273a2dbSMatthew Booth 23647273a2dbSMatthew Booth@end table 23657273a2dbSMatthew Booth 23667273a2dbSMatthew Booth@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 23677273a2dbSMatthew Booth 23687273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 23697273a2dbSMatthew Booth 23707273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 23717273a2dbSMatthew Boothdefaults to @code{localhost}. 23727273a2dbSMatthew Booth 23737273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 23747273a2dbSMatthew Boothis required. 23757273a2dbSMatthew Booth 23767273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 23777273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 23787273a2dbSMatthew Booth 23797273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 23807273a2dbSMatthew Boothavailable local port will be used. 23817273a2dbSMatthew Booth 23827273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 23837273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 23847273a2dbSMatthew Booth 23857273a2dbSMatthew Booth@item -chardev msmouse ,id=@var{id} 23867273a2dbSMatthew Booth 23877273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 23887273a2dbSMatthew Boothtake any options. 23897273a2dbSMatthew Booth 23907273a2dbSMatthew Booth@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 23917273a2dbSMatthew Booth 23927273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 23937273a2dbSMatthew Boothsize. 23947273a2dbSMatthew Booth 23957273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 23967273a2dbSMatthew Booththe console, in pixels. 23977273a2dbSMatthew Booth 23987273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 23997273a2dbSMatthew Boothconsole with the given dimensions. 24007273a2dbSMatthew Booth 24014f57378fSMarkus Armbruster@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 240251767e7cSLei Li 24033949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 2404e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 240551767e7cSLei Li 24067273a2dbSMatthew Booth@item -chardev file ,id=@var{id} ,path=@var{path} 24077273a2dbSMatthew Booth 24087273a2dbSMatthew BoothLog all traffic received from the guest to a file. 24097273a2dbSMatthew Booth 24107273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 24117273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 24127273a2dbSMatthew Boothis required. 24137273a2dbSMatthew Booth 24147273a2dbSMatthew Booth@item -chardev pipe ,id=@var{id} ,path=@var{path} 24157273a2dbSMatthew Booth 24167273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 24177273a2dbSMatthew BoothWindows hosts and other hosts: 24187273a2dbSMatthew Booth 24197273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 24207273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 24217273a2dbSMatthew Booth 24227273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 24237273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 24247273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 24257273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 24267273a2dbSMatthew Boothbe present. 24277273a2dbSMatthew Booth 24287273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 24297273a2dbSMatthew Boothrequired. 24307273a2dbSMatthew Booth 24317273a2dbSMatthew Booth@item -chardev console ,id=@var{id} 24327273a2dbSMatthew Booth 24337273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 24347273a2dbSMatthew Boothtake any options. 24357273a2dbSMatthew Booth 24367273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 24377273a2dbSMatthew Booth 24387273a2dbSMatthew Booth@item -chardev serial ,id=@var{id} ,path=@option{path} 24397273a2dbSMatthew Booth 24407273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 24417273a2dbSMatthew Booth 2442d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 2443d59044efSGerd Hoffmannnot only serial lines. 24447273a2dbSMatthew Booth 24457273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 24467273a2dbSMatthew Booth 24477273a2dbSMatthew Booth@item -chardev pty ,id=@var{id} 24487273a2dbSMatthew Booth 24497273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 24507273a2dbSMatthew Boothnot take any options. 24517273a2dbSMatthew Booth 24527273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 24537273a2dbSMatthew Booth 2454b7fdb3abSAurelien Jarno@item -chardev stdio ,id=@var{id} [,signal=on|off] 2455b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 2456b7fdb3abSAurelien Jarno 2457b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 2458b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2459b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 2460b7fdb3abSAurelien Jarno 24617273a2dbSMatthew Booth@item -chardev braille ,id=@var{id} 24627273a2dbSMatthew Booth 24637273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 24647273a2dbSMatthew Booth 24657273a2dbSMatthew Booth@item -chardev tty ,id=@var{id} ,path=@var{path} 24667273a2dbSMatthew Booth 24677273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2468d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 24697273a2dbSMatthew Booth 24707273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 24717273a2dbSMatthew Booth 247288a946d3SGerd Hoffmann@item -chardev parallel ,id=@var{id} ,path=@var{path} 2473f9cfd655SMarkus Armbruster@itemx -chardev parport ,id=@var{id} ,path=@var{path} 24747273a2dbSMatthew Booth 247588a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 24767273a2dbSMatthew Booth 24777273a2dbSMatthew BoothConnect to a local parallel port. 24787273a2dbSMatthew Booth 24797273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 24807273a2dbSMatthew Boothrequired. 24817273a2dbSMatthew Booth 2482cbcc6336SAlon Levy@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2483cbcc6336SAlon Levy 24843a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 24853a846906SStefan Hajnoczi 2486cbcc6336SAlon Levy@option{debug} debug level for spicevmc 2487cbcc6336SAlon Levy 2488cbcc6336SAlon Levy@option{name} name of spice channel to connect to 2489cbcc6336SAlon Levy 2490cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 2491cbcc6336SAlon Levy 24925a49d3e9SMarc-André Lureau@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 24935a49d3e9SMarc-André Lureau 24945a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 24955a49d3e9SMarc-André Lureau 24965a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 24975a49d3e9SMarc-André Lureau 24985a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 24995a49d3e9SMarc-André Lureau 25005a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 25015a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 25027273a2dbSMatthew BoothETEXI 25037273a2dbSMatthew Booth 2504c70a01e4SMarkus ArmbrusterSTEXI 2505c70a01e4SMarkus Armbruster@end table 2506c70a01e4SMarkus ArmbrusterETEXI 25077273a2dbSMatthew BoothDEFHEADING() 25087273a2dbSMatthew Booth 250943f187a5SPaolo BonziniDEFHEADING(Device URL Syntax) 2510c70a01e4SMarkus ArmbrusterSTEXI 25110f5314a2SRonnie Sahlberg 25120f5314a2SRonnie SahlbergIn addition to using normal file images for the emulated storage devices, 25130f5314a2SRonnie SahlbergQEMU can also use networked resources such as iSCSI devices. These are 25140f5314a2SRonnie Sahlbergspecified using a special URL syntax. 25150f5314a2SRonnie Sahlberg 25160f5314a2SRonnie Sahlberg@table @option 25170f5314a2SRonnie Sahlberg@item iSCSI 25180f5314a2SRonnie SahlbergiSCSI support allows QEMU to access iSCSI resources directly and use as 25190f5314a2SRonnie Sahlbergimages for the guest storage. Both disk and cdrom images are supported. 25200f5314a2SRonnie Sahlberg 25210f5314a2SRonnie SahlbergSyntax for specifying iSCSI LUNs is 25220f5314a2SRonnie Sahlberg``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 25230f5314a2SRonnie Sahlberg 252431459f46SRonnie SahlbergBy default qemu will use the iSCSI initiator-name 252531459f46SRonnie Sahlberg'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 252631459f46SRonnie Sahlbergline or a configuration file. 252731459f46SRonnie Sahlberg 25285dd7a535SPeter LievenSince version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect 25295dd7a535SPeter Lievenstalled requests and force a reestablishment of the session. The timeout 25309049736eSPeter Lievenis specified in seconds. The default is 0 which means no timeout. Libiscsi 25319049736eSPeter Lieven1.15.0 or greater is required for this feature. 253231459f46SRonnie Sahlberg 25330f5314a2SRonnie SahlbergExample (without authentication): 25340f5314a2SRonnie Sahlberg@example 25353804da9dSStefan Weilqemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2536f9dadc98SRonnie Sahlberg -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2537f9dadc98SRonnie Sahlberg -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 25380f5314a2SRonnie Sahlberg@end example 25390f5314a2SRonnie Sahlberg 25400f5314a2SRonnie SahlbergExample (CHAP username/password via URL): 25410f5314a2SRonnie Sahlberg@example 25423804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 25430f5314a2SRonnie Sahlberg@end example 25440f5314a2SRonnie Sahlberg 25450f5314a2SRonnie SahlbergExample (CHAP username/password via environment variables): 25460f5314a2SRonnie Sahlberg@example 25470f5314a2SRonnie SahlbergLIBISCSI_CHAP_USERNAME="user" \ 25480f5314a2SRonnie SahlbergLIBISCSI_CHAP_PASSWORD="password" \ 25493804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 25500f5314a2SRonnie Sahlberg@end example 25510f5314a2SRonnie Sahlberg 25520f5314a2SRonnie SahlbergiSCSI support is an optional feature of QEMU and only available when 25530f5314a2SRonnie Sahlbergcompiled and linked against libiscsi. 2554f9dadc98SRonnie SahlbergETEXI 2555f9dadc98SRonnie SahlbergDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2556f9dadc98SRonnie Sahlberg "-iscsi [user=user][,password=password]\n" 2557f9dadc98SRonnie Sahlberg " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 25582fe3798cSPaolo Bonzini " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 25595dd7a535SPeter Lieven " [,timeout=timeout]\n" 2560f9dadc98SRonnie Sahlberg " iSCSI session parameters\n", QEMU_ARCH_ALL) 2561f9dadc98SRonnie SahlbergSTEXI 25620f5314a2SRonnie Sahlberg 256331459f46SRonnie SahlbergiSCSI parameters such as username and password can also be specified via 256431459f46SRonnie Sahlberga configuration file. See qemu-doc for more information and examples. 256531459f46SRonnie Sahlberg 256608ae330eSRonnie Sahlberg@item NBD 256708ae330eSRonnie SahlbergQEMU supports NBD (Network Block Devices) both using TCP protocol as well 256808ae330eSRonnie Sahlbergas Unix Domain Sockets. 256908ae330eSRonnie Sahlberg 257008ae330eSRonnie SahlbergSyntax for specifying a NBD device using TCP 257108ae330eSRonnie Sahlberg``nbd:<server-ip>:<port>[:exportname=<export>]'' 257208ae330eSRonnie Sahlberg 257308ae330eSRonnie SahlbergSyntax for specifying a NBD device using Unix Domain Sockets 257408ae330eSRonnie Sahlberg``nbd:unix:<domain-socket>[:exportname=<export>]'' 257508ae330eSRonnie Sahlberg 257608ae330eSRonnie Sahlberg 257708ae330eSRonnie SahlbergExample for TCP 257808ae330eSRonnie Sahlberg@example 25793804da9dSStefan Weilqemu-system-i386 --drive file=nbd:192.0.2.1:30000 258008ae330eSRonnie Sahlberg@end example 258108ae330eSRonnie Sahlberg 258208ae330eSRonnie SahlbergExample for Unix Domain Sockets 258308ae330eSRonnie Sahlberg@example 25843804da9dSStefan Weilqemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 258508ae330eSRonnie Sahlberg@end example 258608ae330eSRonnie Sahlberg 25870a12ec87SRichard W.M. Jones@item SSH 25880a12ec87SRichard W.M. JonesQEMU supports SSH (Secure Shell) access to remote disks. 25890a12ec87SRichard W.M. Jones 25900a12ec87SRichard W.M. JonesExamples: 25910a12ec87SRichard W.M. Jones@example 25920a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 25930a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 25940a12ec87SRichard W.M. Jones@end example 25950a12ec87SRichard W.M. Jones 25960a12ec87SRichard W.M. JonesCurrently authentication must be done using ssh-agent. Other 25970a12ec87SRichard W.M. Jonesauthentication methods may be supported in future. 25980a12ec87SRichard W.M. Jones 2599d9990228SRonnie Sahlberg@item Sheepdog 2600d9990228SRonnie SahlbergSheepdog is a distributed storage system for QEMU. 2601d9990228SRonnie SahlbergQEMU supports using either local sheepdog devices or remote networked 2602d9990228SRonnie Sahlbergdevices. 2603d9990228SRonnie Sahlberg 2604d9990228SRonnie SahlbergSyntax for specifying a sheepdog device 26055d6768e3SMORITA Kazutaka@example 26061b8bbb46SMORITA Kazutakasheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 26075d6768e3SMORITA Kazutaka@end example 2608d9990228SRonnie Sahlberg 2609d9990228SRonnie SahlbergExample 2610d9990228SRonnie Sahlberg@example 26115d6768e3SMORITA Kazutakaqemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2612d9990228SRonnie Sahlberg@end example 2613d9990228SRonnie Sahlberg 26146135c5e1SThomas HuthSee also @url{https://sheepdog.github.io/sheepdog/}. 2615d9990228SRonnie Sahlberg 26168809e289SBharata B Rao@item GlusterFS 2617736a83faSStefan WeilGlusterFS is a user space distributed file system. 26188809e289SBharata B RaoQEMU supports the use of GlusterFS volumes for hosting VM disk images using 26198809e289SBharata B RaoTCP, Unix Domain Sockets and RDMA transport protocols. 26208809e289SBharata B Rao 26218809e289SBharata B RaoSyntax for specifying a VM disk image on GlusterFS volume is 26228809e289SBharata B Rao@example 262376b5550fSPrasanna Kumar Kalever 262476b5550fSPrasanna Kumar KaleverURI: 262576b5550fSPrasanna Kumar Kalevergluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...] 262676b5550fSPrasanna Kumar Kalever 262776b5550fSPrasanna Kumar KaleverJSON: 262876b5550fSPrasanna Kumar Kalever'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...", 262976b5550fSPrasanna Kumar Kalever@ "server":[@{"type":"tcp","host":"...","port":"..."@}, 263076b5550fSPrasanna Kumar Kalever@ @{"type":"unix","socket":"..."@}]@}@}' 26318809e289SBharata B Rao@end example 26328809e289SBharata B Rao 26338809e289SBharata B Rao 26348809e289SBharata B RaoExample 26358809e289SBharata B Rao@example 263676b5550fSPrasanna Kumar KaleverURI: 263776b5550fSPrasanna Kumar Kaleverqemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img, 263876b5550fSPrasanna Kumar Kalever@ file.debug=9,file.logfile=/var/log/qemu-gluster.log 263976b5550fSPrasanna Kumar Kalever 264076b5550fSPrasanna Kumar KaleverJSON: 264176b5550fSPrasanna Kumar Kaleverqemu-system-x86_64 'json:@{"driver":"qcow2", 264276b5550fSPrasanna Kumar Kalever@ "file":@{"driver":"gluster", 264376b5550fSPrasanna Kumar Kalever@ "volume":"testvol","path":"a.img", 264476b5550fSPrasanna Kumar Kalever@ "debug":9,"logfile":"/var/log/qemu-gluster.log", 264576b5550fSPrasanna Kumar Kalever@ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@}, 264676b5550fSPrasanna Kumar Kalever@ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}' 264776b5550fSPrasanna Kumar Kaleverqemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, 264876b5550fSPrasanna Kumar Kalever@ file.debug=9,file.logfile=/var/log/qemu-gluster.log, 264976b5550fSPrasanna Kumar Kalever@ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, 265076b5550fSPrasanna Kumar Kalever@ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket 26518809e289SBharata B Rao@end example 26528809e289SBharata B Rao 26538809e289SBharata B RaoSee also @url{http://www.gluster.org}. 26540a86cb73SMatthew Booth 265523dce387SMax Reitz@item HTTP/HTTPS/FTP/FTPS 265623dce387SMax ReitzQEMU supports read-only access to files accessed over http(s) and ftp(s). 26570a86cb73SMatthew Booth 26580a86cb73SMatthew BoothSyntax using a single filename: 26590a86cb73SMatthew Booth@example 26600a86cb73SMatthew Booth<protocol>://[<username>[:<password>]@@]<host>/<path> 26610a86cb73SMatthew Booth@end example 26620a86cb73SMatthew Booth 26630a86cb73SMatthew Boothwhere: 26640a86cb73SMatthew Booth@table @option 26650a86cb73SMatthew Booth@item protocol 266623dce387SMax Reitz'http', 'https', 'ftp', or 'ftps'. 26670a86cb73SMatthew Booth 26680a86cb73SMatthew Booth@item username 26690a86cb73SMatthew BoothOptional username for authentication to the remote server. 26700a86cb73SMatthew Booth 26710a86cb73SMatthew Booth@item password 26720a86cb73SMatthew BoothOptional password for authentication to the remote server. 26730a86cb73SMatthew Booth 26740a86cb73SMatthew Booth@item host 26750a86cb73SMatthew BoothAddress of the remote server. 26760a86cb73SMatthew Booth 26770a86cb73SMatthew Booth@item path 26780a86cb73SMatthew BoothPath on the remote server, including any query string. 26790a86cb73SMatthew Booth@end table 26800a86cb73SMatthew Booth 26810a86cb73SMatthew BoothThe following options are also supported: 26820a86cb73SMatthew Booth@table @option 26830a86cb73SMatthew Booth@item url 26840a86cb73SMatthew BoothThe full URL when passing options to the driver explicitly. 26850a86cb73SMatthew Booth 26860a86cb73SMatthew Booth@item readahead 26870a86cb73SMatthew BoothThe amount of data to read ahead with each range request to the remote server. 26880a86cb73SMatthew BoothThis value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it 26890a86cb73SMatthew Boothdoes not have a suffix, it will be assumed to be in bytes. The value must be a 26900a86cb73SMatthew Boothmultiple of 512 bytes. It defaults to 256k. 26910a86cb73SMatthew Booth 26920a86cb73SMatthew Booth@item sslverify 26930a86cb73SMatthew BoothWhether to verify the remote server's certificate when connecting over SSL. It 26940a86cb73SMatthew Boothcan have the value 'on' or 'off'. It defaults to 'on'. 2695212aefaaSDaniel Henrique Barboza 2696a94f83d9SRichard W.M. Jones@item cookie 2697a94f83d9SRichard W.M. JonesSend this cookie (it can also be a list of cookies separated by ';') with 2698a94f83d9SRichard W.M. Joneseach outgoing request. Only supported when using protocols such as HTTP 2699a94f83d9SRichard W.M. Joneswhich support cookies, otherwise ignored. 2700a94f83d9SRichard W.M. Jones 2701212aefaaSDaniel Henrique Barboza@item timeout 2702212aefaaSDaniel Henrique BarbozaSet the timeout in seconds of the CURL connection. This timeout is the time 2703212aefaaSDaniel Henrique Barbozathat CURL waits for a response from the remote server to get the size of the 2704212aefaaSDaniel Henrique Barbozaimage to be downloaded. If not set, the default timeout of 5 seconds is used. 27050a86cb73SMatthew Booth@end table 27060a86cb73SMatthew Booth 27070a86cb73SMatthew BoothNote that when passing options to qemu explicitly, @option{driver} is the value 27080a86cb73SMatthew Boothof <protocol>. 27090a86cb73SMatthew Booth 27100a86cb73SMatthew BoothExample: boot from a remote Fedora 20 live ISO image 27110a86cb73SMatthew Booth@example 27120a86cb73SMatthew Boothqemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly 27130a86cb73SMatthew Booth 27140a86cb73SMatthew Boothqemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly 27150a86cb73SMatthew Booth@end example 27160a86cb73SMatthew Booth 27170a86cb73SMatthew BoothExample: boot from a remote Fedora 20 cloud image using a local overlay for 27180a86cb73SMatthew Boothwrites, copy-on-read, and a readahead of 64k 27190a86cb73SMatthew Booth@example 27200a86cb73SMatthew Boothqemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 27210a86cb73SMatthew Booth 27220a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on 27230a86cb73SMatthew Booth@end example 27240a86cb73SMatthew Booth 27250a86cb73SMatthew BoothExample: boot from an image stored on a VMware vSphere server with a self-signed 2726212aefaaSDaniel Henrique Barbozacertificate using a local overlay for writes, a readahead of 64k and a timeout 2727212aefaaSDaniel Henrique Barbozaof 10 seconds. 27280a86cb73SMatthew Booth@example 2729212aefaaSDaniel Henrique Barbozaqemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2 27300a86cb73SMatthew Booth 27310a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/test.qcow2 27320a86cb73SMatthew Booth@end example 2733c70a01e4SMarkus ArmbrusterETEXI 2734c70a01e4SMarkus Armbruster 2735c70a01e4SMarkus ArmbrusterSTEXI 27360f5314a2SRonnie Sahlberg@end table 27370f5314a2SRonnie SahlbergETEXI 27380f5314a2SRonnie Sahlberg 273943f187a5SPaolo BonziniDEFHEADING(Bluetooth(R) options) 2740c70a01e4SMarkus ArmbrusterSTEXI 2741c70a01e4SMarkus Armbruster@table @option 2742c70a01e4SMarkus ArmbrusterETEXI 27437273a2dbSMatthew Booth 27445824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 27455824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 27465824d651Sblueswir1 "-bt hci,host[:id]\n" \ 27475824d651Sblueswir1 " use host's HCI with the given name\n" \ 27485824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 27495824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 27505824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 27515824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 27525824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 2753ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2754ad96090aSBlue Swirl QEMU_ARCH_ALL) 27555824d651Sblueswir1STEXI 27565824d651Sblueswir1@item -bt hci[...] 27576616b2adSStefan Weil@findex -bt 27585824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 27595824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 27605824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 27615824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 27625824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 27635824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 27645824d651Sblueswir1machines have none. 27655824d651Sblueswir1 27665824d651Sblueswir1@anchor{bt-hcis} 27675824d651Sblueswir1The following three types are recognized: 27685824d651Sblueswir1 2769b3f046c2SKevin Wolf@table @option 27705824d651Sblueswir1@item -bt hci,null 27715824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 27725824d651Sblueswir1and will not respond to any HCI commands or emit events. 27735824d651Sblueswir1 27745824d651Sblueswir1@item -bt hci,host[:@var{id}] 27755824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 27765824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 27775824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 27785824d651Sblueswir1capable systems like Linux. 27795824d651Sblueswir1 27805824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 27815824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 27825824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 27835824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 27845824d651Sblueswir1with other devices in the same network (scatternet). 27855824d651Sblueswir1@end table 27865824d651Sblueswir1 27875824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 27885824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 27895824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 27905824d651Sblueswir1allows the host and target machines to participate in a common scatternet 27915824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 27925824d651Sblueswir1be used as following: 27935824d651Sblueswir1 27945824d651Sblueswir1@example 27953804da9dSStefan Weilqemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 27965824d651Sblueswir1@end example 27975824d651Sblueswir1 27985824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 27995824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 28005824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 28015824d651Sblueswir1currently: 28025824d651Sblueswir1 2803b3f046c2SKevin Wolf@table @option 28045824d651Sblueswir1@item keyboard 28055824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 28065824d651Sblueswir1@end table 28075824d651Sblueswir1ETEXI 28085824d651Sblueswir1 2809c70a01e4SMarkus ArmbrusterSTEXI 2810c70a01e4SMarkus Armbruster@end table 2811c70a01e4SMarkus ArmbrusterETEXI 28125824d651Sblueswir1DEFHEADING() 28135824d651Sblueswir1 2814d1a0cf73SStefan Berger#ifdef CONFIG_TPM 281543f187a5SPaolo BonziniDEFHEADING(TPM device options) 2816d1a0cf73SStefan Berger 2817d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 281892dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 281992dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 282092dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 282192dcc234SStefan Berger " not provided it will be searched for in /sys/class/misc/tpm?/device\n", 2822d1a0cf73SStefan Berger QEMU_ARCH_ALL) 2823d1a0cf73SStefan BergerSTEXI 2824d1a0cf73SStefan Berger 2825d1a0cf73SStefan BergerThe general form of a TPM device option is: 2826d1a0cf73SStefan Berger@table @option 2827d1a0cf73SStefan Berger 2828d1a0cf73SStefan Berger@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 2829d1a0cf73SStefan Berger@findex -tpmdev 2830d1a0cf73SStefan BergerBackend type must be: 28314549a8b7SStefan Berger@option{passthrough}. 2832d1a0cf73SStefan Berger 2833d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 283428c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 283528c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 2836d1a0cf73SStefan Berger 2837d1a0cf73SStefan BergerOptions to each backend are described below. 2838d1a0cf73SStefan Berger 2839d1a0cf73SStefan BergerUse 'help' to print all available TPM backend types. 2840d1a0cf73SStefan Berger@example 2841d1a0cf73SStefan Bergerqemu -tpmdev help 2842d1a0cf73SStefan Berger@end example 2843d1a0cf73SStefan Berger 284492dcc234SStefan Berger@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} 28454549a8b7SStefan Berger 28464549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 28474549a8b7SStefan Bergerdriver. 28484549a8b7SStefan Berger 28494549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 28504549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 28514549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 28524549a8b7SStefan Berger 285392dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 285492dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 285592dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 285692dcc234SStefan Bergersysfs entry to use. 285792dcc234SStefan Berger 28584549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 28594549a8b7SStefan Berger 28604549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 28614549a8b7SStefan Bergerused by any other application on the host. 28624549a8b7SStefan Berger 28634549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 28644549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 28654549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 28664549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 28674549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 28684549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 28694549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 28704549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 28714549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 28724549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 28734549a8b7SStefan Berger 28744549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 28754549a8b7SStefan Berger@example 28764549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 28774549a8b7SStefan Berger@end example 28784549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 28794549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 28804549a8b7SStefan Berger 2881d1a0cf73SStefan Berger@end table 2882d1a0cf73SStefan Berger 2883d1a0cf73SStefan BergerETEXI 2884d1a0cf73SStefan Berger 2885d1a0cf73SStefan BergerDEFHEADING() 2886d1a0cf73SStefan Berger 2887d1a0cf73SStefan Berger#endif 2888d1a0cf73SStefan Berger 288943f187a5SPaolo BonziniDEFHEADING(Linux/Multiboot boot specific) 28905824d651Sblueswir1STEXI 28917677f05dSAlexander Graf 28927677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 28937677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 28945824d651Sblueswir1for easier testing of various kernels. 28955824d651Sblueswir1 28965824d651Sblueswir1@table @option 28975824d651Sblueswir1ETEXI 28985824d651Sblueswir1 28995824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2900ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 29015824d651Sblueswir1STEXI 29025824d651Sblueswir1@item -kernel @var{bzImage} 29036616b2adSStefan Weil@findex -kernel 29047677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 29057677f05dSAlexander Grafor in multiboot format. 29065824d651Sblueswir1ETEXI 29075824d651Sblueswir1 29085824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2909ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 29105824d651Sblueswir1STEXI 29115824d651Sblueswir1@item -append @var{cmdline} 29126616b2adSStefan Weil@findex -append 29135824d651Sblueswir1Use @var{cmdline} as kernel command line 29145824d651Sblueswir1ETEXI 29155824d651Sblueswir1 29165824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2917ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 29185824d651Sblueswir1STEXI 29195824d651Sblueswir1@item -initrd @var{file} 29206616b2adSStefan Weil@findex -initrd 29215824d651Sblueswir1Use @var{file} as initial ram disk. 29227677f05dSAlexander Graf 29237677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 29247677f05dSAlexander Graf 29257677f05dSAlexander GrafThis syntax is only available with multiboot. 29267677f05dSAlexander Graf 29277677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 29287677f05dSAlexander Graffirst module. 29295824d651Sblueswir1ETEXI 29305824d651Sblueswir1 2931412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2932379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2933412beee6SGrant LikelySTEXI 2934412beee6SGrant Likely@item -dtb @var{file} 2935412beee6SGrant Likely@findex -dtb 2936412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 2937412beee6SGrant Likelyon boot. 2938412beee6SGrant LikelyETEXI 2939412beee6SGrant Likely 29405824d651Sblueswir1STEXI 29415824d651Sblueswir1@end table 29425824d651Sblueswir1ETEXI 29435824d651Sblueswir1DEFHEADING() 29445824d651Sblueswir1 294543f187a5SPaolo BonziniDEFHEADING(Debug/Expert options) 29465824d651Sblueswir1STEXI 29475824d651Sblueswir1@table @option 29485824d651Sblueswir1ETEXI 29495824d651Sblueswir1 295081b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 295181b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 295263d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 29536407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 295463d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 295581b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 295681b2b810SGabriel L. SomloSTEXI 295763d3145aSMarkus Armbruster 295881b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 295981b2b810SGabriel L. Somlo@findex -fw_cfg 296063d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 29616407d76eSGabriel L. Somlo 29626407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 296363d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 296463d3145aSMarkus Armbruster 296563d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 296663d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 296763d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 296863d3145aSMarkus Armbruster 296963d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 297063d3145aSMarkus Armbruster 297163d3145aSMarkus ArmbrusterExample: 297263d3145aSMarkus Armbruster@example 297363d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 297463d3145aSMarkus Armbruster@end example 297563d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 297663d3145aSMarkus Armbrusterfrom ./my_blob.bin. 297763d3145aSMarkus Armbruster 297881b2b810SGabriel L. SomloETEXI 297981b2b810SGabriel L. Somlo 29805824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 2981ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 2982ad96090aSBlue Swirl QEMU_ARCH_ALL) 29835824d651Sblueswir1STEXI 29845824d651Sblueswir1@item -serial @var{dev} 29856616b2adSStefan Weil@findex -serial 29865824d651Sblueswir1Redirect the virtual serial port to host character device 29875824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 29885824d651Sblueswir1@code{stdio} in non graphical mode. 29895824d651Sblueswir1 29905824d651Sblueswir1This option can be used several times to simulate up to 4 serial 29915824d651Sblueswir1ports. 29925824d651Sblueswir1 29935824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 29945824d651Sblueswir1 29955824d651Sblueswir1Available character devices are: 2996b3f046c2SKevin Wolf@table @option 29974e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 29985824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 29995824d651Sblueswir1@example 30005824d651Sblueswir1vc:800x600 30015824d651Sblueswir1@end example 30025824d651Sblueswir1It is also possible to specify width or height in characters: 30035824d651Sblueswir1@example 30045824d651Sblueswir1vc:80Cx24C 30055824d651Sblueswir1@end example 30065824d651Sblueswir1@item pty 30075824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 30085824d651Sblueswir1@item none 30095824d651Sblueswir1No device is allocated. 30105824d651Sblueswir1@item null 30115824d651Sblueswir1void device 301288e020e5SIngo van Lil@item chardev:@var{id} 301388e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 30145824d651Sblueswir1@item /dev/XXX 30155824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 30165824d651Sblueswir1parameters are set according to the emulated ones. 30175824d651Sblueswir1@item /dev/parport@var{N} 30185824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 30195824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 30205824d651Sblueswir1@item file:@var{filename} 30215824d651Sblueswir1Write output to @var{filename}. No character can be read. 30225824d651Sblueswir1@item stdio 30235824d651Sblueswir1[Unix only] standard input/output 30245824d651Sblueswir1@item pipe:@var{filename} 30255824d651Sblueswir1name pipe @var{filename} 30265824d651Sblueswir1@item COM@var{n} 30275824d651Sblueswir1[Windows only] Use host serial port @var{n} 30285824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 30295824d651Sblueswir1This implements UDP Net Console. 30305824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 30315824d651Sblueswir1they default to @code{0.0.0.0}. 30325824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 30335824d651Sblueswir1 30345824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3035b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3036b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 30375824d651Sblueswir1will appear in the netconsole session. 30385824d651Sblueswir1 30395824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3040b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 30415824d651Sblueswir1source port each time by using something like @code{-serial 3042b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 30435824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 30445824d651Sblueswir1characters via udp. If you have a patched version of netcat which 30455824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3046bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3047b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 30485824d651Sblueswir1@table @code 3049071c9394SStefan Weil@item QEMU Options: 30505824d651Sblueswir1-serial udp::4555@@:4556 30515824d651Sblueswir1@item netcat options: 30525824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 30535824d651Sblueswir1@item telnet options: 30545824d651Sblueswir1localhost 5555 30555824d651Sblueswir1@end table 30565824d651Sblueswir1 30575dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 30585824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 30595824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 30605824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 30615824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 30625824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 30635824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 30645dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 30655dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 30665dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 30675824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 30685824d651Sblueswir1connect to the corresponding character device. 30695824d651Sblueswir1@table @code 30705824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 30715824d651Sblueswir1-serial tcp:192.168.0.2:4444 30725824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 30735824d651Sblueswir1-serial tcp::4444,server 30745824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 30755824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 30765824d651Sblueswir1@end table 30775824d651Sblueswir1 30785824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 30795824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 30805824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 30815824d651Sblueswir1difference is that the port acts like a telnet server or client using 30825824d651Sblueswir1telnet option negotiation. This will also allow you to send the 30835824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 30845824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 30855824d651Sblueswir1type "send break" followed by pressing the enter key. 30865824d651Sblueswir1 30875dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 30885824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 30895824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 30905824d651Sblueswir1@var{path} is used for connections. 30915824d651Sblueswir1 30925824d651Sblueswir1@item mon:@var{dev_string} 30935824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 30945824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 309502c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 30965824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 30975824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 30985824d651Sblueswir1listening on port 4444 would be: 30995824d651Sblueswir1@table @code 31005824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 31015824d651Sblueswir1@end table 3102be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 310302c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 31045824d651Sblueswir1 31055824d651Sblueswir1@item braille 31065824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 31075824d651Sblueswir1or fake device. 31085824d651Sblueswir1 3109be8b28a9SKevin Wolf@item msmouse 3110be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 31115824d651Sblueswir1@end table 31125824d651Sblueswir1ETEXI 31135824d651Sblueswir1 31145824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3115ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3116ad96090aSBlue Swirl QEMU_ARCH_ALL) 31175824d651Sblueswir1STEXI 31185824d651Sblueswir1@item -parallel @var{dev} 31196616b2adSStefan Weil@findex -parallel 31205824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 31215824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 31225824d651Sblueswir1be used to use hardware devices connected on the corresponding host 31235824d651Sblueswir1parallel port. 31245824d651Sblueswir1 31255824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 31265824d651Sblueswir1ports. 31275824d651Sblueswir1 31285824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 31295824d651Sblueswir1ETEXI 31305824d651Sblueswir1 31315824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3132ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3133ad96090aSBlue Swirl QEMU_ARCH_ALL) 31345824d651Sblueswir1STEXI 31354e307fc8SGerd Hoffmann@item -monitor @var{dev} 31366616b2adSStefan Weil@findex -monitor 31375824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 31385824d651Sblueswir1serial port). 31395824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 31405824d651Sblueswir1non graphical mode. 314170e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 31425824d651Sblueswir1ETEXI 31436ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3144ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3145ad96090aSBlue Swirl QEMU_ARCH_ALL) 314695d5f08bSStefan WeilSTEXI 314795d5f08bSStefan Weil@item -qmp @var{dev} 31486616b2adSStefan Weil@findex -qmp 314995d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 315095d5f08bSStefan WeilETEXI 31514821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 31524821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 31534821cd4cSMax Reitz QEMU_ARCH_ALL) 31544821cd4cSMax ReitzSTEXI 31554821cd4cSMax Reitz@item -qmp-pretty @var{dev} 31564821cd4cSMax Reitz@findex -qmp-pretty 31574821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 31584821cd4cSMax ReitzETEXI 31595824d651Sblueswir1 316022a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3161bdbcb547SMarc-André Lureau "-mon [chardev=]name[,mode=readline|control]\n", QEMU_ARCH_ALL) 316222a0e04bSGerd HoffmannSTEXI 3163bdbcb547SMarc-André Lureau@item -mon [chardev=]name[,mode=readline|control] 31646616b2adSStefan Weil@findex -mon 316522a0e04bSGerd HoffmannSetup monitor on chardev @var{name}. 316622a0e04bSGerd HoffmannETEXI 316722a0e04bSGerd Hoffmann 3168c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3169ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3170ad96090aSBlue Swirl QEMU_ARCH_ALL) 3171c9f398e5SH. Peter AnvinSTEXI 3172c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 31736616b2adSStefan Weil@findex -debugcon 3174c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3175c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3176c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3177c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3178c9f398e5SH. Peter Anvinnon graphical mode. 3179c9f398e5SH. Peter AnvinETEXI 3180c9f398e5SH. Peter Anvin 31815824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3182ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 31835824d651Sblueswir1STEXI 31845824d651Sblueswir1@item -pidfile @var{file} 31856616b2adSStefan Weil@findex -pidfile 31865824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 31875824d651Sblueswir1from a script. 31885824d651Sblueswir1ETEXI 31895824d651Sblueswir1 31901b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3191ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 31921b530a6dSaurel32STEXI 31931b530a6dSaurel32@item -singlestep 31946616b2adSStefan Weil@findex -singlestep 31951b530a6dSaurel32Run the emulation in single step mode. 31961b530a6dSaurel32ETEXI 31971b530a6dSaurel32 31985824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3199ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3200ad96090aSBlue Swirl QEMU_ARCH_ALL) 32015824d651Sblueswir1STEXI 32025824d651Sblueswir1@item -S 32036616b2adSStefan Weil@findex -S 32045824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 32055824d651Sblueswir1ETEXI 32065824d651Sblueswir1 3207888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3208888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3209888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3210888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3211888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3212888a6bc6SSatoru MoriyaSTEXI 3213888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3214888a6bc6SSatoru Moriya@findex -realtime 3215888a6bc6SSatoru MoriyaRun qemu with realtime features. 3216888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3217888a6bc6SSatoru Moriya(enabled by default). 3218888a6bc6SSatoru MoriyaETEXI 3219888a6bc6SSatoru Moriya 322059030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3221ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 32225824d651Sblueswir1STEXI 322359030a8cSaliguori@item -gdb @var{dev} 32246616b2adSStefan Weil@findex -gdb 322559030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 322659030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3227b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 322859030a8cSaliguoriwithin gdb and establish the connection via a pipe: 322959030a8cSaliguori@example 32303804da9dSStefan Weil(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 323159030a8cSaliguori@end example 32325824d651Sblueswir1ETEXI 32335824d651Sblueswir1 323459030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3235ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3236ad96090aSBlue Swirl QEMU_ARCH_ALL) 32375824d651Sblueswir1STEXI 323859030a8cSaliguori@item -s 32396616b2adSStefan Weil@findex -s 324059030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 324159030a8cSaliguori(@pxref{gdb_usage}). 32425824d651Sblueswir1ETEXI 32435824d651Sblueswir1 32445824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3245989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3246ad96090aSBlue Swirl QEMU_ARCH_ALL) 32475824d651Sblueswir1STEXI 3248989b697dSPeter Maydell@item -d @var{item1}[,...] 32496616b2adSStefan Weil@findex -d 3250989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 32515824d651Sblueswir1ETEXI 32525824d651Sblueswir1 3253c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3254989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3255c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3256c235d738SMatthew FernandezSTEXI 32578bd383b4SStefan Weil@item -D @var{logfile} 3258c235d738SMatthew Fernandez@findex -D 3259989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3260c235d738SMatthew FernandezETEXI 3261c235d738SMatthew Fernandez 32623514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 32633514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 32643514552eSAlex Bennée QEMU_ARCH_ALL) 32653514552eSAlex BennéeSTEXI 32663514552eSAlex Bennée@item -dfilter @var{range1}[,...] 32673514552eSAlex Bennée@findex -dfilter 32683514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 32693514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 32703514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 32713514552eSAlex Bennéeaddresses and sizes required. For example: 32723514552eSAlex Bennée@example 32733514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 32743514552eSAlex Bennée@end example 32753514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 32763514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 32773514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 32783514552eSAlex BennéeETEXI 32793514552eSAlex Bennée 32805824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3281ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3282ad96090aSBlue Swirl QEMU_ARCH_ALL) 32835824d651Sblueswir1STEXI 32845824d651Sblueswir1@item -L @var{path} 32856616b2adSStefan Weil@findex -L 32865824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 328737146e7eSRichard W.M. Jones 328837146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 32895824d651Sblueswir1ETEXI 32905824d651Sblueswir1 32915824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3292ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 32935824d651Sblueswir1STEXI 32945824d651Sblueswir1@item -bios @var{file} 32956616b2adSStefan Weil@findex -bios 32965824d651Sblueswir1Set the filename for the BIOS. 32975824d651Sblueswir1ETEXI 32985824d651Sblueswir1 32995824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3300ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 33015824d651Sblueswir1STEXI 33025824d651Sblueswir1@item -enable-kvm 33036616b2adSStefan Weil@findex -enable-kvm 33045824d651Sblueswir1Enable KVM full virtualization support. This option is only available 33055824d651Sblueswir1if KVM support is enabled when compiling. 33065824d651Sblueswir1ETEXI 33075824d651Sblueswir1 3308b0cb0a66SVincent PalatinDEF("enable-hax", 0, QEMU_OPTION_enable_hax, \ 3309b0cb0a66SVincent Palatin "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386) 3310b0cb0a66SVincent PalatinSTEXI 3311b0cb0a66SVincent Palatin@item -enable-hax 3312b0cb0a66SVincent Palatin@findex -enable-hax 3313b0cb0a66SVincent PalatinEnable HAX (Hardware-based Acceleration eXecution) support. This option 3314b0cb0a66SVincent Palatinis only available if HAX support is enabled when compiling. HAX is only 3315b0cb0a66SVincent Palatinapplicable to MAC and Windows platform, and thus does not conflict with 3316b0cb0a66SVincent PalatinKVM. 3317b0cb0a66SVincent PalatinETEXI 3318b0cb0a66SVincent Palatin 3319e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3320ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3321e37630caSaliguoriDEF("xen-create", 0, QEMU_OPTION_xen_create, 3322e37630caSaliguori "-xen-create create domain using xen hypercalls, bypassing xend\n" 3323ad96090aSBlue Swirl " warning: should not be used when xend is in use\n", 3324ad96090aSBlue Swirl QEMU_ARCH_ALL) 3325e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3326e37630caSaliguori "-xen-attach attach to existing xen domain\n" 3327b65ee4faSStefan Weil " xend will use this when starting QEMU\n", 3328ad96090aSBlue Swirl QEMU_ARCH_ALL) 332995d5f08bSStefan WeilSTEXI 333095d5f08bSStefan Weil@item -xen-domid @var{id} 33316616b2adSStefan Weil@findex -xen-domid 333295d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 333395d5f08bSStefan Weil@item -xen-create 33346616b2adSStefan Weil@findex -xen-create 333595d5f08bSStefan WeilCreate domain using xen hypercalls, bypassing xend. 333695d5f08bSStefan WeilWarning: should not be used when xend is in use (XEN only). 333795d5f08bSStefan Weil@item -xen-attach 33386616b2adSStefan Weil@findex -xen-attach 333995d5f08bSStefan WeilAttach to existing xen domain. 3340b65ee4faSStefan Weilxend will use this when starting QEMU (XEN only). 334195d5f08bSStefan WeilETEXI 3342e37630caSaliguori 33435824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3344ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 33455824d651Sblueswir1STEXI 33465824d651Sblueswir1@item -no-reboot 33476616b2adSStefan Weil@findex -no-reboot 33485824d651Sblueswir1Exit instead of rebooting. 33495824d651Sblueswir1ETEXI 33505824d651Sblueswir1 33515824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3352ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 33535824d651Sblueswir1STEXI 33545824d651Sblueswir1@item -no-shutdown 33556616b2adSStefan Weil@findex -no-shutdown 33565824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 33575824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 33585824d651Sblueswir1disk image. 33595824d651Sblueswir1ETEXI 33605824d651Sblueswir1 33615824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 33625824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3363ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3364ad96090aSBlue Swirl QEMU_ARCH_ALL) 33655824d651Sblueswir1STEXI 33665824d651Sblueswir1@item -loadvm @var{file} 33676616b2adSStefan Weil@findex -loadvm 33685824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 33695824d651Sblueswir1ETEXI 33705824d651Sblueswir1 33715824d651Sblueswir1#ifndef _WIN32 33725824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3373ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 33745824d651Sblueswir1#endif 33755824d651Sblueswir1STEXI 33765824d651Sblueswir1@item -daemonize 33776616b2adSStefan Weil@findex -daemonize 33785824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 33795824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 33805824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 33815824d651Sblueswir1to cope with initialization race conditions. 33825824d651Sblueswir1ETEXI 33835824d651Sblueswir1 33845824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3385ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3386ad96090aSBlue Swirl QEMU_ARCH_ALL) 33875824d651Sblueswir1STEXI 33885824d651Sblueswir1@item -option-rom @var{file} 33896616b2adSStefan Weil@findex -option-rom 33905824d651Sblueswir1Load the contents of @var{file} as an option ROM. 33915824d651Sblueswir1This option is useful to load things like EtherBoot. 33925824d651Sblueswir1ETEXI 33935824d651Sblueswir1 3394e218052fSMarkus ArmbrusterHXCOMM Silently ignored for compatibility 3395e218052fSMarkus ArmbrusterDEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 33965824d651Sblueswir1 33971ed2fc1fSJan KiszkaHXCOMM Options deprecated by -rtc 3398ad96090aSBlue SwirlDEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 3399ad96090aSBlue SwirlDEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 34005824d651Sblueswir1 34011ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 340278808141SPaolo Bonzini "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3403ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3404ad96090aSBlue Swirl QEMU_ARCH_ALL) 34051ed2fc1fSJan Kiszka 34065824d651Sblueswir1STEXI 34075824d651Sblueswir1 34086875204cSJan Kiszka@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 34096616b2adSStefan Weil@findex -rtc 34101ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 34111ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 34121ed2fc1fSJan KiszkaMS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 34131ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 34141ed2fc1fSJan Kiszka 34159d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 34166875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 34176875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 341878808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 341978808141SPaolo Bonzinito @code{rt} instead. To even prevent it from progressing during suspension, 342078808141SPaolo Bonziniyou can set it to @code{vm}. 34216875204cSJan Kiszka 34221ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 34231ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 34241ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 34251ed2fc1fSJan Kiszkare-inject them. 34265824d651Sblueswir1ETEXI 34275824d651Sblueswir1 34285824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 34299c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3430bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3431f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3432f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 34335824d651Sblueswir1STEXI 34349c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 34356616b2adSStefan Weil@findex -icount 34365824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 34374e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 34385824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 34395824d651Sblueswir1time within a few seconds of real time. 34405824d651Sblueswir1 3441f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3442778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3443778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3444f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3445f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3446f1f4b57eSVictor CLEMENTthe guest point of view. 3447f1f4b57eSVictor CLEMENT 34485824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 34495824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 34505824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 34515824d651Sblueswir1executed often has little or no correlation with actual performance. 3452a8bfac37SSebastian Tanase 3453b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3454a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3455a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3456a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 345782597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3458a8bfac37SSebastian Tanaseto inform about the delay. 3459a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3460a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3461a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3462a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 34634c27b859SPavel Dovgalyuk 34644c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 34654c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 34664c27b859SPavel Dovgalyukread from this file in replay mode. 34679c2037d0SPavel Dovgalyuk 34689c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 34699c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 34709c2037d0SPavel Dovgalyukto load the initial VM state. 34715824d651Sblueswir1ETEXI 34725824d651Sblueswir1 34739dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3474d7933ef3SXu Wang "-watchdog model\n" \ 3475ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3476ad96090aSBlue Swirl QEMU_ARCH_ALL) 34779dd986ccSRichard W.M. JonesSTEXI 34789dd986ccSRichard W.M. Jones@item -watchdog @var{model} 34796616b2adSStefan Weil@findex -watchdog 34809dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 34819dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3482d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3483d7933ef3SXu Wangwhich your guest has drivers. 34849dd986ccSRichard W.M. Jones 3485d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3486d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 34879dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3488d7933ef3SXu Wang 3489d7933ef3SXu WangThe following models may be available: 3490d7933ef3SXu Wang@table @option 3491d7933ef3SXu Wang@item ib700 3492d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3493d7933ef3SXu Wang@item i6300esb 3494d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3495d7933ef3SXu Wangdual-timer watchdog. 3496188f24c2SXu Wang@item diag288 3497188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3498188f24c2SXu Wang(currently KVM only). 3499d7933ef3SXu Wang@end table 35009dd986ccSRichard W.M. JonesETEXI 35019dd986ccSRichard W.M. Jones 35029dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 35039dd986ccSRichard W.M. Jones "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 3504ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3505ad96090aSBlue Swirl QEMU_ARCH_ALL) 35069dd986ccSRichard W.M. JonesSTEXI 35079dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3508b8f490ebSMarkus Armbruster@findex -watchdog-action 35099dd986ccSRichard W.M. Jones 35109dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 35119dd986ccSRichard W.M. Jonesexpires. 35129dd986ccSRichard W.M. JonesThe default is 35139dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 35149dd986ccSRichard W.M. JonesOther possible actions are: 35159dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 35169dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 35179dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 35189dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 35199dd986ccSRichard W.M. Jones@code{none} (do nothing). 35209dd986ccSRichard W.M. Jones 35219dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 35229dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 35239dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 35249dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 35259dd986ccSRichard W.M. Jones 35269dd986ccSRichard W.M. JonesExamples: 35279dd986ccSRichard W.M. Jones 35289dd986ccSRichard W.M. Jones@table @code 35299dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3530f9cfd655SMarkus Armbruster@itemx -watchdog ib700 35319dd986ccSRichard W.M. Jones@end table 35329dd986ccSRichard W.M. JonesETEXI 35339dd986ccSRichard W.M. Jones 35345824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3535ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3536ad96090aSBlue Swirl QEMU_ARCH_ALL) 35375824d651Sblueswir1STEXI 35385824d651Sblueswir1 35394e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 35406616b2adSStefan Weil@findex -echr 35415824d651Sblueswir1Change the escape character used for switching to the monitor when using 35425824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 35435824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 35445824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 35455824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 35465824d651Sblueswir1instance you could use the either of the following to change the escape 35475824d651Sblueswir1character to Control-t. 35485824d651Sblueswir1@table @code 35495824d651Sblueswir1@item -echr 0x14 3550f9cfd655SMarkus Armbruster@itemx -echr 20 35515824d651Sblueswir1@end table 35525824d651Sblueswir1ETEXI 35535824d651Sblueswir1 35545824d651Sblueswir1DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 35555824d651Sblueswir1 "-virtioconsole c\n" \ 3556ad96090aSBlue Swirl " set virtio console\n", QEMU_ARCH_ALL) 35575824d651Sblueswir1STEXI 35585824d651Sblueswir1@item -virtioconsole @var{c} 35596616b2adSStefan Weil@findex -virtioconsole 35605824d651Sblueswir1Set virtio console. 356198b19252SAmit Shah 356298b19252SAmit ShahThis option is maintained for backward compatibility. 356398b19252SAmit Shah 356498b19252SAmit ShahPlease use @code{-device virtconsole} for the new way of invocation. 35655824d651Sblueswir1ETEXI 35665824d651Sblueswir1 35675824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3568ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 35695824d651Sblueswir1STEXI 357095d5f08bSStefan Weil@item -show-cursor 35716616b2adSStefan Weil@findex -show-cursor 357295d5f08bSStefan WeilShow cursor. 35735824d651Sblueswir1ETEXI 35745824d651Sblueswir1 35755824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3576ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 35775824d651Sblueswir1STEXI 357895d5f08bSStefan Weil@item -tb-size @var{n} 35796616b2adSStefan Weil@findex -tb-size 358095d5f08bSStefan WeilSet TB size. 35815824d651Sblueswir1ETEXI 35825824d651Sblueswir1 35835824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 35847c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 35857c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 35867c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 35877c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 35887c601803SMichael Tokarev " specified protocol and socket address\n" \ 35897c601803SMichael Tokarev "-incoming fd:fd\n" \ 35907c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 35917c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 35921597051bSDr. David Alan Gilbert " or from given external command\n" \ 35931597051bSDr. David Alan Gilbert "-incoming defer\n" \ 35941597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3595ad96090aSBlue Swirl QEMU_ARCH_ALL) 35965824d651Sblueswir1STEXI 35977c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3598f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 35996616b2adSStefan Weil@findex -incoming 36007c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 36017c601803SMichael Tokarev 36027c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 36037c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 36047c601803SMichael Tokarev 36057c601803SMichael Tokarev@item -incoming fd:@var{fd} 36067c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 36077c601803SMichael Tokarev 36087c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 36097c601803SMichael TokarevAccept incoming migration as an output from specified external command. 36101597051bSDr. David Alan Gilbert 36111597051bSDr. David Alan Gilbert@item -incoming defer 36121597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 36131597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 36141597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 36155824d651Sblueswir1ETEXI 36165824d651Sblueswir1 3617d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 3618d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 3619d15c05fcSAshijeet AcharyaSTEXI 3620d15c05fcSAshijeet Acharya@item -only-migratable 3621d15c05fcSAshijeet Acharya@findex -only-migratable 3622d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 3623d15c05fcSAshijeet Acharyaunmigratable state. 3624d15c05fcSAshijeet AcharyaETEXI 3625d15c05fcSAshijeet Acharya 3626d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3627ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3628d8c208ddSGerd HoffmannSTEXI 36293dbf2c7fSStefan Weil@item -nodefaults 36306616b2adSStefan Weil@findex -nodefaults 363166c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 363266c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 363366c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 363466c19bf1SMichal Novotnydefault devices. 3635d8c208ddSGerd HoffmannETEXI 3636d8c208ddSGerd Hoffmann 36375824d651Sblueswir1#ifndef _WIN32 36385824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3639ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3640ad96090aSBlue Swirl QEMU_ARCH_ALL) 36415824d651Sblueswir1#endif 36425824d651Sblueswir1STEXI 36434e257e5eSKevin Wolf@item -chroot @var{dir} 36446616b2adSStefan Weil@findex -chroot 36455824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 36465824d651Sblueswir1directory. Especially useful in combination with -runas. 36475824d651Sblueswir1ETEXI 36485824d651Sblueswir1 36495824d651Sblueswir1#ifndef _WIN32 36505824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 3651ad96090aSBlue Swirl "-runas user change to user id user just before starting the VM\n", 3652ad96090aSBlue Swirl QEMU_ARCH_ALL) 36535824d651Sblueswir1#endif 36545824d651Sblueswir1STEXI 36554e257e5eSKevin Wolf@item -runas @var{user} 36566616b2adSStefan Weil@findex -runas 36575824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 36585824d651Sblueswir1to the specified user. 36595824d651Sblueswir1ETEXI 36605824d651Sblueswir1 36615824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 36625824d651Sblueswir1 "-prom-env variable=value\n" 3663ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 3664ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 366595d5f08bSStefan WeilSTEXI 366695d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 36676616b2adSStefan Weil@findex -prom-env 366895d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 366995d5f08bSStefan WeilETEXI 36705824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 3671f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 36723b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 36733b3c1694SLeon Alrae QEMU_ARCH_MIPS) 367495d5f08bSStefan WeilSTEXI 367595d5f08bSStefan Weil@item -semihosting 36766616b2adSStefan Weil@findex -semihosting 36773b3c1694SLeon AlraeEnable semihosting mode (ARM, M68K, Xtensa, MIPS only). 3678a38bb079SLiviu IonescuETEXI 3679a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3680a59d31a1SLeon Alrae "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 3681a59d31a1SLeon Alrae " semihosting configuration\n", 36823b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 36833b3c1694SLeon AlraeQEMU_ARCH_MIPS) 3684a38bb079SLiviu IonescuSTEXI 3685a59d31a1SLeon Alrae@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 3686a38bb079SLiviu Ionescu@findex -semihosting-config 36873b3c1694SLeon AlraeEnable and configure semihosting (ARM, M68K, Xtensa, MIPS only). 3688a59d31a1SLeon Alrae@table @option 3689a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 3690a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 3691a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 3692a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 3693a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 3694a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 3695a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 3696a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 3697a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 3698a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 3699a59d31a1SLeon Alrae@end table 370095d5f08bSStefan WeilETEXI 37015824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 3702ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 370395d5f08bSStefan WeilSTEXI 370495d5f08bSStefan Weil@item -old-param 37056616b2adSStefan Weil@findex -old-param (ARM) 370695d5f08bSStefan WeilOld param mode (ARM only). 370795d5f08bSStefan WeilETEXI 370895d5f08bSStefan Weil 37097d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 37107d76ad4fSEduardo Otubo "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n", 37117d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 37127d76ad4fSEduardo OtuboSTEXI 37136265c43bSMarkus Armbruster@item -sandbox @var{arg} 37147d76ad4fSEduardo Otubo@findex -sandbox 37157d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 37167d76ad4fSEduardo Otubodisable it. The default is 'off'. 37177d76ad4fSEduardo OtuboETEXI 37187d76ad4fSEduardo Otubo 3719715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3720ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 37213dbf2c7fSStefan WeilSTEXI 37223dbf2c7fSStefan Weil@item -readconfig @var{file} 37236616b2adSStefan Weil@findex -readconfig 3724ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 3725ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 3726ed24cfacSMichal Novotnycharacter limit. 37273dbf2c7fSStefan WeilETEXI 3728715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3729715a664aSGerd Hoffmann "-writeconfig <file>\n" 3730ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 37313dbf2c7fSStefan WeilSTEXI 37323dbf2c7fSStefan Weil@item -writeconfig @var{file} 37336616b2adSStefan Weil@findex -writeconfig 3734ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 3735ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 3736ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 37373dbf2c7fSStefan WeilETEXI 3738292444cbSAnthony LiguoriDEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, 3739292444cbSAnthony Liguori "-nodefconfig\n" 3740ad96090aSBlue Swirl " do not load default config files at startup\n", 3741ad96090aSBlue Swirl QEMU_ARCH_ALL) 3742292444cbSAnthony LiguoriSTEXI 3743292444cbSAnthony Liguori@item -nodefconfig 37446616b2adSStefan Weil@findex -nodefconfig 3745f29a5614SEduardo HabkostNormally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup. 3746f29a5614SEduardo HabkostThe @code{-nodefconfig} option will prevent QEMU from loading any of those config files. 3747f29a5614SEduardo HabkostETEXI 3748f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3749f29a5614SEduardo Habkost "-no-user-config\n" 3750f29a5614SEduardo Habkost " do not load user-provided config files at startup\n", 3751f29a5614SEduardo Habkost QEMU_ARCH_ALL) 3752f29a5614SEduardo HabkostSTEXI 3753f29a5614SEduardo Habkost@item -no-user-config 3754f29a5614SEduardo Habkost@findex -no-user-config 3755f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 3756f29a5614SEduardo Habkostconfig files on @var{sysconfdir}, but won't make it skip the QEMU-provided config 3757f29a5614SEduardo Habkostfiles from @var{datadir}. 3758292444cbSAnthony LiguoriETEXI 3759ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 376010578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 376123d15e86SLluís " specify tracing options\n", 3762ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 3763ab6540d5SPrerna SaxenaSTEXI 376423d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 376523d15e86SLluísHXCOMM HX does not support conditional compilation of text. 3766e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 3767ab6540d5SPrerna Saxena@findex -trace 3768eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 3769ab6540d5SPrerna SaxenaETEXI 37703dbf2c7fSStefan Weil 377131e70d6cSMarkus ArmbrusterHXCOMM Internal use 377231e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 377331e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3774c7f0f3b1SAnthony Liguori 37750f66998fSPaul Moore#ifdef __linux__ 37760f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 37770f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 37780f66998fSPaul Moore QEMU_ARCH_ALL) 37790f66998fSPaul Moore#endif 37800f66998fSPaul MooreSTEXI 37810f66998fSPaul Moore@item -enable-fips 37820f66998fSPaul Moore@findex -enable-fips 37830f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 37840f66998fSPaul MooreETEXI 37850f66998fSPaul Moore 3786a0dac021SJan KiszkaHXCOMM Deprecated by -machine accel=tcg property 3787c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3788a0dac021SJan Kiszka 3789c21fb4f8SJan KiszkaHXCOMM Deprecated by kvm-pit driver properties 3790c6e88b3bSBruce RogersDEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 3791c21fb4f8SJan Kiszka "", QEMU_ARCH_I386) 3792c21fb4f8SJan Kiszka 37934086bde8SJan KiszkaHXCOMM Deprecated (ignored) 3794c6e88b3bSBruce RogersDEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 37954086bde8SJan Kiszka 3796e43d594eSJan KiszkaHXCOMM Deprecated by -machine kernel_irqchip=on|off property 3797c6e88b3bSBruce RogersDEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 3798e43d594eSJan Kiszka 379988eed34aSJan KiszkaHXCOMM Deprecated (ignored) 380088eed34aSJan KiszkaDEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 380188eed34aSJan Kiszka 38025e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 38035e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 38045e2ac519SSeiji Aguchi " change the format of messages\n" 38055e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 38065e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 38075e2ac519SSeiji AguchiSTEXI 38085e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 38095e2ac519SSeiji Aguchi@findex -msg 38105e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 38115e2ac519SSeiji AguchiETEXI 38125e2ac519SSeiji Aguchi 3813abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 3814abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 3815abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 3816abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 3817abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 38182382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 3819abfd9ce3SAmit Shah QEMU_ARCH_ALL) 3820abfd9ce3SAmit ShahSTEXI 3821abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 3822abfd9ce3SAmit Shah@findex -dump-vmstate 3823abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 3824abfd9ce3SAmit Shahin @var{file} 3825abfd9ce3SAmit ShahETEXI 3826abfd9ce3SAmit Shah 382743f187a5SPaolo BonziniSTEXI 382843f187a5SPaolo Bonzini@end table 382943f187a5SPaolo BonziniETEXI 383043f187a5SPaolo BonziniDEFHEADING() 3831b9174d4fSDaniel P. BerrangeDEFHEADING(Generic object creation) 383243f187a5SPaolo BonziniSTEXI 383343f187a5SPaolo Bonzini@table @option 383443f187a5SPaolo BonziniETEXI 3835b9174d4fSDaniel P. Berrange 3836b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 3837b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 3838b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 3839b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 3840b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 3841b9174d4fSDaniel P. Berrange " '/objects' path.\n", 3842b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 3843b9174d4fSDaniel P. BerrangeSTEXI 3844b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3845b9174d4fSDaniel P. Berrange@findex -object 3846b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 3847b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 3848b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 3849b9174d4fSDaniel P. Berrange'/objects' path. 3850b9174d4fSDaniel P. Berrange 3851b9174d4fSDaniel P. Berrange@table @option 3852b9174d4fSDaniel P. Berrange 3853b9174d4fSDaniel P. Berrange@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off} 3854b9174d4fSDaniel P. Berrange 3855b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 3856b9174d4fSDaniel P. Berrangethe guest RAM with huge pages. The @option{id} parameter is a 3857b9174d4fSDaniel P. Berrangeunique ID that will be used to reference this memory region 3858b9174d4fSDaniel P. Berrangewhen configuring the @option{-numa} argument. The @option{size} 3859b9174d4fSDaniel P. Berrangeoption provides the size of the memory region, and accepts 3860b9174d4fSDaniel P. Berrangecommon suffixes, eg @option{500M}. The @option{mem-path} provides 3861b9174d4fSDaniel P. Berrangethe path to either a shared memory or huge page filesystem mount. 3862b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 3863b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 3864b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 3865b9174d4fSDaniel P. Berrange 3866b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 3867b9174d4fSDaniel P. Berrange 3868b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 3869b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 3870b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 3871b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 3872b9174d4fSDaniel P. Berrangeentropy from and if omitted defaults to @option{/dev/random}. 3873b9174d4fSDaniel P. Berrange 3874b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 3875b9174d4fSDaniel P. Berrange 3876b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 3877b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 3878b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 3879b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 3880b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 3881b9174d4fSDaniel P. Berrangeto the RNG daemon. 3882b9174d4fSDaniel P. Berrange 3883e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 3884e00adf6cSDaniel P. Berrange 3885e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 3886e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 3887e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 3888e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 3889e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 3890e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 3891e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 3892e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 3893e00adf6cSDaniel P. Berrange 3894e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 3895e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 3896e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 3897e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 3898e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 3899e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 3900e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 3901e00adf6cSDaniel P. Berrangeupfront and saved. 3902e00adf6cSDaniel P. Berrange 39031d7b5b4aSDaniel P. Berrange@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off},passwordid=@var{id} 390485bcbc78SDaniel P. Berrange 390585bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 390685bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 390785bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 390885bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 390985bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 391085bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 391185bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 391285bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 391385bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 391485bcbc78SDaniel P. Berrange 391585bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 391685bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 391785bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 391885bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 391985bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 392085bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 392185bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 392285bcbc78SDaniel P. Berrangeupfront and saved. 392385bcbc78SDaniel P. Berrange 392485bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 392585bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 392685bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 392785bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 392885bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 392985bcbc78SDaniel P. Berrange 39301d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 39311d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 39321d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 39331d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 39341d7b5b4aSDaniel P. Berrangepassword for decryption. 39351d7b5b4aSDaniel P. Berrange 3936338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 39377dbb11c8SYang Hongyang 39387dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 39397dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 39407dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 3941338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 3942338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 39437dbb11c8SYang Hongyang 39447dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 39457dbb11c8SYang Hongyang 39467dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 39477dbb11c8SYang Hongyang queue of the netdev (default). 39487dbb11c8SYang Hongyang 39497dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 39507dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 39517dbb11c8SYang Hongyang 39527dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 39537dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 39547dbb11c8SYang Hongyang 3955f6d3afb5SZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}] 3956f6d3afb5SZhang Chen 3957f6d3afb5SZhang Chenfilter-mirror on netdev @var{netdevid},mirror net packet to chardev 3958f6d3afb5SZhang Chen@var{chardevid} 3959f6d3afb5SZhang Chen 3960d46f75b2SZhang Chen@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid}, 3961d46f75b2SZhang Chenoutdev=@var{chardevid}[,queue=@var{all|rx|tx}] 3962d46f75b2SZhang Chen 3963d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 3964d46f75b2SZhang Chen@var{chardevid},and redirect indev's packet to filter. 3965d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 3966d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 3967d46f75b2SZhang Chenneed to be specified. 3968d46f75b2SZhang Chen 3969e6eee8abSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},rewriter-mode=@var{mode}[,queue=@var{all|rx|tx}] 3970e6eee8abSZhang Chen 3971e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 3972e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 3973e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 3974e6eee8abSZhang Chenclient. 3975e6eee8abSZhang Chen 3976e6eee8abSZhang Chenusage: 3977e6eee8abSZhang Chencolo secondary: 3978e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 3979e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 3980e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 3981e6eee8abSZhang Chen 3982c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 3983d3e0c032SThomas Huth 3984d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 3985d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 3986d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 3987d3e0c032SThomas Huthor Wireshark. 3988d3e0c032SThomas Huth 39897dce4e6fSZhang Chen@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid}, 39907dce4e6fSZhang Chenoutdev=@var{chardevid} 39917dce4e6fSZhang Chen 39927dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 39937dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 39947dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 39957dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 39967dce4e6fSZhang Chen 39977dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 39987dce4e6fSZhang Chen 39997dce4e6fSZhang Chen@example 40007dce4e6fSZhang Chen 40017dce4e6fSZhang Chenprimary: 40027dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 40037dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 40047dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 40057dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 40067dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 40077dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 40087dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 40097dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 40107dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 40117dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 40127dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 40137dce4e6fSZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0 40147dce4e6fSZhang Chen 40157dce4e6fSZhang Chensecondary: 40167dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 40177dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 40187dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 40197dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 40207dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 40217dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 40227dce4e6fSZhang Chen 40237dce4e6fSZhang Chen@end example 40247dce4e6fSZhang Chen 40257dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 40267dce4e6fSZhang Chenthe colo-compare git log. 40277dce4e6fSZhang Chen 40281653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 40291653a5f3SGonglei 40301653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 40311653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 40321653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 40331653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 40341653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 40351653a5f3SGonglei@var{queues} is 1. 40361653a5f3SGonglei 40371653a5f3SGonglei@example 40381653a5f3SGonglei 40391653a5f3SGonglei # qemu-system-x86_64 \ 40401653a5f3SGonglei [...] \ 40411653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 40421653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 40431653a5f3SGonglei [...] 40441653a5f3SGonglei@end example 40451653a5f3SGonglei 4046ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4047ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4048ac1d8878SDaniel P. Berrange 4049ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4050ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4051ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4052ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4053ac1d8878SDaniel P. Berrange 4054ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4055ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4056ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4057ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4058ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4059ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4060ac1d8878SDaniel P. Berrange 4061ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4062ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4063ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4064ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4065ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4066ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4067ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 406869c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4069ac1d8878SDaniel P. Berrange 4070ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4071ac1d8878SDaniel P. Berrange 4072ac1d8878SDaniel P. Berrange@example 4073ac1d8878SDaniel P. Berrange 4074ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,data=letmein,format=raw 4075ac1d8878SDaniel P. Berrange 4076ac1d8878SDaniel P. Berrange@end example 4077ac1d8878SDaniel P. Berrange 4078ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4079ac1d8878SDaniel P. Berrange 4080ac1d8878SDaniel P. Berrange # echo -n "letmein" > mypasswd.txt 4081ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 4082ac1d8878SDaniel P. Berrange 4083ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4084ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4085ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4086ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4087ac1d8878SDaniel P. Berrange 4088ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4089ac1d8878SDaniel P. Berrange 4090ac1d8878SDaniel P. Berrange@example 4091ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4092ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4093ac1d8878SDaniel P. Berrange@end example 4094ac1d8878SDaniel P. Berrange 4095ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4096ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4097ac1d8878SDaniel P. Berrange 4098ac1d8878SDaniel P. Berrange@example 4099ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4100ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4101ac1d8878SDaniel P. Berrange@end example 4102ac1d8878SDaniel P. Berrange 4103ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4104ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4105ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4106ac1d8878SDaniel P. Berrange 4107ac1d8878SDaniel P. Berrange@example 4108ac1d8878SDaniel P. Berrange # SECRET=$(echo -n "letmein" | 4109ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4110ac1d8878SDaniel P. Berrange@end example 4111ac1d8878SDaniel P. Berrange 4112ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4113ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4114ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4115ac1d8878SDaniel P. Berrange 4116ac1d8878SDaniel P. Berrange@example 4117ac1d8878SDaniel P. Berrange # $QEMU \ 4118ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4119ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4120ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4121ac1d8878SDaniel P. Berrange@end example 4122ac1d8878SDaniel P. Berrange 4123b9174d4fSDaniel P. Berrange@end table 4124b9174d4fSDaniel P. Berrange 4125b9174d4fSDaniel P. BerrangeETEXI 4126b9174d4fSDaniel P. Berrange 4127b9174d4fSDaniel P. Berrange 41283dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 41293dbf2c7fSStefan WeilSTEXI 41303dbf2c7fSStefan Weil@end table 41313dbf2c7fSStefan WeilETEXI 4132