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 9de6b4f90SMarkus ArmbrusterDEFHEADING(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" 34d661d9a4SJustin Terry (VM) " supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n" 35d1048befSDon Slutz " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 368490fc78SLuiz Capitulino " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 37a52a7fdfSLe Tan " mem-merge=on|off controls memory merge support (default: on)\n" 382eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 399850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4087252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 41902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 42274250c3SXiao Feng Ren " enforce-config-section=on|off enforce configuration section migration (default=off)\n" 43244b3f44STao Xu " memory-encryption=@var{} memory encryption object to use (default=none)\n" 44244b3f44STao Xu " hmat=on|off controls ACPI HMAT support (default=off)\n", 4580f52a66SJan Kiszka QEMU_ARCH_ALL) 465824d651Sblueswir1STEXI 4780f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 4880f52a66SJan Kiszka@findex -machine 49585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 508bfce83aSDaniel P. Berrangeavailable machines. 518bfce83aSDaniel P. Berrange 528bfce83aSDaniel P. BerrangeFor architectures which aim to support live migration compatibility 538bfce83aSDaniel P. Berrangeacross releases, each release will introduce a new versioned machine 548bfce83aSDaniel P. Berrangetype. For example, the 2.8.0 release introduced machine types 558bfce83aSDaniel P. Berrange``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 568bfce83aSDaniel P. Berrange 578bfce83aSDaniel P. BerrangeTo allow live migration of guests from QEMU version 2.8.0, to QEMU 588bfce83aSDaniel P. Berrangeversion 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 598bfce83aSDaniel P. Berrangeand ``pc-q35-2.8'' machines too. To allow users live migrating VMs 608bfce83aSDaniel P. Berrangeto skip multiple intermediate releases when upgrading, new releases 618bfce83aSDaniel P. Berrangeof QEMU will support machine types from many previous versions. 628bfce83aSDaniel P. Berrange 638bfce83aSDaniel P. BerrangeSupported machine properties are: 6480f52a66SJan Kiszka@table @option 6580f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 6680f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 67d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 68bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 69bde4d920SThomas Huthfails to initialize. 70d1048befSDon Slutz@item vmport=on|off|auto 71d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 72d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 73d1048befSDon Slutzis on. 74ddb97f1dSJason Baron@item dump-guest-core=on|off 75ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 768490fc78SLuiz Capitulino@item mem-merge=on|off 778490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 788490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 798490fc78SLuiz Capitulino(enabled by default). 802eb1cd07STony Krowiak@item aes-key-wrap=on|off 812eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 822eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 832eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 842eb1cd07STony Krowiak@item dea-key-wrap=on|off 852eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 862eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 872eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 8887252e1bSXiao Guangrong@item nvdimm=on|off 8987252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 9016f72448SPeter Xu@item enforce-config-section=on|off 9116f72448SPeter XuIf @option{enforce-config-section} is set to @var{on}, force migration 9216f72448SPeter Xucode to send configuration section even if the machine-type sets the 9316f72448SPeter Xu@option{migration.send-configuration} property to @var{off}. 9416f72448SPeter XuNOTE: this parameter is deprecated. Please use @option{-global} 9516f72448SPeter Xu@option{migration.send-configuration}=@var{on|off} instead. 96db588194SBrijesh Singh@item memory-encryption=@var{} 97db588194SBrijesh SinghMemory encryption object to use. The default is none. 98244b3f44STao Xu@item hmat=on|off 99244b3f44STao XuEnables or disables ACPI Heterogeneous Memory Attribute Table (HMAT) support. 100244b3f44STao XuThe default is off. 10180f52a66SJan Kiszka@end table 1025824d651Sblueswir1ETEXI 1035824d651Sblueswir1 10480f52a66SJan KiszkaHXCOMM Deprecated by -machine 10580f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 10680f52a66SJan Kiszka 1075824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 108585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 1095824d651Sblueswir1STEXI 1105824d651Sblueswir1@item -cpu @var{model} 1116616b2adSStefan Weil@findex -cpu 112585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 1135824d651Sblueswir1ETEXI 1145824d651Sblueswir1 1158d4e9146SKONRAD FredericDEF("accel", HAS_ARG, QEMU_OPTION_accel, 116fe174132SPaolo Bonzini "-accel [accel=]accelerator[,prop[=value][,...]]\n" 117d661d9a4SJustin Terry (VM) " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n" 11846472d82SPaolo Bonzini " igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n" 11911bc4a13SPaolo Bonzini " kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n" 12023b0898eSPaolo Bonzini " kvm-shadow-mem=size of KVM shadow MMU in bytes\n" 121fe174132SPaolo Bonzini " tb-size=n (TCG translation block cache size)\n" 1220b3c5c81SEduardo Habkost " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL) 1238d4e9146SKONRAD FredericSTEXI 1248d4e9146SKONRAD Frederic@item -accel @var{name}[,prop=@var{value}[,...]] 1258d4e9146SKONRAD Frederic@findex -accel 1268d4e9146SKONRAD FredericThis is used to enable an accelerator. Depending on the target architecture, 127d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 128bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 129bde4d920SThomas Huthfails to initialize. 1308d4e9146SKONRAD Frederic@table @option 13146472d82SPaolo Bonzini@item igd-passthru=on|off 13246472d82SPaolo BonziniWhen Xen is in use, this option controls whether Intel integrated graphics 13346472d82SPaolo Bonzinidevices can be passed through to the guest (default=off) 13411bc4a13SPaolo Bonzini@item kernel-irqchip=on|off|split 13511bc4a13SPaolo BonziniControls KVM in-kernel irqchip support. The default is full acceleration of the 13611bc4a13SPaolo Bonziniinterrupt controllers. On x86, split irqchip reduces the kernel attack 13711bc4a13SPaolo Bonzinisurface, at a performance cost for non-MSI interrupts. Disabling the in-kernel 13811bc4a13SPaolo Bonziniirqchip completely is not recommended except for debugging purposes. 13923b0898eSPaolo Bonzini@item kvm-shadow-mem=size 14023b0898eSPaolo BonziniDefines the size of the KVM shadow MMU. 141fe174132SPaolo Bonzini@item tb-size=@var{n} 142fe174132SPaolo BonziniControls the size (in MiB) of the TCG translation block cache. 1438d4e9146SKONRAD Frederic@item thread=single|multi 1448d4e9146SKONRAD FredericControls number of TCG threads. When the TCG is multi-threaded there will be one 1458d4e9146SKONRAD Fredericthread per vCPU therefor taking advantage of additional host cores. The default 1468d4e9146SKONRAD Fredericis to enable multi-threading where both the back-end and front-ends support it and 1478d4e9146SKONRAD Fredericno incompatible TCG features have been enabled (e.g. icount/replay). 1488d4e9146SKONRAD Frederic@end table 1498d4e9146SKONRAD FredericETEXI 1508d4e9146SKONRAD Frederic 1515824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 1521b458422SLike Xu "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n" 1536be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1546be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 155ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 1561b458422SLike Xu " cores= number of CPU cores on one socket (for PC, it's on one die)\n" 15758a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 1581b458422SLike Xu " dies= number of CPU dies on one socket (for PC only)\n" 159ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 160ad96090aSBlue Swirl QEMU_ARCH_ALL) 1615824d651Sblueswir1STEXI 1621b458422SLike Xu@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1636616b2adSStefan Weil@findex -smp 1645824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1655824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1665824d651Sblueswir1to 4. 1671b458422SLike XuFor the PC target, the number of @var{cores} per die, the number of @var{threads} 1681b458422SLike Xuper cores, the number of @var{dies} per packages and the total number of 1691b458422SLike Xu@var{sockets} can be specified. Missing values will be computed. 1701b458422SLike XuIf any on the three values is given, the total number of CPUs @var{n} can be omitted. 1711b458422SLike Xu@var{maxcpus} specifies the maximum number of hotpluggable CPUs. 1725824d651Sblueswir1ETEXI 1735824d651Sblueswir1 174268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 175244b3f44STao Xu "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n" 176244b3f44STao Xu "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n" 1772d19c656SIgor Mammedov "-numa dist,src=source,dst=destination,val=distance\n" 178*9b12dfa0SLiu Jingqi "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n" 179*9b12dfa0SLiu Jingqi "-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n", 1802d19c656SIgor Mammedov QEMU_ARCH_ALL) 181268a362cSaliguoriSTEXI 182244b3f44STao Xu@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}] 183244b3f44STao Xu@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}] 1840f203430SHe Chen@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 185419fcdecSIgor Mammedov@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 186*9b12dfa0SLiu Jingqi@itemx -numa hmat-lb,initiator=@var{node},target=@var{node},hierarchy=@var{hierarchy},data-type=@var{tpye}[,latency=@var{lat}][,bandwidth=@var{bw}] 1876616b2adSStefan Weil@findex -numa 1884b9a5dd7SEduardo HabkostDefine a NUMA node and assign RAM and VCPUs to it. 1890f203430SHe ChenSet the NUMA distance from a source node to a destination node. 190*9b12dfa0SLiu JingqiSet the ACPI Heterogeneous Memory Attributes for the given nodes. 1917febe36fSPaolo Bonzini 192419fcdecSIgor MammedovLegacy VCPU assignment uses @samp{cpus} option where 1934b9a5dd7SEduardo Habkost@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 1944b9a5dd7SEduardo Habkost@samp{cpus} option represent a contiguous range of CPU indexes 1954b9a5dd7SEduardo Habkost(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 1964b9a5dd7SEduardo Habkostset of VCPUs can be represented by providing multiple @samp{cpus} 1974b9a5dd7SEduardo Habkostoptions. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 1984b9a5dd7SEduardo Habkostsplit between them. 1994b9a5dd7SEduardo Habkost 2004b9a5dd7SEduardo HabkostFor example, the following option assigns VCPUs 0, 1, 2 and 5 to 2014b9a5dd7SEduardo Habkosta NUMA node: 2024b9a5dd7SEduardo Habkost@example 2034b9a5dd7SEduardo Habkost-numa node,cpus=0-2,cpus=5 2044b9a5dd7SEduardo Habkost@end example 2054b9a5dd7SEduardo Habkost 206419fcdecSIgor Mammedov@samp{cpu} option is a new alternative to @samp{cpus} option 207419fcdecSIgor Mammedovwhich uses @samp{socket-id|core-id|thread-id} properties to assign 208419fcdecSIgor MammedovCPU objects to a @var{node} using topology layout properties of CPU. 209419fcdecSIgor MammedovThe set of properties is machine specific, and depends on used 210419fcdecSIgor Mammedovmachine type/@samp{smp} options. It could be queried with 211419fcdecSIgor Mammedov@samp{hotpluggable-cpus} monitor command. 212419fcdecSIgor Mammedov@samp{node-id} property specifies @var{node} to which CPU object 213419fcdecSIgor Mammedovwill be assigned, it's required for @var{node} to be declared 214419fcdecSIgor Mammedovwith @samp{node} option before it's used with @samp{cpu} option. 215419fcdecSIgor Mammedov 216419fcdecSIgor MammedovFor example: 217419fcdecSIgor Mammedov@example 218419fcdecSIgor Mammedov-M pc \ 219419fcdecSIgor Mammedov-smp 1,sockets=2,maxcpus=2 \ 220419fcdecSIgor Mammedov-numa node,nodeid=0 -numa node,nodeid=1 \ 221419fcdecSIgor Mammedov-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 222419fcdecSIgor Mammedov@end example 223419fcdecSIgor Mammedov 2244b9a5dd7SEduardo Habkost@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 2254b9a5dd7SEduardo Habkostassigns RAM from a given memory backend device to a node. If 2264b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 2274b9a5dd7SEduardo Habkostsplit equally between them. 2284b9a5dd7SEduardo Habkost 2294b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 2304b9a5dd7SEduardo Habkostif one node uses @samp{memdev}, all of them have to use it. 2314b9a5dd7SEduardo Habkost 232244b3f44STao Xu@samp{initiator} is an additional option that points to an @var{initiator} 233244b3f44STao XuNUMA node that has best performance (the lowest latency or largest bandwidth) 234244b3f44STao Xuto this NUMA @var{node}. Note that this option can be set only when 235244b3f44STao Xuthe machine property 'hmat' is set to 'on'. 236244b3f44STao Xu 237244b3f44STao XuFollowing example creates a machine with 2 NUMA nodes, node 0 has CPU. 238244b3f44STao Xunode 1 has only memory, and its initiator is node 0. Note that because 239244b3f44STao Xunode 0 has CPU, by default the initiator of node 0 is itself and must be 240244b3f44STao Xuitself. 241244b3f44STao Xu@example 242244b3f44STao Xu-machine hmat=on \ 243244b3f44STao Xu-m 2G,slots=2,maxmem=4G \ 244244b3f44STao Xu-object memory-backend-ram,size=1G,id=m0 \ 245244b3f44STao Xu-object memory-backend-ram,size=1G,id=m1 \ 246244b3f44STao Xu-numa node,nodeid=0,memdev=m0 \ 247244b3f44STao Xu-numa node,nodeid=1,memdev=m1,initiator=0 \ 248244b3f44STao Xu-smp 2,sockets=2,maxcpus=2 \ 249244b3f44STao Xu-numa cpu,node-id=0,socket-id=0 \ 250244b3f44STao Xu-numa cpu,node-id=0,socket-id=1 251244b3f44STao Xu@end example 252244b3f44STao Xu 2530f203430SHe Chen@var{source} and @var{destination} are NUMA node IDs. 2540f203430SHe Chen@var{distance} is the NUMA distance from @var{source} to @var{destination}. 2550f203430SHe ChenThe distance from a node to itself is always 10. If any pair of nodes is 2560f203430SHe Chengiven a distance, then all pairs must be given distances. Although, when 2570f203430SHe Chendistances are only given in one direction for each pair of nodes, then 2580f203430SHe Chenthe distances in the opposite directions are assumed to be the same. If, 2590f203430SHe Chenhowever, an asymmetrical pair of distances is given for even one node 2600f203430SHe Chenpair, then all node pairs must be provided distance values for both 2610f203430SHe Chendirections, even when they are symmetrical. When a node is unreachable 2620f203430SHe Chenfrom another node, set the pair's distance to 255. 2630f203430SHe Chen 2644b9a5dd7SEduardo HabkostNote that the -@option{numa} option doesn't allocate any of the 2654b9a5dd7SEduardo Habkostspecified resources, it just assigns existing resources to NUMA 2664b9a5dd7SEduardo Habkostnodes. This means that one still has to use the @option{-m}, 2674b9a5dd7SEduardo Habkost@option{-smp} options to allocate RAM and VCPUs respectively. 2684b9a5dd7SEduardo Habkost 269*9b12dfa0SLiu JingqiUse @samp{hmat-lb} to set System Locality Latency and Bandwidth Information 270*9b12dfa0SLiu Jingqibetween initiator and target NUMA nodes in ACPI Heterogeneous Attribute Memory Table (HMAT). 271*9b12dfa0SLiu JingqiInitiator NUMA node can create memory requests, usually it has one or more processors. 272*9b12dfa0SLiu JingqiTarget NUMA node contains addressable memory. 273*9b12dfa0SLiu Jingqi 274*9b12dfa0SLiu JingqiIn @samp{hmat-lb} option, @var{node} are NUMA node IDs. @var{hierarchy} is the memory 275*9b12dfa0SLiu Jingqihierarchy of the target NUMA node: if @var{hierarchy} is 'memory', the structure 276*9b12dfa0SLiu Jingqirepresents the memory performance; if @var{hierarchy} is 'first-level|second-level|third-level', 277*9b12dfa0SLiu Jingqithis structure represents aggregated performance of memory side caches for each domain. 278*9b12dfa0SLiu Jingqi@var{type} of 'data-type' is type of data represented by this structure instance: 279*9b12dfa0SLiu Jingqiif 'hierarchy' is 'memory', 'data-type' is 'access|read|write' latency or 'access|read|write' 280*9b12dfa0SLiu Jingqibandwidth of the target memory; if 'hierarchy' is 'first-level|second-level|third-level', 281*9b12dfa0SLiu Jingqi'data-type' is 'access|read|write' hit latency or 'access|read|write' hit bandwidth of the 282*9b12dfa0SLiu Jingqitarget memory side cache. 283*9b12dfa0SLiu Jingqi 284*9b12dfa0SLiu Jingqi@var{lat} is latency value in nanoseconds. @var{bw} is bandwidth value, 285*9b12dfa0SLiu Jingqithe possible value and units are NUM[M|G|T], mean that the bandwidth value are 286*9b12dfa0SLiu JingqiNUM byte per second (or MB/s, GB/s or TB/s depending on used suffix). 287*9b12dfa0SLiu JingqiNote that if latency or bandwidth value is 0, means the corresponding latency or 288*9b12dfa0SLiu Jingqibandwidth information is not provided. 289*9b12dfa0SLiu Jingqi 290*9b12dfa0SLiu JingqiFor example, the following options describe 2 NUMA nodes. Node 0 has 2 cpus and 291*9b12dfa0SLiu Jingqia ram, node 1 has only a ram. The processors in node 0 access memory in node 292*9b12dfa0SLiu Jingqi0 with access-latency 5 nanoseconds, access-bandwidth is 200 MB/s; 293*9b12dfa0SLiu JingqiThe processors in NUMA node 0 access memory in NUMA node 1 with access-latency 10 294*9b12dfa0SLiu Jingqinanoseconds, access-bandwidth is 100 MB/s. 295*9b12dfa0SLiu Jingqi@example 296*9b12dfa0SLiu Jingqi-machine hmat=on \ 297*9b12dfa0SLiu Jingqi-m 2G \ 298*9b12dfa0SLiu Jingqi-object memory-backend-ram,size=1G,id=m0 \ 299*9b12dfa0SLiu Jingqi-object memory-backend-ram,size=1G,id=m1 \ 300*9b12dfa0SLiu Jingqi-smp 2 \ 301*9b12dfa0SLiu Jingqi-numa node,nodeid=0,memdev=m0 \ 302*9b12dfa0SLiu Jingqi-numa node,nodeid=1,memdev=m1,initiator=0 \ 303*9b12dfa0SLiu Jingqi-numa cpu,node-id=0,socket-id=0 \ 304*9b12dfa0SLiu Jingqi-numa cpu,node-id=0,socket-id=1 \ 305*9b12dfa0SLiu Jingqi-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \ 306*9b12dfa0SLiu Jingqi-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \ 307*9b12dfa0SLiu Jingqi-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \ 308*9b12dfa0SLiu Jingqi-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M 309*9b12dfa0SLiu Jingqi@end example 310*9b12dfa0SLiu Jingqi 311268a362cSaliguoriETEXI 312268a362cSaliguori 31310adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 31410adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 31510adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 31610adb8beSMarkus ArmbrusterSTEXI 31710adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 31810adb8beSMarkus Armbruster@findex -add-fd 31910adb8beSMarkus Armbruster 32010adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 32110adb8beSMarkus Armbruster 32210adb8beSMarkus Armbruster@table @option 32310adb8beSMarkus Armbruster@item fd=@var{fd} 32410adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 32510adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 32610adb8beSMarkus Armbruster@item set=@var{set} 32710adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 32810adb8beSMarkus Armbruster@item opaque=@var{opaque} 32910adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 33010adb8beSMarkus Armbruster@end table 33110adb8beSMarkus Armbruster 33210adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 33310adb8beSMarkus Armbruster@example 334664785acSThomas Huth@value{qemu_system} \ 335664785acSThomas Huth -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 336664785acSThomas Huth -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 33710adb8beSMarkus Armbruster -drive file=/dev/fdset/2,index=0,media=disk 33810adb8beSMarkus Armbruster@end example 33910adb8beSMarkus ArmbrusterETEXI 34010adb8beSMarkus Armbruster 34110adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 34210adb8beSMarkus Armbruster "-set group.id.arg=value\n" 34310adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 34410adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 34510adb8beSMarkus ArmbrusterSTEXI 34610adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 34710adb8beSMarkus Armbruster@findex -set 348e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 34910adb8beSMarkus ArmbrusterETEXI 35010adb8beSMarkus Armbruster 35110adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 3523751d7c4SPaolo Bonzini "-global driver.property=value\n" 3533751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 35410adb8beSMarkus Armbruster " set a global default for a driver property\n", 35510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 35610adb8beSMarkus ArmbrusterSTEXI 35710adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 3583751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 35910adb8beSMarkus Armbruster@findex -global 36010adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 36110adb8beSMarkus Armbruster 36210adb8beSMarkus Armbruster@example 363664785acSThomas Huth@value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img 36410adb8beSMarkus Armbruster@end example 36510adb8beSMarkus Armbruster 36610adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 36710adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 36810adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 3693751d7c4SPaolo Bonzini 370ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 371ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 372ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 37310adb8beSMarkus ArmbrusterETEXI 37410adb8beSMarkus Armbruster 37510adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 37610adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 377c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 37810adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 37910adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 38010adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 38110adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 38210adb8beSMarkus Armbruster QEMU_ARCH_ALL) 38310adb8beSMarkus ArmbrusterSTEXI 384c8a6ae8bSAmos 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] 38510adb8beSMarkus Armbruster@findex -boot 38610adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 387d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 38810adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 38910adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 39010adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 391c0d9f7d0SThomas Huth@option{once}. Note that the @option{order} or @option{once} parameter 392c0d9f7d0SThomas Huthshould not be used together with the @option{bootindex} property of 393c0d9f7d0SThomas Huthdevices, since the firmware implementations normally do not support both 394c0d9f7d0SThomas Huthat the same time. 39510adb8beSMarkus Armbruster 39610adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 39710adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 39810adb8beSMarkus Armbruster 39910adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 40010adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 40110adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 40210adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 40310adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 40410adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 40510adb8beSMarkus Armbruster 40610adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 4078937a39dSHan Hanwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 4088937a39dSHan Hanreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 40910adb8beSMarkus Armbrustersystem support it. 41010adb8beSMarkus Armbruster 411c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 412c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 413c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 414c8a6ae8bSAmos Kong 41510adb8beSMarkus Armbruster@example 41610adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 417664785acSThomas Huth@value{qemu_system_x86} -boot order=nc 41810adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 419664785acSThomas Huth@value{qemu_system_x86} -boot once=d 42010adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 421664785acSThomas Huth@value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000 42210adb8beSMarkus Armbruster@end example 42310adb8beSMarkus Armbruster 42410adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 42510adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 42610adb8beSMarkus ArmbrusterETEXI 42710adb8beSMarkus Armbruster 42810adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 42989f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 4306e1d3c1cSIgor Mammedov " configure guest RAM\n" 4310daba1f0SAlexander Graf " size: initial amount of guest memory\n" 432c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 433b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 434b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 4356e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 43610adb8beSMarkus ArmbrusterSTEXI 4379fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 43810adb8beSMarkus Armbruster@findex -m 4399fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 4409fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 4419fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 4429fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 4439fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 4449fcc0794SLuiz Capitulino 4459fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 4469fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 4479fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 4489fcc0794SLuiz Capitulino 4499fcc0794SLuiz Capitulino@example 450664785acSThomas Huth@value{qemu_system} -m 1G,slots=3,maxmem=4G 4519fcc0794SLuiz Capitulino@end example 4529fcc0794SLuiz Capitulino 4539fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 4549fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 45510adb8beSMarkus ArmbrusterETEXI 45610adb8beSMarkus Armbruster 45710adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 45810adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 45910adb8beSMarkus ArmbrusterSTEXI 46010adb8beSMarkus Armbruster@item -mem-path @var{path} 46110adb8beSMarkus Armbruster@findex -mem-path 46210adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 46310adb8beSMarkus ArmbrusterETEXI 46410adb8beSMarkus Armbruster 46510adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 46610adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 46710adb8beSMarkus Armbruster QEMU_ARCH_ALL) 46810adb8beSMarkus ArmbrusterSTEXI 46910adb8beSMarkus Armbruster@item -mem-prealloc 47010adb8beSMarkus Armbruster@findex -mem-prealloc 47110adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 47210adb8beSMarkus ArmbrusterETEXI 47310adb8beSMarkus Armbruster 47410adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 47510adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 47610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 47710adb8beSMarkus ArmbrusterSTEXI 47810adb8beSMarkus Armbruster@item -k @var{language} 47910adb8beSMarkus Armbruster@findex -k 48010adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 48110adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 48232945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 48310adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 48410adb8beSMarkus Armbrusterhosts. 48510adb8beSMarkus Armbruster 48610adb8beSMarkus ArmbrusterThe available layouts are: 48710adb8beSMarkus Armbruster@example 48810adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 48910adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 49010adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 49110adb8beSMarkus Armbruster@end example 49210adb8beSMarkus Armbruster 49310adb8beSMarkus ArmbrusterThe default is @code{en-us}. 49410adb8beSMarkus ArmbrusterETEXI 49510adb8beSMarkus Armbruster 49610adb8beSMarkus Armbruster 497f0b3d811SKővágó, ZoltánHXCOMM Deprecated by -audiodev 49810adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 499f0b3d811SKővágó, Zoltán "-audio-help show -audiodev equivalent of the currently specified audio settings\n", 50010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 50110adb8beSMarkus ArmbrusterSTEXI 50210adb8beSMarkus Armbruster@item -audio-help 50310adb8beSMarkus Armbruster@findex -audio-help 504f0b3d811SKővágó, ZoltánWill show the -audiodev equivalent of the currently specified 505f0b3d811SKővágó, Zoltán(deprecated) environment variables. 506f0b3d811SKővágó, ZoltánETEXI 507f0b3d811SKővágó, Zoltán 508f0b3d811SKővágó, ZoltánDEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev, 509f0b3d811SKővágó, Zoltán "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n" 510f0b3d811SKővágó, Zoltán " specifies the audio backend to use\n" 511f0b3d811SKővágó, Zoltán " id= identifier of the backend\n" 512f0b3d811SKővágó, Zoltán " timer-period= timer period in microseconds\n" 5138efac073SKővágó, Zoltán " in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n" 514f0b3d811SKővágó, Zoltán " in|out.fixed-settings= use fixed settings for host audio\n" 515f0b3d811SKővágó, Zoltán " in|out.frequency= frequency to use with fixed settings\n" 516f0b3d811SKővágó, Zoltán " in|out.channels= number of channels to use with fixed settings\n" 517f0b3d811SKővágó, Zoltán " in|out.format= sample format to use with fixed settings\n" 518f0b3d811SKővágó, Zoltán " valid values: s8, s16, s32, u8, u16, u32\n" 519f0b3d811SKővágó, Zoltán " in|out.voices= number of voices to use\n" 5208624725bSStefan Hajnoczi " in|out.buffer-length= length of buffer in microseconds\n" 521f0b3d811SKővágó, Zoltán "-audiodev none,id=id,[,prop[=value][,...]]\n" 522f0b3d811SKővágó, Zoltán " dummy driver that discards all output\n" 523f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_ALSA 524f0b3d811SKővágó, Zoltán "-audiodev alsa,id=id[,prop[=value][,...]]\n" 525f0b3d811SKővágó, Zoltán " in|out.dev= name of the audio device to use\n" 526dfc54343SStefan Hajnoczi " in|out.period-length= length of period in microseconds\n" 527f0b3d811SKővágó, Zoltán " in|out.try-poll= attempt to use poll mode\n" 528f0b3d811SKővágó, Zoltán " threshold= threshold (in microseconds) when playback starts\n" 529f0b3d811SKővágó, Zoltán#endif 530f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_COREAUDIO 531f0b3d811SKővágó, Zoltán "-audiodev coreaudio,id=id[,prop[=value][,...]]\n" 532f0b3d811SKővágó, Zoltán " in|out.buffer-count= number of buffers\n" 533f0b3d811SKővágó, Zoltán#endif 534f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_DSOUND 535f0b3d811SKővágó, Zoltán "-audiodev dsound,id=id[,prop[=value][,...]]\n" 536f0b3d811SKővágó, Zoltán " latency= add extra latency to playback in microseconds\n" 537f0b3d811SKővágó, Zoltán#endif 538f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_OSS 539f0b3d811SKővágó, Zoltán "-audiodev oss,id=id[,prop[=value][,...]]\n" 540f0b3d811SKővágó, Zoltán " in|out.dev= path of the audio device to use\n" 541f0b3d811SKővágó, Zoltán " in|out.buffer-count= number of buffers\n" 542f0b3d811SKővágó, Zoltán " in|out.try-poll= attempt to use poll mode\n" 543f0b3d811SKővágó, Zoltán " try-mmap= try using memory mapped access\n" 544f0b3d811SKővágó, Zoltán " exclusive= open device in exclusive mode\n" 545f0b3d811SKővágó, Zoltán " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n" 546f0b3d811SKővágó, Zoltán#endif 547f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_PA 548f0b3d811SKővágó, Zoltán "-audiodev pa,id=id[,prop[=value][,...]]\n" 549f0b3d811SKővágó, Zoltán " server= PulseAudio server address\n" 550f0b3d811SKővágó, Zoltán " in|out.name= source/sink device name\n" 55114d4f011SStefan Hajnoczi " in|out.latency= desired latency in microseconds\n" 552f0b3d811SKővágó, Zoltán#endif 553f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_SDL 554f0b3d811SKővágó, Zoltán "-audiodev sdl,id=id[,prop[=value][,...]]\n" 555f0b3d811SKővágó, Zoltán#endif 556f0b3d811SKővágó, Zoltán#ifdef CONFIG_SPICE 557f0b3d811SKővágó, Zoltán "-audiodev spice,id=id[,prop[=value][,...]]\n" 558f0b3d811SKővágó, Zoltán#endif 559f0b3d811SKővágó, Zoltán "-audiodev wav,id=id[,prop[=value][,...]]\n" 560f0b3d811SKővágó, Zoltán " path= path of wav file to record\n", 561f0b3d811SKővágó, Zoltán QEMU_ARCH_ALL) 562f0b3d811SKővágó, ZoltánSTEXI 563f0b3d811SKővágó, Zoltán@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]] 564f0b3d811SKővágó, Zoltán@findex -audiodev 565f0b3d811SKővágó, ZoltánAdds a new audio backend @var{driver} identified by @var{id}. There are 566f0b3d811SKővágó, Zoltánglobal and driver specific properties. Some values can be set 567f0b3d811SKővágó, Zoltándifferently for input and output, they're marked with @code{in|out.}. 568f0b3d811SKővágó, ZoltánYou can set the input's property with @code{in.@var{prop}} and the 569f0b3d811SKővágó, Zoltánoutput's property with @code{out.@var{prop}}. For example: 570f0b3d811SKővágó, Zoltán@example 571f0b3d811SKővágó, Zoltán-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 572f0b3d811SKővágó, Zoltán-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified 573f0b3d811SKővágó, Zoltán@end example 574f0b3d811SKővágó, Zoltán 5758efac073SKővágó, ZoltánNOTE: parameter validation is known to be incomplete, in many cases 5768efac073SKővágó, Zoltánspecifying an invalid option causes QEMU to print an error message and 5778efac073SKővágó, Zoltáncontinue emulation without sound. 5788efac073SKővágó, Zoltán 579f0b3d811SKővágó, ZoltánValid global options are: 580f0b3d811SKővágó, Zoltán 581f0b3d811SKővágó, Zoltán@table @option 582f0b3d811SKővágó, Zoltán@item id=@var{identifier} 583f0b3d811SKővágó, ZoltánIdentifies the audio backend. 584f0b3d811SKővágó, Zoltán 585f0b3d811SKővágó, Zoltán@item timer-period=@var{period} 586f0b3d811SKővágó, ZoltánSets the timer @var{period} used by the audio subsystem in microseconds. 587f0b3d811SKővágó, ZoltánDefault is 10000 (10 ms). 588f0b3d811SKővágó, Zoltán 5898efac073SKővágó, Zoltán@item in|out.mixing-engine=on|off 5908efac073SKővágó, ZoltánUse QEMU's mixing engine to mix all streams inside QEMU and convert 5918efac073SKővágó, Zoltánaudio formats when not supported by the backend. When off, 5928efac073SKővágó, Zoltán@var{fixed-settings} must be off too. Note that disabling this option 5938efac073SKővágó, Zoltánmeans that the selected backend must support multiple streams and the 5948efac073SKővágó, Zoltánaudio formats used by the virtual cards, otherwise you'll get no sound. 5958efac073SKővágó, ZoltánIt's not recommended to disable this option unless you want to use 5.1 5968efac073SKővágó, Zoltánor 7.1 audio, as mixing engine only supports mono and stereo audio. 5978efac073SKővágó, ZoltánDefault is on. 5988efac073SKővágó, Zoltán 599f0b3d811SKővágó, Zoltán@item in|out.fixed-settings=on|off 600f0b3d811SKővágó, ZoltánUse fixed settings for host audio. When off, it will change based on 601f0b3d811SKővágó, Zoltánhow the guest opens the sound card. In this case you must not specify 602f0b3d811SKővágó, Zoltán@var{frequency}, @var{channels} or @var{format}. Default is on. 603f0b3d811SKővágó, Zoltán 604f0b3d811SKővágó, Zoltán@item in|out.frequency=@var{frequency} 605f0b3d811SKővágó, ZoltánSpecify the @var{frequency} to use when using @var{fixed-settings}. 606f0b3d811SKővágó, ZoltánDefault is 44100Hz. 607f0b3d811SKővágó, Zoltán 608f0b3d811SKővágó, Zoltán@item in|out.channels=@var{channels} 609f0b3d811SKővágó, ZoltánSpecify the number of @var{channels} to use when using 610f0b3d811SKővágó, Zoltán@var{fixed-settings}. Default is 2 (stereo). 611f0b3d811SKővágó, Zoltán 612f0b3d811SKővágó, Zoltán@item in|out.format=@var{format} 613f0b3d811SKővágó, ZoltánSpecify the sample @var{format} to use when using @var{fixed-settings}. 614f0b3d811SKővágó, ZoltánValid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8}, 615f0b3d811SKővágó, Zoltán@code{u16}, @code{u32}. Default is @code{s16}. 616f0b3d811SKővágó, Zoltán 617f0b3d811SKővágó, Zoltán@item in|out.voices=@var{voices} 618f0b3d811SKővágó, ZoltánSpecify the number of @var{voices} to use. Default is 1. 619f0b3d811SKővágó, Zoltán 6208624725bSStefan Hajnoczi@item in|out.buffer-length=@var{usecs} 621f0b3d811SKővágó, ZoltánSets the size of the buffer in microseconds. 622f0b3d811SKővágó, Zoltán 623f0b3d811SKővágó, Zoltán@end table 624f0b3d811SKővágó, Zoltán 625f0b3d811SKővágó, Zoltán@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]] 626f0b3d811SKővágó, ZoltánCreates a dummy backend that discards all outputs. This backend has no 627f0b3d811SKővágó, Zoltánbackend specific properties. 628f0b3d811SKővágó, Zoltán 629f0b3d811SKővágó, Zoltán@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 630f0b3d811SKővágó, ZoltánCreates backend using the ALSA. This backend is only available on 631f0b3d811SKővágó, ZoltánLinux. 632f0b3d811SKővágó, Zoltán 633f0b3d811SKővágó, ZoltánALSA specific options are: 634f0b3d811SKővágó, Zoltán 635f0b3d811SKővágó, Zoltán@table @option 636f0b3d811SKővágó, Zoltán 637f0b3d811SKővágó, Zoltán@item in|out.dev=@var{device} 638f0b3d811SKővágó, ZoltánSpecify the ALSA @var{device} to use for input and/or output. Default 639f0b3d811SKővágó, Zoltánis @code{default}. 640f0b3d811SKővágó, Zoltán 641dfc54343SStefan Hajnoczi@item in|out.period-length=@var{usecs} 642f0b3d811SKővágó, ZoltánSets the period length in microseconds. 643f0b3d811SKővágó, Zoltán 644f0b3d811SKővágó, Zoltán@item in|out.try-poll=on|off 645f0b3d811SKővágó, ZoltánAttempt to use poll mode with the device. Default is on. 646f0b3d811SKővágó, Zoltán 647f0b3d811SKővágó, Zoltán@item threshold=@var{threshold} 648f0b3d811SKővágó, ZoltánThreshold (in microseconds) when playback starts. Default is 0. 649f0b3d811SKővágó, Zoltán 650f0b3d811SKővágó, Zoltán@end table 651f0b3d811SKővágó, Zoltán 652f0b3d811SKővágó, Zoltán@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]] 653f0b3d811SKővágó, ZoltánCreates a backend using Apple's Core Audio. This backend is only 654f0b3d811SKővágó, Zoltánavailable on Mac OS and only supports playback. 655f0b3d811SKővágó, Zoltán 656f0b3d811SKővágó, ZoltánCore Audio specific options are: 657f0b3d811SKővágó, Zoltán 658f0b3d811SKővágó, Zoltán@table @option 659f0b3d811SKővágó, Zoltán 660f0b3d811SKővágó, Zoltán@item in|out.buffer-count=@var{count} 661f0b3d811SKővágó, ZoltánSets the @var{count} of the buffers. 662f0b3d811SKővágó, Zoltán 663f0b3d811SKővágó, Zoltán@end table 664f0b3d811SKővágó, Zoltán 665f0b3d811SKővágó, Zoltán@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]] 666f0b3d811SKővágó, ZoltánCreates a backend using Microsoft's DirectSound. This backend is only 667f0b3d811SKővágó, Zoltánavailable on Windows and only supports playback. 668f0b3d811SKővágó, Zoltán 669f0b3d811SKővágó, ZoltánDirectSound specific options are: 670f0b3d811SKővágó, Zoltán 671f0b3d811SKővágó, Zoltán@table @option 672f0b3d811SKővágó, Zoltán 673f0b3d811SKővágó, Zoltán@item latency=@var{usecs} 674f0b3d811SKővágó, ZoltánAdd extra @var{usecs} microseconds latency to playback. Default is 675f0b3d811SKővágó, Zoltán10000 (10 ms). 676f0b3d811SKővágó, Zoltán 677f0b3d811SKővágó, Zoltán@end table 678f0b3d811SKővágó, Zoltán 679f0b3d811SKővágó, Zoltán@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]] 680f0b3d811SKővágó, ZoltánCreates a backend using OSS. This backend is available on most 681f0b3d811SKővágó, ZoltánUnix-like systems. 682f0b3d811SKővágó, Zoltán 683f0b3d811SKővágó, ZoltánOSS specific options are: 684f0b3d811SKővágó, Zoltán 685f0b3d811SKővágó, Zoltán@table @option 686f0b3d811SKővágó, Zoltán 687f0b3d811SKővágó, Zoltán@item in|out.dev=@var{device} 688f0b3d811SKővágó, ZoltánSpecify the file name of the OSS @var{device} to use. Default is 689f0b3d811SKővágó, Zoltán@code{/dev/dsp}. 690f0b3d811SKővágó, Zoltán 691f0b3d811SKővágó, Zoltán@item in|out.buffer-count=@var{count} 692f0b3d811SKővágó, ZoltánSets the @var{count} of the buffers. 693f0b3d811SKővágó, Zoltán 694f0b3d811SKővágó, Zoltán@item in|out.try-poll=on|of 695f0b3d811SKővágó, ZoltánAttempt to use poll mode with the device. Default is on. 696f0b3d811SKővágó, Zoltán 697f0b3d811SKővágó, Zoltán@item try-mmap=on|off 698f0b3d811SKővágó, ZoltánTry using memory mapped device access. Default is off. 699f0b3d811SKővágó, Zoltán 700f0b3d811SKővágó, Zoltán@item exclusive=on|off 701f0b3d811SKővágó, ZoltánOpen the device in exclusive mode (vmix won't work in this case). 702f0b3d811SKővágó, ZoltánDefault is off. 703f0b3d811SKővágó, Zoltán 704f0b3d811SKővágó, Zoltán@item dsp-policy=@var{policy} 705f0b3d811SKővágó, ZoltánSets the timing policy (between 0 and 10, where smaller number means 706f0b3d811SKővágó, Zoltánsmaller latency but higher CPU usage). Use -1 to use buffer sizes 707f0b3d811SKővágó, Zoltánspecified by @code{buffer} and @code{buffer-count}. This option is 708f0b3d811SKővágó, Zoltánignored if you do not have OSS 4. Default is 5. 709f0b3d811SKővágó, Zoltán 710f0b3d811SKővágó, Zoltán@end table 711f0b3d811SKővágó, Zoltán 712f0b3d811SKővágó, Zoltán@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 713f0b3d811SKővágó, ZoltánCreates a backend using PulseAudio. This backend is available on most 714f0b3d811SKővágó, Zoltánsystems. 715f0b3d811SKővágó, Zoltán 716f0b3d811SKővágó, ZoltánPulseAudio specific options are: 717f0b3d811SKővágó, Zoltán 718f0b3d811SKővágó, Zoltán@table @option 719f0b3d811SKővágó, Zoltán 720f0b3d811SKővágó, Zoltán@item server=@var{server} 721f0b3d811SKővágó, ZoltánSets the PulseAudio @var{server} to connect to. 722f0b3d811SKővágó, Zoltán 723f0b3d811SKővágó, Zoltán@item in|out.name=@var{sink} 724f0b3d811SKővágó, ZoltánUse the specified source/sink for recording/playback. 725f0b3d811SKővágó, Zoltán 72614d4f011SStefan Hajnoczi@item in|out.latency=@var{usecs} 72714d4f011SStefan HajnocziDesired latency in microseconds. The PulseAudio server will try to honor this 72814d4f011SStefan Hajnoczivalue but actual latencies may be lower or higher. 72914d4f011SStefan Hajnoczi 730f0b3d811SKővágó, Zoltán@end table 731f0b3d811SKővágó, Zoltán 732f0b3d811SKővágó, Zoltán@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]] 733f0b3d811SKővágó, ZoltánCreates a backend using SDL. This backend is available on most systems, 734f0b3d811SKővágó, Zoltánbut you should use your platform's native backend if possible. This 735f0b3d811SKővágó, Zoltánbackend has no backend specific properties. 736f0b3d811SKővágó, Zoltán 737f0b3d811SKővágó, Zoltán@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]] 738f0b3d811SKővágó, ZoltánCreates a backend that sends audio through SPICE. This backend requires 739f0b3d811SKővágó, Zoltán@code{-spice} and automatically selected in that case, so usually you 740f0b3d811SKővágó, Zoltáncan ignore this option. This backend has no backend specific 741f0b3d811SKővágó, Zoltánproperties. 742f0b3d811SKővágó, Zoltán 743f0b3d811SKővágó, Zoltán@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]] 744f0b3d811SKővágó, ZoltánCreates a backend that writes audio to a WAV file. 745f0b3d811SKővágó, Zoltán 746f0b3d811SKővágó, ZoltánBackend specific options are: 747f0b3d811SKővágó, Zoltán 748f0b3d811SKővágó, Zoltán@table @option 749f0b3d811SKővágó, Zoltán 750f0b3d811SKővágó, Zoltán@item path=@var{path} 751f0b3d811SKővágó, ZoltánWrite recorded audio into the specified file. Default is 752f0b3d811SKővágó, Zoltán@code{qemu.wav}. 753f0b3d811SKővágó, Zoltán 754f0b3d811SKővágó, Zoltán@end table 75510adb8beSMarkus ArmbrusterETEXI 75610adb8beSMarkus Armbruster 75710adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 75810adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 75910adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 76010adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 76110adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 76210adb8beSMarkus ArmbrusterSTEXI 76310adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 76410adb8beSMarkus Armbruster@findex -soundhw 76510adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 766664785acSThomas Huthavailable sound hardware. For example: 76710adb8beSMarkus Armbruster 76810adb8beSMarkus Armbruster@example 769664785acSThomas Huth@value{qemu_system_x86} -soundhw sb16,adlib disk.img 770664785acSThomas Huth@value{qemu_system_x86} -soundhw es1370 disk.img 771664785acSThomas Huth@value{qemu_system_x86} -soundhw ac97 disk.img 772664785acSThomas Huth@value{qemu_system_x86} -soundhw hda disk.img 773664785acSThomas Huth@value{qemu_system_x86} -soundhw all disk.img 774664785acSThomas Huth@value{qemu_system_x86} -soundhw help 77510adb8beSMarkus Armbruster@end example 77610adb8beSMarkus Armbruster 77710adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 77810adb8beSMarkus Armbrusterrequire manually specifying clocking. 77910adb8beSMarkus Armbruster 78010adb8beSMarkus Armbruster@example 78110adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 78210adb8beSMarkus Armbruster@end example 78310adb8beSMarkus ArmbrusterETEXI 78410adb8beSMarkus Armbruster 78510adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 78610adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 78710adb8beSMarkus Armbruster " add device (based on driver)\n" 78810adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 78910adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 79010adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 79110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 79210adb8beSMarkus ArmbrusterSTEXI 79310adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 79410adb8beSMarkus Armbruster@findex -device 79510adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 79610adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 79710adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 79810adb8beSMarkus Armbruster@code{-device @var{driver},help}. 799f8490451SCorey Minyard 800f8490451SCorey MinyardSome drivers are: 8017b0cd78bSCorey Minyard@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}] 802f8490451SCorey Minyard 803f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 804f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 805f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 806f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 807f8490451SCorey Minyard 808f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 809f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 810f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 811f8490451SCorey Minyardit. 812f8490451SCorey Minyard 8138c6fd7f3SCédric Le Goater@table @option 8147b0cd78bSCorey Minyard@item id=@var{id} 8157b0cd78bSCorey MinyardThe BMC id for interfaces to use this device. 8168c6fd7f3SCédric Le Goater@item slave_addr=@var{val} 8178c6fd7f3SCédric Le GoaterDefine slave address to use for the BMC. The default is 0x20. 8188c6fd7f3SCédric Le Goater@item sdrfile=@var{file} 8198c6fd7f3SCédric Le Goaterfile containing raw Sensor Data Records (SDR) data. The default is none. 820540c07d3SCédric Le Goater@item fruareasize=@var{val} 821540c07d3SCédric Le Goatersize of a Field Replaceable Unit (FRU) area. The default is 1024. 822540c07d3SCédric Le Goater@item frudatafile=@var{file} 823540c07d3SCédric Le Goaterfile containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 8247b0cd78bSCorey Minyard@item guid=@var{uuid} 8257b0cd78bSCorey Minyardvalue for the GUID for the BMC, in standard UUID format. If this is set, 8267b0cd78bSCorey Minyardget "Get GUID" command to the BMC will return it. Otherwise "Get GUID" 8277b0cd78bSCorey Minyardwill return an error. 8288c6fd7f3SCédric Le Goater@end table 8298c6fd7f3SCédric Le Goater 830f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 831f8490451SCorey Minyard 832f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 833f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 834f8490451SCorey Minyardto an external entity that provides the IPMI services. 835f8490451SCorey Minyard 836f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 837f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 838f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 839f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 840f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 841f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 842f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 843f8490451SCorey Minyardexposed to any outside network. 844f8490451SCorey Minyard 845f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 846f8490451SCorey Minyarddetails on the external interface. 847f8490451SCorey Minyard 848f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 849f8490451SCorey Minyard 850f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 851f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 852f8490451SCorey Minyard 853f8490451SCorey Minyard@table @option 854f8490451SCorey Minyard@item bmc=@var{id} 855f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 856f8490451SCorey Minyard@item ioport=@var{val} 857f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 858f8490451SCorey Minyard@item irq=@var{val} 859f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 860f8490451SCorey Minyardset this to 0. 861f8490451SCorey Minyard@end table 862f8490451SCorey Minyard 863f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 864f8490451SCorey Minyard 865f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 866f8490451SCorey Minyard0xe4 and the default interrupt is 5. 867f8490451SCorey Minyard 86810adb8beSMarkus ArmbrusterETEXI 86910adb8beSMarkus Armbruster 87010adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 8718f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 87210adb8beSMarkus Armbruster " set the name of the guest\n" 873479a5747SRoman Bolshakov " string1 sets the window title and string2 the process name\n" 874479a5747SRoman Bolshakov " When debug-threads is enabled, individual threads are given a separate name\n" 8758f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 87610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 87710adb8beSMarkus ArmbrusterSTEXI 87810adb8beSMarkus Armbruster@item -name @var{name} 87910adb8beSMarkus Armbruster@findex -name 88010adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 88110adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 88210adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 88310adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 8848f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 88510adb8beSMarkus ArmbrusterETEXI 88610adb8beSMarkus Armbruster 88710adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 88810adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 88910adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 89010adb8beSMarkus ArmbrusterSTEXI 89110adb8beSMarkus Armbruster@item -uuid @var{uuid} 89210adb8beSMarkus Armbruster@findex -uuid 89310adb8beSMarkus ArmbrusterSet system UUID. 89410adb8beSMarkus ArmbrusterETEXI 89510adb8beSMarkus Armbruster 89610adb8beSMarkus ArmbrusterSTEXI 89710adb8beSMarkus Armbruster@end table 89810adb8beSMarkus ArmbrusterETEXI 89910adb8beSMarkus ArmbrusterDEFHEADING() 90010adb8beSMarkus Armbruster 901de6b4f90SMarkus ArmbrusterDEFHEADING(Block device options:) 90210adb8beSMarkus ArmbrusterSTEXI 90310adb8beSMarkus Armbruster@table @option 90410adb8beSMarkus ArmbrusterETEXI 90510adb8beSMarkus Armbruster 9065824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 907ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 908ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 9095824d651Sblueswir1STEXI 9105824d651Sblueswir1@item -fda @var{file} 911f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 9126616b2adSStefan Weil@findex -fda 9136616b2adSStefan Weil@findex -fdb 91492a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 9155824d651Sblueswir1ETEXI 9165824d651Sblueswir1 9175824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 918ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 919ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 9205824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 921ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 922ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 9235824d651Sblueswir1STEXI 9245824d651Sblueswir1@item -hda @var{file} 925f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 926f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 927f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 9286616b2adSStefan Weil@findex -hda 9296616b2adSStefan Weil@findex -hdb 9306616b2adSStefan Weil@findex -hdc 9316616b2adSStefan Weil@findex -hdd 9325824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 9335824d651Sblueswir1ETEXI 9345824d651Sblueswir1 9355824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 936ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 937ad96090aSBlue Swirl QEMU_ARCH_ALL) 9385824d651Sblueswir1STEXI 9395824d651Sblueswir1@item -cdrom @var{file} 9406616b2adSStefan Weil@findex -cdrom 9415824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 9425824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 9435824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 9445824d651Sblueswir1ETEXI 9455824d651Sblueswir1 94642e5f393SMarkus ArmbrusterDEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 94742e5f393SMarkus Armbruster "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 94842e5f393SMarkus Armbruster " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 949c9b749d7SKevin Wolf " [,read-only=on|off][,auto-read-only=on|off]\n" 950c9b749d7SKevin Wolf " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n" 95142e5f393SMarkus Armbruster " [,driver specific parameters...]\n" 95242e5f393SMarkus Armbruster " configure a block backend\n", QEMU_ARCH_ALL) 953dfaca464SKevin WolfSTEXI 954dfaca464SKevin Wolf@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 955dfaca464SKevin Wolf@findex -blockdev 956dfaca464SKevin Wolf 957370e8328SKevin WolfDefine a new block driver node. Some of the options apply to all block drivers, 958370e8328SKevin Wolfother options are only accepted for a specific block driver. See below for a 959370e8328SKevin Wolflist of generic options and options for the most common block drivers. 960370e8328SKevin Wolf 961370e8328SKevin WolfOptions that expect a reference to another node (e.g. @code{file}) can be 962370e8328SKevin Wolfgiven in two ways. Either you specify the node name of an already existing node 963370e8328SKevin Wolf(file=@var{node-name}), or you define a new node inline, adding options 964370e8328SKevin Wolffor the referenced node after a dot (file.filename=@var{path},file.aio=native). 965370e8328SKevin Wolf 966370e8328SKevin WolfA block driver node created with @option{-blockdev} can be used for a guest 967370e8328SKevin Wolfdevice by specifying its node name for the @code{drive} property in a 968370e8328SKevin Wolf@option{-device} argument that defines a block device. 969dfaca464SKevin Wolf 970dfaca464SKevin Wolf@table @option 971dfaca464SKevin Wolf@item Valid options for any block driver node: 972dfaca464SKevin Wolf 973dfaca464SKevin Wolf@table @code 974dfaca464SKevin Wolf@item driver 975dfaca464SKevin WolfSpecifies the block driver to use for the given node. 976dfaca464SKevin Wolf@item node-name 977dfaca464SKevin WolfThis defines the name of the block driver node by which it will be referenced 978dfaca464SKevin Wolflater. The name must be unique, i.e. it must not match the name of a different 979dfaca464SKevin Wolfblock driver node, or (if you use @option{-drive} as well) the ID of a drive. 980dfaca464SKevin Wolf 981dfaca464SKevin WolfIf no node name is specified, it is automatically generated. The generated node 982dfaca464SKevin Wolfname is not intended to be predictable and changes between QEMU invocations. 983dfaca464SKevin WolfFor the top level, an explicit node name must be specified. 984dfaca464SKevin Wolf@item read-only 985dfaca464SKevin WolfOpen the node read-only. Guest write attempts will fail. 986c9b749d7SKevin Wolf 987c9b749d7SKevin WolfNote that some block drivers support only read-only access, either generally or 988c9b749d7SKevin Wolfin certain configurations. In this case, the default value 989c9b749d7SKevin Wolf@option{read-only=off} does not work and the option must be specified 990c9b749d7SKevin Wolfexplicitly. 991c9b749d7SKevin Wolf@item auto-read-only 992c9b749d7SKevin WolfIf @option{auto-read-only=on} is set, QEMU may fall back to read-only usage 993c9b749d7SKevin Wolfeven when @option{read-only=off} is requested, or even switch between modes as 994c9b749d7SKevin Wolfneeded, e.g. depending on whether the image file is writable or whether a 995c9b749d7SKevin Wolfwriting user is attached to the node. 996c9b749d7SKevin Wolf@item force-share 997c9b749d7SKevin WolfOverride the image locking system of QEMU by forcing the node to utilize 998c9b749d7SKevin Wolfweaker shared access for permissions where it would normally request exclusive 999c9b749d7SKevin Wolfaccess. When there is the potential for multiple instances to have the same 1000c9b749d7SKevin Wolffile open (whether this invocation of QEMU is the first or the second 1001c9b749d7SKevin Wolfinstance), both instances must permit shared access for the second instance to 1002c9b749d7SKevin Wolfsucceed at opening the file. 1003c9b749d7SKevin Wolf 1004c9b749d7SKevin WolfEnabling @option{force-share=on} requires @option{read-only=on}. 1005dfaca464SKevin Wolf@item cache.direct 1006dfaca464SKevin WolfThe host page cache can be avoided with @option{cache.direct=on}. This will 1007dfaca464SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform an 1008dfaca464SKevin Wolfinternal copy of the data. 1009dfaca464SKevin Wolf@item cache.no-flush 1010dfaca464SKevin WolfIn case you don't care about data integrity over host failures, you can use 1011dfaca464SKevin Wolf@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 1012dfaca464SKevin Wolfany data to the disk but can instead keep things in cache. If anything goes 1013dfaca464SKevin Wolfwrong, like your host losing power, the disk storage getting disconnected 1014dfaca464SKevin Wolfaccidentally, etc. your image will most probably be rendered unusable. 1015dfaca464SKevin Wolf@item discard=@var{discard} 1016dfaca464SKevin Wolf@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 1017dfaca464SKevin Wolfwhether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 1018dfaca464SKevin Wolfignored or passed to the filesystem. Some machine types may not support 1019dfaca464SKevin Wolfdiscard requests. 1020dfaca464SKevin Wolf@item detect-zeroes=@var{detect-zeroes} 1021dfaca464SKevin Wolf@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 1022dfaca464SKevin Wolfconversion of plain zero writes by the OS to driver specific optimized 1023dfaca464SKevin Wolfzero write commands. You may even choose "unmap" if @var{discard} is set 1024dfaca464SKevin Wolfto "unmap" to allow a zero write to be converted to an @code{unmap} operation. 1025dfaca464SKevin Wolf@end table 1026dfaca464SKevin Wolf 1027370e8328SKevin Wolf@item Driver-specific options for @code{file} 1028370e8328SKevin Wolf 1029370e8328SKevin WolfThis is the protocol-level block driver for accessing regular files. 1030370e8328SKevin Wolf 1031370e8328SKevin Wolf@table @code 1032370e8328SKevin Wolf@item filename 1033370e8328SKevin WolfThe path to the image file in the local filesystem 1034370e8328SKevin Wolf@item aio 1035370e8328SKevin WolfSpecifies the AIO backend (threads/native, default: threads) 10361878eaffSFam Zheng@item locking 10371878eaffSFam ZhengSpecifies whether the image file is protected with Linux OFD / POSIX locks. The 10381878eaffSFam Zhengdefault is to use the Linux Open File Descriptor API if available, otherwise no 10391878eaffSFam Zhenglock is applied. (auto/on/off, default: auto) 1040370e8328SKevin Wolf@end table 1041370e8328SKevin WolfExample: 1042370e8328SKevin Wolf@example 1043370e8328SKevin Wolf-blockdev driver=file,node-name=disk,filename=disk.img 1044370e8328SKevin Wolf@end example 1045370e8328SKevin Wolf 1046370e8328SKevin Wolf@item Driver-specific options for @code{raw} 1047370e8328SKevin Wolf 1048370e8328SKevin WolfThis is the image format block driver for raw images. It is usually 1049370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 1050370e8328SKevin Wolf 1051370e8328SKevin Wolf@table @code 1052370e8328SKevin Wolf@item file 1053370e8328SKevin WolfReference to or definition of the data source block driver node 1054370e8328SKevin Wolf(e.g. a @code{file} driver node) 1055370e8328SKevin Wolf@end table 1056370e8328SKevin WolfExample 1: 1057370e8328SKevin Wolf@example 1058370e8328SKevin Wolf-blockdev driver=file,node-name=disk_file,filename=disk.img 1059370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file=disk_file 1060370e8328SKevin Wolf@end example 1061370e8328SKevin WolfExample 2: 1062370e8328SKevin Wolf@example 1063370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 1064370e8328SKevin Wolf@end example 1065370e8328SKevin Wolf 1066370e8328SKevin Wolf@item Driver-specific options for @code{qcow2} 1067370e8328SKevin Wolf 1068370e8328SKevin WolfThis is the image format block driver for qcow2 images. It is usually 1069370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 1070370e8328SKevin Wolf 1071370e8328SKevin Wolf@table @code 1072370e8328SKevin Wolf@item file 1073370e8328SKevin WolfReference to or definition of the data source block driver node 1074370e8328SKevin Wolf(e.g. a @code{file} driver node) 1075370e8328SKevin Wolf 1076370e8328SKevin Wolf@item backing 1077370e8328SKevin WolfReference to or definition of the backing file block device (default is taken 10784f7be280SMax Reitzfrom the image file). It is allowed to pass @code{null} here in order to disable 10794f7be280SMax Reitzthe default backing file. 1080370e8328SKevin Wolf 1081370e8328SKevin Wolf@item lazy-refcounts 1082370e8328SKevin WolfWhether to enable the lazy refcounts feature (on/off; default is taken from the 1083370e8328SKevin Wolfimage file) 1084370e8328SKevin Wolf 1085370e8328SKevin Wolf@item cache-size 1086370e8328SKevin WolfThe maximum total size of the L2 table and refcount block caches in bytes 108740fb215dSLeonid Bloch(default: the sum of l2-cache-size and refcount-cache-size) 1088370e8328SKevin Wolf 1089370e8328SKevin Wolf@item l2-cache-size 1090370e8328SKevin WolfThe maximum size of the L2 table cache in bytes 109180668d0fSLeonid Bloch(default: if cache-size is not specified - 32M on Linux platforms, and 8M on 109280668d0fSLeonid Blochnon-Linux platforms; otherwise, as large as possible within the cache-size, 109380668d0fSLeonid Blochwhile permitting the requested or the minimal refcount cache size) 1094370e8328SKevin Wolf 1095370e8328SKevin Wolf@item refcount-cache-size 1096370e8328SKevin WolfThe maximum size of the refcount block cache in bytes 109740fb215dSLeonid Bloch(default: 4 times the cluster size; or if cache-size is specified, the part of 109840fb215dSLeonid Blochit which is not used for the L2 cache) 1099370e8328SKevin Wolf 1100370e8328SKevin Wolf@item cache-clean-interval 1101370e8328SKevin WolfClean unused entries in the L2 and refcount caches. The interval is in seconds. 1102e3a7b455SLeonid BlochThe default value is 600 on supporting platforms, and 0 on other platforms. 1103e3a7b455SLeonid BlochSetting it to 0 disables this feature. 1104370e8328SKevin Wolf 1105370e8328SKevin Wolf@item pass-discard-request 1106370e8328SKevin WolfWhether discard requests to the qcow2 device should be forwarded to the data 1107370e8328SKevin Wolfsource (on/off; default: on if discard=unmap is specified, off otherwise) 1108370e8328SKevin Wolf 1109370e8328SKevin Wolf@item pass-discard-snapshot 1110370e8328SKevin WolfWhether discard requests for the data source should be issued when a snapshot 1111370e8328SKevin Wolfoperation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 1112370e8328SKevin Wolfdefault: on) 1113370e8328SKevin Wolf 1114370e8328SKevin Wolf@item pass-discard-other 1115370e8328SKevin WolfWhether discard requests for the data source should be issued on other 1116370e8328SKevin Wolfoccasions where a cluster gets freed (on/off; default: off) 1117370e8328SKevin Wolf 1118370e8328SKevin Wolf@item overlap-check 1119370e8328SKevin WolfWhich overlap checks to perform for writes to the image 1120370e8328SKevin Wolf(none/constant/cached/all; default: cached). For details or finer 1121370e8328SKevin Wolfgranularity control refer to the QAPI documentation of @code{blockdev-add}. 1122370e8328SKevin Wolf@end table 1123370e8328SKevin Wolf 1124370e8328SKevin WolfExample 1: 1125370e8328SKevin Wolf@example 1126370e8328SKevin Wolf-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 1127370e8328SKevin Wolf-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 1128370e8328SKevin Wolf@end example 1129370e8328SKevin WolfExample 2: 1130370e8328SKevin Wolf@example 1131370e8328SKevin Wolf-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 1132370e8328SKevin Wolf@end example 1133370e8328SKevin Wolf 1134370e8328SKevin Wolf@item Driver-specific options for other drivers 1135370e8328SKevin WolfPlease refer to the QAPI documentation of the @code{blockdev-add} QMP command. 1136370e8328SKevin Wolf 1137dfaca464SKevin Wolf@end table 1138dfaca464SKevin Wolf 1139dfaca464SKevin WolfETEXI 114042e5f393SMarkus Armbruster 11415824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 11425824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 114392196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 1144572023f7SKevin Wolf " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 1145d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 1146fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 11472f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 11483e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 11493e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 11503e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 11513e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 11522024c1dfSBenoît Canet " [[,iops_size=is]]\n" 115376f4afb4SAlberto Garcia " [[,group=g]]\n" 1154ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 11555824d651Sblueswir1STEXI 11565824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 11576616b2adSStefan Weil@findex -drive 11585824d651Sblueswir1 1159dfaca464SKevin WolfDefine a new drive. This includes creating a block driver node (the backend) as 1160dfaca464SKevin Wolfwell as a guest device, and is mostly a shortcut for defining the corresponding 1161dfaca464SKevin Wolf@option{-blockdev} and @option{-device} options. 1162dfaca464SKevin Wolf 1163dfaca464SKevin Wolf@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 1164dfaca464SKevin Wolfaddition, it knows the following options: 11655824d651Sblueswir1 1166b3f046c2SKevin Wolf@table @option 11675824d651Sblueswir1@item file=@var{file} 11685824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 11695824d651Sblueswir1this drive. If the filename contains comma, you must double it 11705824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 11710f5314a2SRonnie Sahlberg 11720f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 11730f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 11745824d651Sblueswir1@item if=@var{interface} 11755824d651Sblueswir1This option defines on which type on interface the drive is connected. 1176ed1fcd00SCraig JellickAvailable types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 11775824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 11785824d651Sblueswir1These options define where is connected the drive by defining the bus number and 11795824d651Sblueswir1the unit id. 11805824d651Sblueswir1@item index=@var{index} 11815824d651Sblueswir1This option defines where is connected the drive by using an index in the list 11825824d651Sblueswir1of available connectors of a given interface type. 11835824d651Sblueswir1@item media=@var{media} 11845824d651Sblueswir1This option defines the type of the media: disk or cdrom. 11855824d651Sblueswir1@item snapshot=@var{snapshot} 11869d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 11879d85d557SMichael Tokarev(see @option{-snapshot}). 11885824d651Sblueswir1@item cache=@var{cache} 1189dfaca464SKevin Wolf@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 1190dfaca464SKevin Wolfand controls how the host cache is used to access block data. This is a 1191dfaca464SKevin Wolfshortcut that sets the @option{cache.direct} and @option{cache.no-flush} 1192dfaca464SKevin Wolfoptions (as in @option{-blockdev}), and additionally @option{cache.writeback}, 1193dfaca464SKevin Wolfwhich provides a default for the @option{write-cache} option of block guest 1194dfaca464SKevin Wolfdevices (as in @option{-device}). The modes correspond to the following 1195dfaca464SKevin Wolfsettings: 1196dfaca464SKevin Wolf 1197dfaca464SKevin Wolf@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 1198dfaca464SKevin Wolf@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 1199dfaca464SKevin Wolf@c and the HTML output. 1200dfaca464SKevin Wolf@example 1201dfaca464SKevin Wolf@ │ cache.writeback cache.direct cache.no-flush 1202dfaca464SKevin Wolf─────────────┼───────────────────────────────────────────────── 1203dfaca464SKevin Wolfwriteback │ on off off 1204dfaca464SKevin Wolfnone │ on on off 1205dfaca464SKevin Wolfwritethrough │ off off off 1206dfaca464SKevin Wolfdirectsync │ off on off 1207dfaca464SKevin Wolfunsafe │ on off on 1208dfaca464SKevin Wolf@end example 1209dfaca464SKevin Wolf 1210dfaca464SKevin WolfThe default mode is @option{cache=writeback}. 1211dfaca464SKevin Wolf 12125c6c3a6cSChristoph Hellwig@item aio=@var{aio} 12135c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 12145824d651Sblueswir1@item format=@var{format} 12155824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 1216d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 12175824d651Sblueswir1an untrusted format header. 1218ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 1219ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 1220ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 1221ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 1222ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 1223ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 1224fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 1225fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 1226fb0490f6SStefan Hajnoczifile sectors into the image file. 122701f9cfabSStefan Hajnoczi@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 122801f9cfabSStefan HajnocziSpecify bandwidth throttling limits in bytes per second, either for all request 122901f9cfabSStefan Hajnoczitypes or for reads or writes only. Small values can lead to timeouts or hangs 123001f9cfabSStefan Hajnocziinside the guest. A safe minimum for disks is 2 MB/s. 123101f9cfabSStefan Hajnoczi@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 123201f9cfabSStefan HajnocziSpecify bursts in bytes per second, either for all request types or for reads 123301f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 123401f9cfabSStefan Hajnoczitemporarily. 123501f9cfabSStefan Hajnoczi@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 123601f9cfabSStefan HajnocziSpecify request rate limits in requests per second, either for all request 123701f9cfabSStefan Hajnoczitypes or for reads or writes only. 123801f9cfabSStefan Hajnoczi@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 123901f9cfabSStefan HajnocziSpecify bursts in requests per second, either for all request types or for reads 124001f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 124101f9cfabSStefan Hajnoczitemporarily. 124201f9cfabSStefan Hajnoczi@item iops_size=@var{is} 124301f9cfabSStefan HajnocziLet every @var{is} bytes of a request count as a new request for iops 124401f9cfabSStefan Hajnoczithrottling purposes. Use this option to prevent guests from circumventing iops 124501f9cfabSStefan Hajnoczilimits by sending fewer but larger requests. 124601f9cfabSStefan Hajnoczi@item group=@var{g} 124701f9cfabSStefan HajnocziJoin a throttling quota group with given name @var{g}. All drives that are 124801f9cfabSStefan Hajnoczimembers of the same group are accounted for together. Use this option to 124901f9cfabSStefan Hajnocziprevent guests from circumventing throttling limits by using many small disks 125001f9cfabSStefan Hajnocziinstead of a single larger disk. 12515824d651Sblueswir1@end table 12525824d651Sblueswir1 1253dfaca464SKevin WolfBy default, the @option{cache.writeback=on} mode is used. It will report data 1254a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 1255a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 1256a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 1257a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 1258a13e5e05SKevin Wolfdata corruption. 12595824d651Sblueswir1 1260dfaca464SKevin WolfFor such guests, you should consider using @option{cache.writeback=off}. This 1261a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 1262a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 1263a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 12645824d651Sblueswir1 1265dfaca464SKevin WolfWhen using the @option{-snapshot} option, unsafe caching is always used. 1266016f5cf6SAlexander Graf 1267fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 1268fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 1269fb0490f6SStefan Hajnocziis off. 1270fb0490f6SStefan Hajnoczi 12715824d651Sblueswir1Instead of @option{-cdrom} you can use: 12725824d651Sblueswir1@example 1273664785acSThomas Huth@value{qemu_system} -drive file=file,index=2,media=cdrom 12745824d651Sblueswir1@end example 12755824d651Sblueswir1 12765824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 12775824d651Sblueswir1use: 12785824d651Sblueswir1@example 1279664785acSThomas Huth@value{qemu_system} -drive file=file,index=0,media=disk 1280664785acSThomas Huth@value{qemu_system} -drive file=file,index=1,media=disk 1281664785acSThomas Huth@value{qemu_system} -drive file=file,index=2,media=disk 1282664785acSThomas Huth@value{qemu_system} -drive file=file,index=3,media=disk 12835824d651Sblueswir1@end example 12845824d651Sblueswir1 1285587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 1286587ed6beSCorey Bryant@example 1287664785acSThomas Huth@value{qemu_system} \ 1288664785acSThomas Huth -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 1289664785acSThomas Huth -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 1290587ed6beSCorey Bryant -drive file=/dev/fdset/2,index=0,media=disk 1291587ed6beSCorey Bryant@end example 1292587ed6beSCorey Bryant 12935824d651Sblueswir1You can connect a CDROM to the slave of ide0: 12945824d651Sblueswir1@example 1295664785acSThomas Huth@value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom 12965824d651Sblueswir1@end example 12975824d651Sblueswir1 12985824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 12995824d651Sblueswir1@example 1300664785acSThomas Huth@value{qemu_system_x86} -drive if=ide,index=1,media=cdrom 13015824d651Sblueswir1@end example 13025824d651Sblueswir1 13035824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 13045824d651Sblueswir1@example 1305664785acSThomas Huth@value{qemu_system_x86} -drive file=file,index=0,if=floppy 1306664785acSThomas Huth@value{qemu_system_x86} -drive file=file,index=1,if=floppy 13075824d651Sblueswir1@end example 13085824d651Sblueswir1 13095824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 13105824d651Sblueswir1incremented: 13115824d651Sblueswir1@example 1312664785acSThomas Huth@value{qemu_system_x86} -drive file=a -drive file=b" 13135824d651Sblueswir1@end example 13145824d651Sblueswir1is interpreted like: 13155824d651Sblueswir1@example 1316664785acSThomas Huth@value{qemu_system_x86} -hda a -hdb b 13175824d651Sblueswir1@end example 13185824d651Sblueswir1ETEXI 13195824d651Sblueswir1 13205824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 1321ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 1322ad96090aSBlue Swirl QEMU_ARCH_ALL) 13235824d651Sblueswir1STEXI 13244e257e5eSKevin Wolf@item -mtdblock @var{file} 13256616b2adSStefan Weil@findex -mtdblock 13264e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 13275824d651Sblueswir1ETEXI 13285824d651Sblueswir1 13295824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 1330ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 13315824d651Sblueswir1STEXI 13324e257e5eSKevin Wolf@item -sd @var{file} 13336616b2adSStefan Weil@findex -sd 13344e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 13355824d651Sblueswir1ETEXI 13365824d651Sblueswir1 13375824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 1338ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 13395824d651Sblueswir1STEXI 13404e257e5eSKevin Wolf@item -pflash @var{file} 13416616b2adSStefan Weil@findex -pflash 13424e257e5eSKevin WolfUse @var{file} as a parallel flash image. 13435824d651Sblueswir1ETEXI 13445824d651Sblueswir1 13455824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 1346ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 1347ad96090aSBlue Swirl QEMU_ARCH_ALL) 13485824d651Sblueswir1STEXI 13495824d651Sblueswir1@item -snapshot 13506616b2adSStefan Weil@findex -snapshot 13515824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 13525824d651Sblueswir1the raw disk image you use is not written back. You can however force 13535824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 13545824d651Sblueswir1ETEXI 13555824d651Sblueswir1 135674db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 1357b44a6b09SGreg Kurz "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n" 1358b44a6b09SGreg Kurz " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n" 1359b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1360b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1361b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1362b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1363b44a6b09SGreg Kurz " [[,throttling.iops-size=is]]\n" 1364b44a6b09SGreg Kurz "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n" 1365b44a6b09SGreg Kurz "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n" 1366b44a6b09SGreg Kurz "-fsdev synth,id=id\n", 136774db920cSGautham R Shenoy QEMU_ARCH_ALL) 136874db920cSGautham R Shenoy 136974db920cSGautham R ShenoySTEXI 137074db920cSGautham R Shenoy 1371b44a6b09SGreg Kurz@item -fsdev local,id=@var{id},path=@var{path},security_model=@var{security_model} [,writeout=@var{writeout}][,readonly][,fmode=@var{fmode}][,dmode=@var{dmode}] [,throttling.@var{option}=@var{value}[,throttling.@var{option}=@var{value}[,...]]] 1372b44a6b09SGreg Kurz@itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly] 1373b44a6b09SGreg Kurz@itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly] 1374b44a6b09SGreg Kurz@itemx -fsdev synth,id=@var{id}[,readonly] 137574db920cSGautham R Shenoy@findex -fsdev 13767c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 13777c92a3d2SAneesh Kumar K.V@table @option 1378b44a6b09SGreg Kurz@item local 1379b44a6b09SGreg KurzAccesses to the filesystem are done by QEMU. 1380b44a6b09SGreg Kurz@item proxy 1381b44a6b09SGreg KurzAccesses to the filesystem are done by virtfs-proxy-helper(1). 1382b44a6b09SGreg Kurz@item synth 1383b44a6b09SGreg KurzSynthetic filesystem, only used by QTests. 13847c92a3d2SAneesh Kumar K.V@item id=@var{id} 1385b44a6b09SGreg KurzSpecifies identifier for this device. 13867c92a3d2SAneesh Kumar K.V@item path=@var{path} 13877c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 13887c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 13897c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 13907c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 13912c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 13927c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1393b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 13942c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 13957c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 13962c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 13972c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 13987c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 13997c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1400d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 140193aee84fSGreg Kurzonly for local fsdriver. Other fsdrivers (like proxy) don't take 1402d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 14037c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 14047c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 14057c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 14067c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 14077c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 14082c74c2cbSM. Mohan Kumar@item readonly 14092c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 14102c74c2cbSM. Mohan Kumarread-write access is given. 141184a87cc4SM. Mohan Kumar@item socket=@var{socket} 141284a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 1413b44a6b09SGreg Kurzwith virtfs-proxy-helper(1). 1414f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 1415f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 1416b44a6b09SGreg Kurzcommunicating with virtfs-proxy-helper(1). Usually a helper like libvirt 1417b44a6b09SGreg Kurzwill create socketpair and pass one of the fds as sock_fd. 1418b96feb2cSTobias Schramm@item fmode=@var{fmode} 1419b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1420b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1421b96feb2cSTobias Schramm@item dmode=@var{dmode} 1422b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1423b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 1424b44a6b09SGreg Kurz@item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w} 1425b44a6b09SGreg KurzSpecify bandwidth throttling limits in bytes per second, either for all request 1426b44a6b09SGreg Kurztypes or for reads or writes only. 1427b44a6b09SGreg Kurz@item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm} 1428b44a6b09SGreg KurzSpecify bursts in bytes per second, either for all request types or for reads 1429b44a6b09SGreg Kurzor writes only. Bursts allow the guest I/O to spike above the limit 1430b44a6b09SGreg Kurztemporarily. 1431b44a6b09SGreg Kurz@item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w} 1432b44a6b09SGreg KurzSpecify request rate limits in requests per second, either for all request 1433b44a6b09SGreg Kurztypes or for reads or writes only. 1434b44a6b09SGreg Kurz@item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm} 1435b44a6b09SGreg KurzSpecify bursts in requests per second, either for all request types or for reads 1436b44a6b09SGreg Kurzor writes only. Bursts allow the guest I/O to spike above the limit temporarily. 1437b44a6b09SGreg Kurz@item throttling.iops-size=@var{is} 1438b44a6b09SGreg KurzLet every @var{is} bytes of a request count as a new request for iops 1439b44a6b09SGreg Kurzthrottling purposes. 144074db920cSGautham R Shenoy@end table 14417c92a3d2SAneesh Kumar K.V 1442b44a6b09SGreg Kurz-fsdev option is used along with -device driver "virtio-9p-...". 1443b44a6b09SGreg Kurz@item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag} 1444b44a6b09SGreg KurzOptions for virtio-9p-... driver are: 14457c92a3d2SAneesh Kumar K.V@table @option 1446b44a6b09SGreg Kurz@item @var{type} 1447b44a6b09SGreg KurzSpecifies the variant to be used. Supported values are "pci", "ccw" or "device", 1448b44a6b09SGreg Kurzdepending on the machine type. 14497c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 1450b44a6b09SGreg KurzSpecifies the id value specified along with -fsdev option. 14517c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 1452b44a6b09SGreg KurzSpecifies the tag name to be used by the guest to mount this export point. 14537c92a3d2SAneesh Kumar K.V@end table 14547c92a3d2SAneesh Kumar K.V 145574db920cSGautham R ShenoyETEXI 145674db920cSGautham R Shenoy 14573d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 1458b44a6b09SGreg Kurz "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n" 14591a6ed33cSAntonios Motakis " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n" 1460b44a6b09SGreg Kurz "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n" 1461b44a6b09SGreg Kurz "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n" 1462b44a6b09SGreg Kurz "-virtfs synth,mount_tag=tag[,id=id][,readonly]\n", 14633d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 14643d54abc7SGautham R Shenoy 14653d54abc7SGautham R ShenoySTEXI 14663d54abc7SGautham R Shenoy 14671a6ed33cSAntonios Motakis@item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}][,multidevs=@var{multidevs}] 1468b44a6b09SGreg Kurz@itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 1469b44a6b09SGreg Kurz@itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 1470b44a6b09SGreg Kurz@itemx -virtfs synth,mount_tag=@var{mount_tag} 14713d54abc7SGautham R Shenoy@findex -virtfs 14723d54abc7SGautham R Shenoy 1473b44a6b09SGreg KurzDefine a new filesystem device and expose it to the guest using a virtio-9p-device. The general form of a Virtual File system pass-through options are: 14747c92a3d2SAneesh Kumar K.V@table @option 1475b44a6b09SGreg Kurz@item local 1476b44a6b09SGreg KurzAccesses to the filesystem are done by QEMU. 1477b44a6b09SGreg Kurz@item proxy 1478b44a6b09SGreg KurzAccesses to the filesystem are done by virtfs-proxy-helper(1). 1479b44a6b09SGreg Kurz@item synth 1480b44a6b09SGreg KurzSynthetic filesystem, only used by QTests. 14817c92a3d2SAneesh Kumar K.V@item id=@var{id} 1482b44a6b09SGreg KurzSpecifies identifier for the filesystem device 14837c92a3d2SAneesh Kumar K.V@item path=@var{path} 14847c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 14857c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 14867c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 14877c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 14882c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 14897c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1490b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 14912c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 14927c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 14932c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 14942c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 14957c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 14967c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1497d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 149893aee84fSGreg Kurzfor local fsdriver. Other fsdrivers (like proxy) don't take security 1499d9b36a6eSM. Mohan Kumarmodel as a parameter. 15007c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 15017c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 15027c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 15037c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 15047c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 15052c74c2cbSM. Mohan Kumar@item readonly 15062c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 15072c74c2cbSM. Mohan Kumarread-write access is given. 150884a87cc4SM. Mohan Kumar@item socket=@var{socket} 150984a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 1510b44a6b09SGreg Kurzcommunicating with virtfs-proxy-helper(1). Usually a helper like libvirt 1511b44a6b09SGreg Kurzwill create socketpair and pass one of the fds as sock_fd. 1512f67e3ffdSM. Mohan Kumar@item sock_fd 1513f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 1514b44a6b09SGreg Kurzdescriptor for interfacing with virtfs-proxy-helper(1). 1515b96feb2cSTobias Schramm@item fmode=@var{fmode} 1516b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1517b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1518b96feb2cSTobias Schramm@item dmode=@var{dmode} 1519b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1520b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 1521b44a6b09SGreg Kurz@item mount_tag=@var{mount_tag} 1522b44a6b09SGreg KurzSpecifies the tag name to be used by the guest to mount this export point. 15231a6ed33cSAntonios Motakis@item multidevs=@var{multidevs} 15241a6ed33cSAntonios MotakisSpecifies how to deal with multiple devices being shared with a 9p export. 15251a6ed33cSAntonios MotakisSupported behaviours are either "remap", "forbid" or "warn". The latter is 15261a6ed33cSAntonios Motakisthe default behaviour on which virtfs 9p expects only one device to be 15271a6ed33cSAntonios Motakisshared with the same export, and if more than one device is shared and 15281a6ed33cSAntonios Motakisaccessed via the same 9p export then only a warning message is logged 15291a6ed33cSAntonios Motakis(once) by qemu on host side. In order to avoid file ID collisions on guest 15301a6ed33cSAntonios Motakisyou should either create a separate virtfs export for each device to be 15311a6ed33cSAntonios Motakisshared with guests (recommended way) or you might use "remap" instead which 15321a6ed33cSAntonios Motakisallows you to share multiple devices with only one export instead, which is 15331a6ed33cSAntonios Motakisachieved by remapping the original inode numbers from host to guest in a 15341a6ed33cSAntonios Motakisway that would prevent such collisions. Remapping inodes in such use cases 15351a6ed33cSAntonios Motakisis required because the original device IDs from host are never passed and 15361a6ed33cSAntonios Motakisexposed on guest. Instead all files of an export shared with virtfs always 15371a6ed33cSAntonios Motakisshare the same device id on guest. So two files with identical inode 15381a6ed33cSAntonios Motakisnumbers but from actually different devices on host would otherwise cause a 15391a6ed33cSAntonios Motakisfile ID collision and hence potential misbehaviours on guest. "forbid" on 15401a6ed33cSAntonios Motakisthe other hand assumes like "warn" that only one device is shared by the 15411a6ed33cSAntonios Motakissame export, however it will not only log a warning message but also 15421a6ed33cSAntonios Motakisdeny access to additional devices on guest. Note though that "forbid" does 15431a6ed33cSAntonios Motakiscurrently not block all possible file access operations (e.g. readdir() 15441a6ed33cSAntonios Motakiswould still return entries from other devices). 15453d54abc7SGautham R Shenoy@end table 15463d54abc7SGautham R ShenoyETEXI 15473d54abc7SGautham R Shenoy 154861d70487SMarkus ArmbrusterDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 154961d70487SMarkus Armbruster "-iscsi [user=user][,password=password]\n" 155061d70487SMarkus Armbruster " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 155161d70487SMarkus Armbruster " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 155261d70487SMarkus Armbruster " [,timeout=timeout]\n" 155361d70487SMarkus Armbruster " iSCSI session parameters\n", QEMU_ARCH_ALL) 155461d70487SMarkus Armbruster 15555824d651Sblueswir1STEXI 155644743148SMarkus Armbruster@item -iscsi 155744743148SMarkus Armbruster@findex -iscsi 155844743148SMarkus ArmbrusterConfigure iSCSI session parameters. 155944743148SMarkus ArmbrusterETEXI 156044743148SMarkus Armbruster 156144743148SMarkus ArmbrusterSTEXI 15625824d651Sblueswir1@end table 15635824d651Sblueswir1ETEXI 15645824d651Sblueswir1DEFHEADING() 15655824d651Sblueswir1 1566de6b4f90SMarkus ArmbrusterDEFHEADING(USB options:) 156710adb8beSMarkus ArmbrusterSTEXI 156810adb8beSMarkus Armbruster@table @option 156910adb8beSMarkus ArmbrusterETEXI 157010adb8beSMarkus Armbruster 157110adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 157273f46fefSStefan Hajnoczi "-usb enable on-board USB host controller (if not enabled by default)\n", 157310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 157410adb8beSMarkus ArmbrusterSTEXI 157510adb8beSMarkus Armbruster@item -usb 157610adb8beSMarkus Armbruster@findex -usb 157773f46fefSStefan HajnocziEnable USB emulation on machine types with an on-board USB host controller (if 157873f46fefSStefan Hajnoczinot enabled by default). Note that on-board USB host controllers may not 157973f46fefSStefan Hajnoczisupport USB 3.0. In this case @option{-device qemu-xhci} can be used instead 158073f46fefSStefan Hajnoczion machines with PCI. 158110adb8beSMarkus ArmbrusterETEXI 158210adb8beSMarkus Armbruster 158310adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 158410adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 158510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 158610adb8beSMarkus ArmbrusterSTEXI 158710adb8beSMarkus Armbruster 158810adb8beSMarkus Armbruster@item -usbdevice @var{devname} 158910adb8beSMarkus Armbruster@findex -usbdevice 1590a358a3afSThomas HuthAdd the USB device @var{devname}. Note that this option is deprecated, 1591a358a3afSThomas Huthplease use @code{-device usb-...} instead. @xref{usb_devices}. 159210adb8beSMarkus Armbruster 159310adb8beSMarkus Armbruster@table @option 159410adb8beSMarkus Armbruster 159510adb8beSMarkus Armbruster@item mouse 159610adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 159710adb8beSMarkus Armbruster 159810adb8beSMarkus Armbruster@item tablet 159910adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 160010adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 160110adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 160210adb8beSMarkus Armbruster 160310adb8beSMarkus Armbruster@item braille 160410adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 160510adb8beSMarkus Armbrusteror fake device. 160610adb8beSMarkus Armbruster 160710adb8beSMarkus Armbruster@end table 160810adb8beSMarkus ArmbrusterETEXI 160910adb8beSMarkus Armbruster 161010adb8beSMarkus ArmbrusterSTEXI 161110adb8beSMarkus Armbruster@end table 161210adb8beSMarkus ArmbrusterETEXI 161310adb8beSMarkus ArmbrusterDEFHEADING() 161410adb8beSMarkus Armbruster 1615de6b4f90SMarkus ArmbrusterDEFHEADING(Display options:) 16165824d651Sblueswir1STEXI 16175824d651Sblueswir1@table @option 16185824d651Sblueswir1ETEXI 16195824d651Sblueswir1 16201472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 162188b40c68SThomas Huth#if defined(CONFIG_SPICE) 1622d8aec9d9SMarc-André Lureau "-display spice-app[,gl=on|off]\n" 162388b40c68SThomas Huth#endif 162488b40c68SThomas Huth#if defined(CONFIG_SDL) 162588b40c68SThomas Huth "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n" 16264867e47cSElie Tournier " [,window_close=on|off][,gl=on|core|es|off]\n" 162788b40c68SThomas Huth#endif 162888b40c68SThomas Huth#if defined(CONFIG_GTK) 1629f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 163088b40c68SThomas Huth#endif 163188b40c68SThomas Huth#if defined(CONFIG_VNC) 1632f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 163388b40c68SThomas Huth#endif 163488b40c68SThomas Huth#if defined(CONFIG_CURSES) 16352f8b7cd5SSamuel Thibault "-display curses[,charset=<encoding>]\n" 163688b40c68SThomas Huth#endif 163788b40c68SThomas Huth#if defined(CONFIG_OPENGL) 163888b40c68SThomas Huth "-display egl-headless[,rendernode=<file>]\n" 163988b40c68SThomas Huth#endif 1640144aaa99SErik Skultety "-display none\n" 164188b40c68SThomas Huth " select display backend type\n" 1642f04ec5afSRobert Ho " The default display is equivalent to\n " 1643f04ec5afSRobert Ho#if defined(CONFIG_GTK) 164488b40c68SThomas Huth "\"-display gtk\"\n" 1645f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 164688b40c68SThomas Huth "\"-display sdl\"\n" 1647f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 164888b40c68SThomas Huth "\"-display cocoa\"\n" 1649f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 165088b40c68SThomas Huth "\"-vnc localhost:0,to=99,id=default\"\n" 1651f04ec5afSRobert Ho#else 165288b40c68SThomas Huth "\"-display none\"\n" 1653f04ec5afSRobert Ho#endif 1654f04ec5afSRobert Ho , QEMU_ARCH_ALL) 16551472a95bSJes SorensenSTEXI 16561472a95bSJes Sorensen@item -display @var{type} 16571472a95bSJes Sorensen@findex -display 16581472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 16591472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 16601472a95bSJes Sorensen@table @option 16611472a95bSJes Sorensen@item sdl 16621472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 16631472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 16641472a95bSJes Sorensen@item curses 16651472a95bSJes SorensenDisplay video output via curses. For graphics device models which 16661472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 16671472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 16681472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 16691472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 16702f8b7cd5SSamuel ThibaultThe font charset used by the guest can be specified with the 16712f8b7cd5SSamuel Thibault@code{charset} option, for example @code{charset=CP850} for IBM CP850 16722f8b7cd5SSamuel Thibaultencoding. The default is @code{CP437}. 16734171d32eSJes Sorensen@item none 16744171d32eSJes SorensenDo not display video output. The guest will still see an emulated 16754171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 16764171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 16774171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 16784171d32eSJes Sorensenthe destination of the serial and parallel port data. 1679881249c7SJan Kiszka@item gtk 1680881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 1681881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 1682881249c7SJan Kiszkaruntime. 16833264ff12SJes Sorensen@item vnc 16843264ff12SJes SorensenStart a VNC server on display <arg> 1685144aaa99SErik Skultety@item egl-headless 1686144aaa99SErik SkultetyOffload all OpenGL operations to a local DRI device. For any graphical display, 1687144aaa99SErik Skultetythis display needs to be paired with either VNC or SPICE displays. 1688d8aec9d9SMarc-André Lureau@item spice-app 1689d8aec9d9SMarc-André LureauStart QEMU as a Spice server and launch the default Spice client 1690d8aec9d9SMarc-André Lureauapplication. The Spice server will redirect the serial consoles and 1691d8aec9d9SMarc-André LureauQEMU monitors. (Since 4.0) 16921472a95bSJes Sorensen@end table 16931472a95bSJes SorensenETEXI 16941472a95bSJes Sorensen 16955824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 1696ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1697ad96090aSBlue Swirl QEMU_ARCH_ALL) 16985824d651Sblueswir1STEXI 16995824d651Sblueswir1@item -nographic 17006616b2adSStefan Weil@findex -nographic 1701dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1702dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1703dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1704dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1705dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1706dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1707dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1708dc0a3e44SColin Lordswitching between the console and monitor. 17095824d651Sblueswir1ETEXI 17105824d651Sblueswir1 17115824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1712f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1713ad96090aSBlue Swirl QEMU_ARCH_ALL) 17145824d651Sblueswir1STEXI 17155824d651Sblueswir1@item -curses 1716b8f490ebSMarkus Armbruster@findex -curses 1717dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1718dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1719dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1720dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1721dc0a3e44SColin Lordmode. 17225824d651Sblueswir1ETEXI 17235824d651Sblueswir1 17245824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1725ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1726ad96090aSBlue Swirl QEMU_ARCH_ALL) 17275824d651Sblueswir1STEXI 17285824d651Sblueswir1@item -alt-grab 17296616b2adSStefan Weil@findex -alt-grab 1730de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1731de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 17325824d651Sblueswir1ETEXI 17335824d651Sblueswir1 17340ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1735ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1736ad96090aSBlue Swirl QEMU_ARCH_ALL) 17370ca9f8a4SDustin KirklandSTEXI 17380ca9f8a4SDustin Kirkland@item -ctrl-grab 17396616b2adSStefan Weil@findex -ctrl-grab 1740de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1741de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 17420ca9f8a4SDustin KirklandETEXI 17430ca9f8a4SDustin Kirkland 17445824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1745ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 17465824d651Sblueswir1STEXI 17475824d651Sblueswir1@item -no-quit 17486616b2adSStefan Weil@findex -no-quit 17495824d651Sblueswir1Disable SDL window close capability. 17505824d651Sblueswir1ETEXI 17515824d651Sblueswir1 17525824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1753f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 17545824d651Sblueswir1STEXI 17555824d651Sblueswir1@item -sdl 17566616b2adSStefan Weil@findex -sdl 17575824d651Sblueswir1Enable SDL. 17585824d651Sblueswir1ETEXI 17595824d651Sblueswir1 176029b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 176127af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 176227af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 176327af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1764fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 176527af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 176627af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 176727af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 176827af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 176927af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 177027af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 177127af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 177227af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 17735ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 17745ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 17757b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 177627af7788SYonit Halperin " enable spice\n" 177727af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 177827af7788SYonit Halperin QEMU_ARCH_ALL) 177929b0040bSGerd HoffmannSTEXI 178029b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 178129b0040bSGerd Hoffmann@findex -spice 178229b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 178329b0040bSGerd Hoffmann 178429b0040bSGerd Hoffmann@table @option 178529b0040bSGerd Hoffmann 178629b0040bSGerd Hoffmann@item port=<nr> 1787c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 178829b0040bSGerd Hoffmann 1789333b0eebSGerd Hoffmann@item addr=<addr> 1790333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1791333b0eebSGerd Hoffmann 1792333b0eebSGerd Hoffmann@item ipv4 1793f9cfd655SMarkus Armbruster@itemx ipv6 1794f9cfd655SMarkus Armbruster@itemx unix 1795333b0eebSGerd HoffmannForce using the specified IP version. 1796333b0eebSGerd Hoffmann 179729b0040bSGerd Hoffmann@item password=<secret> 179829b0040bSGerd HoffmannSet the password you need to authenticate. 179929b0040bSGerd Hoffmann 180048b3ed0aSMarc-André Lureau@item sasl 180148b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 180248b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 180348b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 180448b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 180548b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 180648b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 180748b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 180848b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 180948b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 181048b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 181148b3ed0aSMarc-André Lureaucredentials. 181248b3ed0aSMarc-André Lureau 181329b0040bSGerd Hoffmann@item disable-ticketing 181429b0040bSGerd HoffmannAllow client connects without authentication. 181529b0040bSGerd Hoffmann 1816d4970b07SHans de Goede@item disable-copy-paste 1817d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1818d4970b07SHans de Goede 18195ad24e5fSHans de Goede@item disable-agent-file-xfer 18205ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 18215ad24e5fSHans de Goede 1822c448e855SGerd Hoffmann@item tls-port=<nr> 1823c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1824c448e855SGerd Hoffmann 1825c448e855SGerd Hoffmann@item x509-dir=<dir> 1826c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1827c448e855SGerd Hoffmann 1828c448e855SGerd Hoffmann@item x509-key-file=<file> 1829f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1830f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1831f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1832f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1833c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1834c448e855SGerd Hoffmann 1835c448e855SGerd Hoffmann@item tls-ciphers=<list> 1836c448e855SGerd HoffmannSpecify which ciphers to use. 1837c448e855SGerd Hoffmann 1838d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1839f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 184017b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 184117b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 184217b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 184317b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 184417b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 184517b6dea0SGerd Hoffmann 18469f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 18479f04e09eSYonit HalperinConfigure image compression (lossless). 18489f04e09eSYonit HalperinDefault is auto_glz. 18499f04e09eSYonit Halperin 18509f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1851f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 18529f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 18539f04e09eSYonit HalperinDefault is auto. 18549f04e09eSYonit Halperin 185584a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 185693ca519eSLi ZhijianConfigure video stream detection. Default is off. 185784a23f25SGerd Hoffmann 185884a23f25SGerd Hoffmann@item agent-mouse=[on|off] 185984a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 186084a23f25SGerd Hoffmann 186184a23f25SGerd Hoffmann@item playback-compression=[on|off] 186284a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 186384a23f25SGerd Hoffmann 18648c957053SYonit Halperin@item seamless-migration=[on|off] 18658c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 18668c957053SYonit Halperin 1867474114b7SGerd Hoffmann@item gl=[on|off] 1868474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1869474114b7SGerd Hoffmann 18707b525508SMarc-André Lureau@item rendernode=<file> 18717b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 18727b525508SMarc-André Lureauthe first available. (Since 2.9) 18737b525508SMarc-André Lureau 187429b0040bSGerd Hoffmann@end table 187529b0040bSGerd HoffmannETEXI 187629b0040bSGerd Hoffmann 18775824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1878ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1879ad96090aSBlue Swirl QEMU_ARCH_ALL) 18805824d651Sblueswir1STEXI 18815824d651Sblueswir1@item -portrait 18826616b2adSStefan Weil@findex -portrait 18835824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 18845824d651Sblueswir1ETEXI 18855824d651Sblueswir1 18869312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 18879312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 18889312805dSVasily Khoruzhick QEMU_ARCH_ALL) 18899312805dSVasily KhoruzhickSTEXI 18906265c43bSMarkus Armbruster@item -rotate @var{deg} 18919312805dSVasily Khoruzhick@findex -rotate 18929312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 18939312805dSVasily KhoruzhickETEXI 18949312805dSVasily Khoruzhick 18955824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1896a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1897ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 18985824d651Sblueswir1STEXI 1899e4558dcaSmalc@item -vga @var{type} 19006616b2adSStefan Weil@findex -vga 19015824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1902b3f046c2SKevin Wolf@table @option 19035824d651Sblueswir1@item cirrus 19045824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 19055824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 19065824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 190741eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 19085824d651Sblueswir1@item std 19095824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 19105824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 19115824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 191241eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 19135824d651Sblueswir1@item vmware 19145824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 19155824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 19165824d651Sblueswir1card. 1917a19cbfb3SGerd Hoffmann@item qxl 1918a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1919a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1920a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 192133632788SMark Cave-Ayland@item tcx 192233632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 192333632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 192433632788SMark Cave-Aylandfixed resolution of 1024x768. 192533632788SMark Cave-Ayland@item cg3 192633632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 192733632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 192833632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1929a94f0c5cSGerd Hoffmann@item virtio 1930a94f0c5cSGerd HoffmannVirtio VGA card. 19315824d651Sblueswir1@item none 19325824d651Sblueswir1Disable VGA card. 19335824d651Sblueswir1@end table 19345824d651Sblueswir1ETEXI 19355824d651Sblueswir1 19365824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1937ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 19385824d651Sblueswir1STEXI 19395824d651Sblueswir1@item -full-screen 19406616b2adSStefan Weil@findex -full-screen 19415824d651Sblueswir1Start in full screen. 19425824d651Sblueswir1ETEXI 19435824d651Sblueswir1 19445824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1945ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 19468ac919a0SLaurent Vivier QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K) 19475824d651Sblueswir1STEXI 194895d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 19496616b2adSStefan Weil@findex -g 195095d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 19515824d651Sblueswir1ETEXI 19525824d651Sblueswir1 19535824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1954f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 19555824d651Sblueswir1STEXI 19565824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 19576616b2adSStefan Weil@findex -vnc 1958dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1959dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1960dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1961dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1962dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1963a358a3afSThomas Huth(option @option{-device usb-tablet}). When using the VNC display, you 1964dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1965dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 19665824d651Sblueswir1 1967b3f046c2SKevin Wolf@table @option 19685824d651Sblueswir1 196999a9a52aSRobert Ho@item to=@var{L} 197099a9a52aSRobert Ho 197199a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 197299a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 197399a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 197499a9a52aSRobert Hoapplication. By default, to=0. 197599a9a52aSRobert Ho 19765824d651Sblueswir1@item @var{host}:@var{d} 19775824d651Sblueswir1 19785824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 19795824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 19805824d651Sblueswir1be omitted in which case the server will accept connections from any host. 19815824d651Sblueswir1 19824e257e5eSKevin Wolf@item unix:@var{path} 19835824d651Sblueswir1 19845824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 19855824d651Sblueswir1location of a unix socket to listen for connections on. 19865824d651Sblueswir1 19875824d651Sblueswir1@item none 19885824d651Sblueswir1 19895824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 19905824d651Sblueswir1can be used to later start the VNC server. 19915824d651Sblueswir1 19925824d651Sblueswir1@end table 19935824d651Sblueswir1 19945824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 19955824d651Sblueswir1separated by commas. Valid options are 19965824d651Sblueswir1 1997b3f046c2SKevin Wolf@table @option 19985824d651Sblueswir1 19995824d651Sblueswir1@item reverse 20005824d651Sblueswir1 20015824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 20025824d651Sblueswir1client is specified by the @var{display}. For reverse network 20035824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 20045824d651Sblueswir1is a TCP port number, not a display number. 20055824d651Sblueswir1 20067536ee4bSTim Hardeck@item websocket 20077536ee4bSTim Hardeck 20087536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 2009275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 2010275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 2011275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 2012275e0d61SDaniel P. Berrange 2013275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 2014275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 2015275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 2016275e0d61SDaniel P. Berrange 20173e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 20183e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 20193e305e4aSDaniel P. Berrangerequires encrypted client connections. 20207536ee4bSTim Hardeck 20215824d651Sblueswir1@item password 20225824d651Sblueswir1 20235824d651Sblueswir1Require that password based authentication is used for client connections. 202486ee5bc3SMichal Novotny 202586ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 202686ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 202786ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 202886ee5bc3SMichal Novotny"vnc" or "spice". 202986ee5bc3SMichal Novotny 203086ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 203186ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 203286ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 203386ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 203486ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 203586ee5bc3SMichal Novotnydate and time). 203686ee5bc3SMichal Novotny 203786ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 203886ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 20395824d651Sblueswir1 20403e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 20413e305e4aSDaniel P. Berrange 20423e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 20433e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 20443e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 20453e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 20463e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 20473e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 20483e305e4aSDaniel P. Berrange 204955cf09a0SDaniel P. Berrange@item tls-authz=@var{ID} 205055cf09a0SDaniel P. Berrange 205155cf09a0SDaniel P. BerrangeProvides the ID of the QAuthZ authorization object against which 205255cf09a0SDaniel P. Berrangethe client's x509 distinguished name will validated. This object is 205355cf09a0SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the 205455cf09a0SDaniel P. Berrangefly while the VNC server is active. If missing, it will default 205555cf09a0SDaniel P. Berrangeto denying access. 205655cf09a0SDaniel P. Berrange 20575824d651Sblueswir1@item sasl 20585824d651Sblueswir1 20595824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 20605824d651Sblueswir1The exact choice of authentication method used is controlled from the 20615824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 20625824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 20635824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 20645824d651Sblueswir1to make it search alternate locations for the service config. 20655824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 20665824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 20675824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 20685824d651Sblueswir1ensures a data encryption preventing compromise of authentication 20695824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 20705824d651Sblueswir1SASL authentication. 20715824d651Sblueswir1 207255cf09a0SDaniel P. Berrange@item sasl-authz=@var{ID} 207355cf09a0SDaniel P. Berrange 207455cf09a0SDaniel P. BerrangeProvides the ID of the QAuthZ authorization object against which 207555cf09a0SDaniel P. Berrangethe client's SASL username will validated. This object is 207655cf09a0SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the 207755cf09a0SDaniel P. Berrangefly while the VNC server is active. If missing, it will default 207855cf09a0SDaniel P. Berrangeto denying access. 207955cf09a0SDaniel P. Berrange 20805824d651Sblueswir1@item acl 20815824d651Sblueswir1 208255cf09a0SDaniel P. BerrangeLegacy method for enabling authorization of clients against the 208355cf09a0SDaniel P. Berrangex509 distinguished name and SASL username. It results in the creation 208455cf09a0SDaniel P. Berrangeof two @code{authz-list} objects with IDs of @code{vnc.username} and 208555cf09a0SDaniel P. Berrange@code{vnc.x509dname}. The rules for these objects must be configured 208655cf09a0SDaniel P. Berrangewith the HMP ACL commands. 208755cf09a0SDaniel P. Berrange 208855cf09a0SDaniel P. BerrangeThis option is deprecated and should no longer be used. The new 208955cf09a0SDaniel P. Berrange@option{sasl-authz} and @option{tls-authz} options are a 209055cf09a0SDaniel P. Berrangereplacement. 20915824d651Sblueswir1 20926f9c78c1SCorentin Chary@item lossy 20936f9c78c1SCorentin Chary 20946f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 20956f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 20966f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 20976f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 20986f9c78c1SCorentin Chary 209980e0c8c3SCorentin Chary@item non-adaptive 210080e0c8c3SCorentin Chary 210180e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 210280e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 210380e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 210461cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 21059d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 210680e0c8c3SCorentin Charylike Tight. 210780e0c8c3SCorentin Chary 21088cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 21098cf36489SGerd Hoffmann 21108cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 21118cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 21128cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 21138cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 21148cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 21158cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 21168cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 21178cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 21188cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 2119b65ee4faSStefan Weilspec but is traditional QEMU behavior. 21208cf36489SGerd Hoffmann 2121c5ce8333SGerd Hoffmann@item key-delay-ms 2122c5ce8333SGerd Hoffmann 2123c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 2124d3b0db6dSAlexander GrafDefault is 10. Keyboards are low-bandwidth devices, so this slowdown 2125c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 2126c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 2127c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 2128c5ce8333SGerd Hoffmann 2129f0b9f36dSKővágó, Zoltán@item audiodev=@var{audiodev} 2130f0b9f36dSKővágó, Zoltán 2131f0b9f36dSKővágó, ZoltánUse the specified @var{audiodev} when the VNC client requests audio 2132f0b9f36dSKővágó, Zoltántransmission. When not using an -audiodev argument, this option must 2133f0b9f36dSKővágó, Zoltánbe omitted, otherwise is must be present and specify a valid audiodev. 2134f0b9f36dSKővágó, Zoltán 21355824d651Sblueswir1@end table 21365824d651Sblueswir1ETEXI 21375824d651Sblueswir1 21385824d651Sblueswir1STEXI 21395824d651Sblueswir1@end table 21405824d651Sblueswir1ETEXI 2141a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 21425824d651Sblueswir1 2143de6b4f90SMarkus ArmbrusterARCHHEADING(i386 target only:, QEMU_ARCH_I386) 21445824d651Sblueswir1STEXI 21455824d651Sblueswir1@table @option 21465824d651Sblueswir1ETEXI 21475824d651Sblueswir1 21485824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 2149ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 2150ad96090aSBlue Swirl QEMU_ARCH_I386) 21515824d651Sblueswir1STEXI 21525824d651Sblueswir1@item -win2k-hack 21536616b2adSStefan Weil@findex -win2k-hack 21545824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 21555824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 21565824d651Sblueswir1slows down the IDE transfers). 21575824d651Sblueswir1ETEXI 21585824d651Sblueswir1 21595824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 2160ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 2161ad96090aSBlue Swirl QEMU_ARCH_I386) 21625824d651Sblueswir1STEXI 21635824d651Sblueswir1@item -no-fd-bootchk 21646616b2adSStefan Weil@findex -no-fd-bootchk 21654eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 21665824d651Sblueswir1be needed to boot from old floppy disks. 21675824d651Sblueswir1ETEXI 21685824d651Sblueswir1 21695824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 2170f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 21715824d651Sblueswir1STEXI 21725824d651Sblueswir1@item -no-acpi 21736616b2adSStefan Weil@findex -no-acpi 21745824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 21755824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 21765824d651Sblueswir1only). 21775824d651Sblueswir1ETEXI 21785824d651Sblueswir1 21795824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 2180ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 21815824d651Sblueswir1STEXI 21825824d651Sblueswir1@item -no-hpet 21836616b2adSStefan Weil@findex -no-hpet 21845824d651Sblueswir1Disable HPET support. 21855824d651Sblueswir1ETEXI 21865824d651Sblueswir1 21875824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 2188104bf02eSMichael 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" 2189ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 21905824d651Sblueswir1STEXI 21915824d651Sblueswir1@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}]...] 21926616b2adSStefan Weil@findex -acpitable 21935824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 2194104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 2195104bf02eSMichael TokarevACPI headers (possible overridden by other options). 2196104bf02eSMichael TokarevFor data=, only data 2197104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 2198104bf02eSMichael Tokarevcommand line. 2199ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 2200ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 2201ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 2202ae123749SLaszlo Ersekspec. 22035824d651Sblueswir1ETEXI 22045824d651Sblueswir1 2205b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 2206b6f6e3d3Saliguori "-smbios file=binary\n" 2207ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 2208b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 2209b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 2210ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 2211b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2212b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 2213b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 2214b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2215b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 2216b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 2217b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 2218b155eb1dSGabriel L. Somlo " [,sku=str]\n" 2219b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 2220b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 2221b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 2222b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 2223b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 22243ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 2225b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 2226c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 2227b6f6e3d3SaliguoriSTEXI 2228b6f6e3d3Saliguori@item -smbios file=@var{binary} 22296616b2adSStefan Weil@findex -smbios 2230b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 2231b6f6e3d3Saliguori 223284351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 2233b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 2234b6f6e3d3Saliguori 2235b6f6e3d3Saliguori@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}] 2236b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 2237b155eb1dSGabriel L. Somlo 22383fdbd1d7SIgor Mammedov@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}] 2239b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 2240b155eb1dSGabriel L. Somlo 2241b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 2242b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 2243b155eb1dSGabriel L. Somlo 2244b155eb1dSGabriel 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}] 2245b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 2246b155eb1dSGabriel L. Somlo 22473ebd6cc8SGabriel 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}] 2248b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 2249b6f6e3d3SaliguoriETEXI 2250b6f6e3d3Saliguori 22515824d651Sblueswir1STEXI 22525824d651Sblueswir1@end table 22535824d651Sblueswir1ETEXI 2254c70a01e4SMarkus ArmbrusterDEFHEADING() 22555824d651Sblueswir1 2256de6b4f90SMarkus ArmbrusterDEFHEADING(Network options:) 22575824d651Sblueswir1STEXI 22585824d651Sblueswir1@table @option 22595824d651Sblueswir1ETEXI 22605824d651Sblueswir1 22616a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 22625824d651Sblueswir1#ifdef CONFIG_SLIRP 22630b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 22640b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 22650b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 2266f18d1375SBenjamin Drung " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 22670fca92b9SFam Zheng " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 2268ad196a9dSJan Kiszka#ifndef _WIN32 2269c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 2270ad196a9dSJan Kiszka#endif 22716a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 22726a8b4a5bSThomas Huth " its DHCP server and optional services\n" 22735824d651Sblueswir1#endif 22745824d651Sblueswir1#ifdef _WIN32 22756a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 22766a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 22775824d651Sblueswir1#else 22786a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 2279584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 22806a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 228169e87b32SJason Wang " [,poll-us=n]\n" 22826a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 2283584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 2284a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 2285a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 2286a7c36ee4SCorey Bryant " to deconfigure it\n" 2287ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 2288a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 2289a7c36ee4SCorey Bryant " configure it\n" 22905824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 22912ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 2292ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 2293f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 2294ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 2295ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 229682b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 22975430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 22985430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 229982b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 23002ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 2301ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 230269e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 230369e87b32SJason Wang " spent on busy polling for vhost net\n" 23046a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 23056a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 23066a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 23076a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 23080df0ff6dSMark McLoughlin#endif 23093fb69aa1SAnton Ivanov#ifdef __linux__ 23106a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 23116a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 23126a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 23136a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 23146a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 23156a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 23163fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 23172f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 23183fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 23193fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 23203fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 23213fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 23223fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 23233fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 23243952651aSGonglei " use 'srcport=' to specify source udp port\n" 23253fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 23263fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 23273fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 23283fb69aa1SAnton Ivanov " well as a weak security measure\n" 23293fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 23303fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 23313fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 23323fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 23333fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 23343fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 23353fb69aa1SAnton Ivanov#endif 23366a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 23376a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 23386a8b4a5bSThomas Huth " using a socket connection\n" 23396a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 23406a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 23413a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 23426a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 23436a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 23446a8b4a5bSThomas Huth " using an UDP tunnel\n" 23455824d651Sblueswir1#ifdef CONFIG_VDE 23466a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 23476a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 23486a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 23495824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 23505824d651Sblueswir1 " ownership and permissions for communication port.\n" 23515824d651Sblueswir1#endif 235258952137SVincenzo Maffione#ifdef CONFIG_NETMAP 23536a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 235458952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 235558952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 235658952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 235758952137SVincenzo Maffione#endif 2358253dc14cSThomas Huth#ifdef CONFIG_POSIX 23596a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 23606a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 2361253dc14cSThomas Huth#endif 236218d65d22SThomas Huth "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 2363af1a5c3eSThomas Huth " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 236478cd6f7bSThomas HuthDEF("nic", HAS_ARG, QEMU_OPTION_nic, 2365dfaa7d50SBALATON Zoltan "-nic [tap|bridge|" 236678cd6f7bSThomas Huth#ifdef CONFIG_SLIRP 236778cd6f7bSThomas Huth "user|" 236878cd6f7bSThomas Huth#endif 236978cd6f7bSThomas Huth#ifdef __linux__ 237078cd6f7bSThomas Huth "l2tpv3|" 237178cd6f7bSThomas Huth#endif 237278cd6f7bSThomas Huth#ifdef CONFIG_VDE 237378cd6f7bSThomas Huth "vde|" 237478cd6f7bSThomas Huth#endif 237578cd6f7bSThomas Huth#ifdef CONFIG_NETMAP 237678cd6f7bSThomas Huth "netmap|" 237778cd6f7bSThomas Huth#endif 237878cd6f7bSThomas Huth#ifdef CONFIG_POSIX 237978cd6f7bSThomas Huth "vhost-user|" 238078cd6f7bSThomas Huth#endif 238178cd6f7bSThomas Huth "socket][,option][,...][mac=macaddr]\n" 238278cd6f7bSThomas Huth " initialize an on-board / default host NIC (using MAC address\n" 238378cd6f7bSThomas Huth " macaddr) and connect it to the given host network backend\n" 2384dfaa7d50SBALATON Zoltan "-nic none use it alone to have zero network devices (the default is to\n" 238578cd6f7bSThomas Huth " provided a 'user' network connection)\n", 238678cd6f7bSThomas Huth QEMU_ARCH_ALL) 23876a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 2388af1a5c3eSThomas Huth "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 23890e60a82dSThomas Huth " configure or create an on-board (or machine default) NIC and\n" 2390af1a5c3eSThomas Huth " connect it to hub 0 (please use -nic unless you need a hub)\n" 23916a8b4a5bSThomas Huth "-net [" 2392a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 2393a1ea458fSMark McLoughlin "user|" 2394a1ea458fSMark McLoughlin#endif 2395a1ea458fSMark McLoughlin "tap|" 2396a7c36ee4SCorey Bryant "bridge|" 2397a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 2398a1ea458fSMark McLoughlin "vde|" 2399a1ea458fSMark McLoughlin#endif 240058952137SVincenzo Maffione#ifdef CONFIG_NETMAP 240158952137SVincenzo Maffione "netmap|" 240258952137SVincenzo Maffione#endif 2403af1a5c3eSThomas Huth "socket][,option][,option][,...]\n" 24046a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 24056a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 24065824d651Sblueswir1STEXI 2407abbbb035SThomas Huth@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 2408abbbb035SThomas Huth@findex -nic 2409abbbb035SThomas HuthThis option is a shortcut for configuring both the on-board (default) guest 2410abbbb035SThomas HuthNIC hardware and the host network backend in one go. The host backend options 2411abbbb035SThomas Huthare the same as with the corresponding @option{-netdev} options below. 2412abbbb035SThomas HuthThe guest NIC model can be set with @option{model=@var{modelname}}. 2413abbbb035SThomas HuthUse @option{model=help} to list the available device types. 2414abbbb035SThomas HuthThe hardware MAC address can be set with @option{mac=@var{macaddr}}. 2415abbbb035SThomas Huth 2416abbbb035SThomas HuthThe following two example do exactly the same, to show how @option{-nic} can 2417abbbb035SThomas Huthbe used to shorten the command line length (note that the e1000 is the default 2418abbbb035SThomas Huthon i386, so the @option{model=e1000} parameter could even be omitted here, too): 2419abbbb035SThomas Huth@example 2420664785acSThomas Huth@value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 2421664785acSThomas Huth@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 2422abbbb035SThomas Huth@end example 2423abbbb035SThomas Huth 2424abbbb035SThomas Huth@item -nic none 2425abbbb035SThomas HuthIndicate that no network devices should be configured. It is used to override 2426abbbb035SThomas Huththe default configuration (default NIC with ``user'' host network backend) 2427abbbb035SThomas Huthwhich is activated if no other networking options are provided. 24285824d651Sblueswir1 242908d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 2430b8f490ebSMarkus Armbruster@findex -netdev 2431abbbb035SThomas HuthConfigure user mode host network backend which requires no administrator 2432ad196a9dSJan Kiszkaprivilege to run. Valid options are: 24335824d651Sblueswir1 2434b3f046c2SKevin Wolf@table @option 243508d12022SStefan Hajnoczi@item id=@var{id} 2436ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 2437ad196a9dSJan Kiszka 2438abbbb035SThomas Huth@item ipv4=on|off and ipv6=on|off 2439abbbb035SThomas HuthSpecify that either IPv4 or IPv6 must be enabled. If neither is specified 2440abbbb035SThomas Huthboth protocols are enabled. 24410b11c036SSamuel Thibault 2442c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 2443c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 2444c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 2445b0b36e5dSBrad Hards10.0.2.0/24. 2446c92ef6a2SJan Kiszka 2447c92ef6a2SJan Kiszka@item host=@var{addr} 2448c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 2449c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 2450ad196a9dSJan Kiszka 2451d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 2452d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 2453d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 2454d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 2455d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 24567aac531eSYann Bordenave 2457d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 24587aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 24597aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 24607aac531eSYann Bordenave 2461c54ed5bcSJan Kiszka@item restrict=on|off 2462caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 2463ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 2464caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 2465ad196a9dSJan Kiszka 2466ad196a9dSJan Kiszka@item hostname=@var{name} 246763d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 2468ad196a9dSJan Kiszka 2469c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 2470c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 2471b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2472c92ef6a2SJan Kiszka 2473c92ef6a2SJan Kiszka@item dns=@var{addr} 2474c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 2475c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 2476c92ef6a2SJan Kiszkai.e. x.x.x.3. 2477c92ef6a2SJan Kiszka 2478d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 24797aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 24807aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 24817aac531eSYann Bordenavenetwork, i.e. xxxx::3. 24827aac531eSYann Bordenave 248363d2960bSKlaus Stengel@item dnssearch=@var{domain} 248463d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 248563d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 248663d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 248763d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 248863d2960bSKlaus Stengelcan not be resolved. 248963d2960bSKlaus Stengel 249063d2960bSKlaus StengelExample: 249163d2960bSKlaus Stengel@example 2492664785acSThomas Huth@value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 249363d2960bSKlaus Stengel@end example 249463d2960bSKlaus Stengel 2495f18d1375SBenjamin Drung@item domainname=@var{domain} 2496f18d1375SBenjamin DrungSpecifies the client domain name reported by the built-in DHCP server. 2497f18d1375SBenjamin Drung 2498ad196a9dSJan Kiszka@item tftp=@var{dir} 2499ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 2500ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 2501ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 2502c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 2503ad196a9dSJan Kiszka 25040fca92b9SFam Zheng@item tftp-server-name=@var{name} 25050fca92b9SFam ZhengIn BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option 25060fca92b9SFam Zheng66). This can be used to advise the guest to load boot files or configurations 25070fca92b9SFam Zhengfrom a different server than the host address. 25080fca92b9SFam Zheng 2509ad196a9dSJan Kiszka@item bootfile=@var{file} 2510ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 2511ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 2512ad196a9dSJan Kiszkaa guest from a local directory. 2513ad196a9dSJan Kiszka 2514ad196a9dSJan KiszkaExample (using pxelinux): 2515ad196a9dSJan Kiszka@example 2516664785acSThomas Huth@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \ 2517abbbb035SThomas Huth -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2518ad196a9dSJan Kiszka@end example 2519ad196a9dSJan Kiszka 2520c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 2521ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 2522ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 2523c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 2524c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 2525ad196a9dSJan Kiszka 2526ad196a9dSJan KiszkaIn the guest Windows OS, the line: 2527ad196a9dSJan Kiszka@example 2528ad196a9dSJan Kiszka10.0.2.4 smbserver 2529ad196a9dSJan Kiszka@end example 2530ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2531ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2532ad196a9dSJan Kiszka 2533ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2534ad196a9dSJan Kiszka 2535e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 2536ad196a9dSJan Kiszka 25373c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2538c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 2539c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 2540c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 25413c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 25423c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 2543c92ef6a2SJan Kiszkaused. This option can be given multiple times. 2544ad196a9dSJan Kiszka 2545ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 2546ad196a9dSJan Kiszkascreen 0, use the following: 2547ad196a9dSJan Kiszka 2548ad196a9dSJan Kiszka@example 2549ad196a9dSJan Kiszka# on the host 2550664785acSThomas Huth@value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 2551ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 2552ad196a9dSJan Kiszkaxterm -display :1 2553ad196a9dSJan Kiszka@end example 2554ad196a9dSJan Kiszka 2555ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 2556ad196a9dSJan Kiszkathe guest, use the following: 2557ad196a9dSJan Kiszka 2558ad196a9dSJan Kiszka@example 2559ad196a9dSJan Kiszka# on the host 2560664785acSThomas Huth@value{qemu_system} -nic user,hostfwd=tcp::5555-:23 2561ad196a9dSJan Kiszkatelnet localhost 5555 2562ad196a9dSJan Kiszka@end example 2563ad196a9dSJan Kiszka 2564ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 2565ad196a9dSJan Kiszkaconnect to the guest telnet server. 2566ad196a9dSJan Kiszka 2567c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2568f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 25693c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 2570b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 2571b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 2572b412eb61SAlexander Graf 257343ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 2574b412eb61SAlexander Graflifetime, like in the following example: 2575b412eb61SAlexander Graf 2576b412eb61SAlexander Graf@example 2577b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2578b412eb61SAlexander Graf# the guest accesses it 2579664785acSThomas Huth@value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 2580b412eb61SAlexander Graf@end example 2581b412eb61SAlexander Graf 2582b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 258343ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 2584b412eb61SAlexander Graf 2585b412eb61SAlexander Graf@example 2586b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2587b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 2588664785acSThomas Huth@value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2589b412eb61SAlexander Graf@end example 2590ad196a9dSJan Kiszka 2591ad196a9dSJan Kiszka@end table 2592ad196a9dSJan Kiszka 2593584613eaSAlexey 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}] 2594abbbb035SThomas HuthConfigure a host TAP network backend with ID @var{id}. 2595a7c36ee4SCorey Bryant 2596a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 25975824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2598a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 2599a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 2600a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2601a7c36ee4SCorey Bryantto disable script execution. 2602a7c36ee4SCorey Bryant 2603a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 2604584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 2605584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 2606584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 2607a7c36ee4SCorey Bryant 2608a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 2609a7c36ee4SCorey Bryantopened host TAP interface. 2610a7c36ee4SCorey Bryant 2611a7c36ee4SCorey BryantExamples: 26125824d651Sblueswir1 26135824d651Sblueswir1@example 2614a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 2615664785acSThomas Huth@value{qemu_system} linux.img -nic tap 26165824d651Sblueswir1@end example 26175824d651Sblueswir1 26185824d651Sblueswir1@example 2619a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 2620a7c36ee4SCorey Bryant#to a TAP device 2621664785acSThomas Huth@value{qemu_system} linux.img \ 262274f78b99SThomas Huth -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 262374f78b99SThomas Huth -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 26245824d651Sblueswir1@end example 26255824d651Sblueswir1 2626a7c36ee4SCorey Bryant@example 2627a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2628a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2629664785acSThomas Huth@value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \ 2630abbbb035SThomas Huth -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 2631a7c36ee4SCorey Bryant@end example 2632a7c36ee4SCorey Bryant 263308d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2634a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 2635a7c36ee4SCorey Bryant 2636a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 2637a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 2638420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 2639a7c36ee4SCorey Bryantdevice is @file{br0}. 2640a7c36ee4SCorey Bryant 2641a7c36ee4SCorey BryantExamples: 2642a7c36ee4SCorey Bryant 2643a7c36ee4SCorey Bryant@example 2644a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2645a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2646664785acSThomas Huth@value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 2647a7c36ee4SCorey Bryant@end example 2648a7c36ee4SCorey Bryant 2649a7c36ee4SCorey Bryant@example 2650a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2651a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 2652664785acSThomas Huth@value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 2653a7c36ee4SCorey Bryant@end example 2654a7c36ee4SCorey Bryant 265508d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 26565824d651Sblueswir1 2657abbbb035SThomas HuthThis host network backend can be used to connect the guest's network to 2658abbbb035SThomas Huthanother QEMU virtual machine using a TCP socket connection. If @option{listen} 2659abbbb035SThomas Huthis specified, QEMU waits for incoming connections on @var{port} 26605824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 26615824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 26625824d651Sblueswir1specifies an already opened TCP socket. 26635824d651Sblueswir1 26645824d651Sblueswir1Example: 26655824d651Sblueswir1@example 26665824d651Sblueswir1# launch a first QEMU instance 2667664785acSThomas Huth@value{qemu_system} linux.img \ 2668abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2669abbbb035SThomas Huth -netdev socket,id=n1,listen=:1234 2670abbbb035SThomas Huth# connect the network of this instance to the network of the first instance 2671664785acSThomas Huth@value{qemu_system} linux.img \ 2672abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2673abbbb035SThomas Huth -netdev socket,id=n2,connect=127.0.0.1:1234 26745824d651Sblueswir1@end example 26755824d651Sblueswir1 267608d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 26775824d651Sblueswir1 2678abbbb035SThomas HuthConfigure a socket host network backend to share the guest's network traffic 2679abbbb035SThomas Huthwith another QEMU virtual machines using a UDP multicast socket, effectively 2680abbbb035SThomas Huthmaking a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 26815824d651Sblueswir1NOTES: 26825824d651Sblueswir1@enumerate 26835824d651Sblueswir1@item 26845824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 26855824d651Sblueswir1correct multicast setup for these hosts). 26865824d651Sblueswir1@item 26875824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 26885824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 26895824d651Sblueswir1@item 26905824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 26915824d651Sblueswir1@end enumerate 26925824d651Sblueswir1 26935824d651Sblueswir1Example: 26945824d651Sblueswir1@example 26955824d651Sblueswir1# launch one QEMU instance 2696664785acSThomas Huth@value{qemu_system} linux.img \ 2697abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2698abbbb035SThomas Huth -netdev socket,id=n1,mcast=230.0.0.1:1234 26995824d651Sblueswir1# launch another QEMU instance on same "bus" 2700664785acSThomas Huth@value{qemu_system} linux.img \ 2701abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2702abbbb035SThomas Huth -netdev socket,id=n2,mcast=230.0.0.1:1234 27035824d651Sblueswir1# launch yet another QEMU instance on same "bus" 2704664785acSThomas Huth@value{qemu_system} linux.img \ 270537a4442aSThomas Huth -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 2706abbbb035SThomas Huth -netdev socket,id=n3,mcast=230.0.0.1:1234 27075824d651Sblueswir1@end example 27085824d651Sblueswir1 27095824d651Sblueswir1Example (User Mode Linux compat.): 27105824d651Sblueswir1@example 2711abbbb035SThomas Huth# launch QEMU instance (note mcast address selected is UML's default) 2712664785acSThomas Huth@value{qemu_system} linux.img \ 2713abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2714abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102 27155824d651Sblueswir1# launch UML 27165824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 27175824d651Sblueswir1@end example 27185824d651Sblueswir1 27193a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 27203a75e74cSMike Ryan@example 2721664785acSThomas Huth@value{qemu_system} linux.img \ 2722abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2723abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 27243a75e74cSMike Ryan@end example 27253a75e74cSMike Ryan 27263fb69aa1SAnton 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}] 2727abbbb035SThomas HuthConfigure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a 2728abbbb035SThomas Huthpopular protocol to transport Ethernet (and other Layer 2) data frames between 27293fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 27303fb69aa1SAnton Ivanov(from version 3.3 onwards). 27313fb69aa1SAnton Ivanov 27323fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 27333fb69aa1SAnton Ivanov 27341e9a7379SMarkus Armbruster@table @option 27353fb69aa1SAnton Ivanov@item src=@var{srcaddr} 27363fb69aa1SAnton Ivanov source address (mandatory) 27373fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 27383fb69aa1SAnton Ivanov destination address (mandatory) 27393fb69aa1SAnton Ivanov@item udp 27403fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 27413fb69aa1SAnton Ivanov@item srcport=@var{srcport} 27423fb69aa1SAnton Ivanov source udp port. 27433fb69aa1SAnton Ivanov@item dstport=@var{dstport} 27443fb69aa1SAnton Ivanov destination udp port. 27453fb69aa1SAnton Ivanov@item ipv6 27463fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 27473fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2748f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 27493fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 27503fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 27513fb69aa1SAnton Ivanovbit. 27523fb69aa1SAnton Ivanov@item cookie64 27533fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 27543fb69aa1SAnton Ivanov@item counter=off 27553fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 27563fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 27573fb69aa1SAnton Ivanov@item pincounter=on 27583fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 27593fb69aa1SAnton Ivanovnetworks which have packet reorder. 27603fb69aa1SAnton Ivanov@item offset=@var{offset} 27613fb69aa1SAnton Ivanov Add an extra offset between header and data 27621e9a7379SMarkus Armbruster@end table 27633fb69aa1SAnton Ivanov 27643fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 27653fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 27663fb69aa1SAnton Ivanov@example 27673fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 27683fb69aa1SAnton Ivanov# on 1.2.3.4 27693fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 27703fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 27713fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 27723fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 27733fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 27743fb69aa1SAnton Ivanovifconfig vmtunnel0 up 27753fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 27763fb69aa1SAnton Ivanov 27773fb69aa1SAnton Ivanov 27783fb69aa1SAnton Ivanov# on 4.3.2.1 27793fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 27803fb69aa1SAnton Ivanov 2781664785acSThomas Huth@value{qemu_system} linux.img -device e1000,netdev=n1 \ 2782abbbb035SThomas Huth -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 27833fb69aa1SAnton Ivanov 27843fb69aa1SAnton Ivanov@end example 27853fb69aa1SAnton Ivanov 278608d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2787abbbb035SThomas HuthConfigure VDE backend to connect to PORT @var{n} of a vde switch running on host and 27885824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 27895824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2790c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 27915824d651Sblueswir1with vde support enabled. 27925824d651Sblueswir1 27935824d651Sblueswir1Example: 27945824d651Sblueswir1@example 27955824d651Sblueswir1# launch vde switch 27965824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 27975824d651Sblueswir1# launch QEMU instance 2798664785acSThomas Huth@value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch 27995824d651Sblueswir1@end example 28005824d651Sblueswir1 2801b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 280203ce5744SNikolay Nikolaev 280303ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 280403ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 280503ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 280603ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2807b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2808b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 280903ce5744SNikolay Nikolaev 281003ce5744SNikolay NikolaevExample: 281103ce5744SNikolay Nikolaev@example 281203ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 281303ce5744SNikolay Nikolaev -numa node,memdev=mem \ 281479cad2faSVincenzo Maffione -chardev socket,id=chr0,path=/path/to/socket \ 281503ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 281603ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 281703ce5744SNikolay Nikolaev@end example 281803ce5744SNikolay Nikolaev 2819abbbb035SThomas Huth@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 282078cd6f7bSThomas Huth 2821abbbb035SThomas HuthCreate a hub port on the emulated hub with ID @var{hubid}. 282278cd6f7bSThomas Huth 2823abbbb035SThomas HuthThe hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 2824af1a5c3eSThomas Huthsingle netdev. Alternatively, you can also connect the hubport to another 2825af1a5c3eSThomas Huthnetdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 2826abbbb035SThomas Huth 2827af1a5c3eSThomas Huth@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 2828abbbb035SThomas Huth@findex -net 2829abbbb035SThomas HuthLegacy option to configure or create an on-board (or machine default) Network 2830af1a5c3eSThomas HuthInterface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 2831af1a5c3eSThomas Huththe default hub), or to the netdev @var{nd}. 2832abbbb035SThomas HuthThe NIC is an e1000 by default on the PC target. Optionally, the MAC address 2833abbbb035SThomas Huthcan be changed to @var{mac}, the device address set to @var{addr} (PCI cards 2834abbbb035SThomas Huthonly), and a @var{name} can be assigned for use in monitor commands. 2835abbbb035SThomas HuthOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2836abbbb035SThomas Huththat the card should have; this option currently only affects virtio cards; set 2837abbbb035SThomas Huth@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2838abbbb035SThomas HuthNIC is created. QEMU can emulate several different models of network card. 2839abbbb035SThomas HuthUse @code{-net nic,model=help} for a list of available devices for your target. 2840abbbb035SThomas Huth 2841af1a5c3eSThomas Huth@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 2842abbbb035SThomas HuthConfigure a host network backend (with the options corresponding to the same 2843af1a5c3eSThomas Huth@option{-netdev} option) and connect it to the emulated hub 0 (the default 2844af1a5c3eSThomas Huthhub). Use @var{name} to specify the name of the hub port. 28455824d651Sblueswir1ETEXI 28465824d651Sblueswir1 2847c70a01e4SMarkus ArmbrusterSTEXI 2848c70a01e4SMarkus Armbruster@end table 2849c70a01e4SMarkus ArmbrusterETEXI 28507273a2dbSMatthew BoothDEFHEADING() 28517273a2dbSMatthew Booth 2852de6b4f90SMarkus ArmbrusterDEFHEADING(Character device options:) 28537273a2dbSMatthew Booth 28547273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2855517b3d40SLin Ma "-chardev help\n" 2856d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28575dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2858981b06e7SJulia Suvorova " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n" 2859fd4a5fd4SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n" 2860981b06e7SJulia Suvorova "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n" 2861d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 28627273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 286397331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2864d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2865d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28667273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2867d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2868d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2869d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2870d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28717273a2dbSMatthew Booth#ifdef _WIN32 2872d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2873d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28747273a2dbSMatthew Booth#else 2875d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2876d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 28777273a2dbSMatthew Booth#endif 28787273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2879d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28807273a2dbSMatthew Booth#endif 28817273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 28827273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2883d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2884d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28857273a2dbSMatthew Booth#endif 28867273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2887d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2888d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28897273a2dbSMatthew Booth#endif 2890cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2891d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2892d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2893cbcc6336SAlon Levy#endif 2894ad96090aSBlue Swirl , QEMU_ARCH_ALL 28957273a2dbSMatthew Booth) 28967273a2dbSMatthew Booth 28977273a2dbSMatthew BoothSTEXI 2898dddba068SMarkus Armbruster 2899dddba068SMarkus ArmbrusterThe general form of a character device option is: 2900dddba068SMarkus Armbruster@table @option 290197331287SJan Kiszka@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 29026616b2adSStefan Weil@findex -chardev 29037273a2dbSMatthew BoothBackend is one of: 29047273a2dbSMatthew Booth@option{null}, 29057273a2dbSMatthew Booth@option{socket}, 29067273a2dbSMatthew Booth@option{udp}, 29077273a2dbSMatthew Booth@option{msmouse}, 29087273a2dbSMatthew Booth@option{vc}, 29094f57378fSMarkus Armbruster@option{ringbuf}, 29107273a2dbSMatthew Booth@option{file}, 29117273a2dbSMatthew Booth@option{pipe}, 29127273a2dbSMatthew Booth@option{console}, 29137273a2dbSMatthew Booth@option{serial}, 29147273a2dbSMatthew Booth@option{pty}, 29157273a2dbSMatthew Booth@option{stdio}, 29167273a2dbSMatthew Booth@option{braille}, 29177273a2dbSMatthew Booth@option{tty}, 291888a946d3SGerd Hoffmann@option{parallel}, 2919cbcc6336SAlon Levy@option{parport}, 292016fdc56aSThomas Huth@option{spicevmc}, 29215a49d3e9SMarc-André Lureau@option{spiceport}. 29227273a2dbSMatthew BoothThe specific backend will determine the applicable options. 29237273a2dbSMatthew Booth 2924dddba068SMarkus ArmbrusterUse @code{-chardev help} to print all available chardev backend types. 2925517b3d40SLin Ma 29267273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 29277273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 29287273a2dbSMatthew Booth 292997331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2930a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2931a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2932a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2933a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2934a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2935a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2936a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2937a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2938a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2939a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2940a40db1b3SPeter Maydell 2941a40db1b3SPeter Maydell@example 2942a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2943bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2944a40db1b3SPeter Maydell-serial chardev:char0 \ 2945a40db1b3SPeter Maydell-serial chardev:char0 2946a40db1b3SPeter Maydell@end example 2947a40db1b3SPeter Maydell 2948a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2949a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2950a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2951a40db1b3SPeter Maydell 2952a40db1b3SPeter Maydell@example 2953a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2954bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2955a40db1b3SPeter Maydell-parallel chardev:char0 \ 2956a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2957a40db1b3SPeter Maydell-serial chardev:char1 \ 2958a40db1b3SPeter Maydell-serial chardev:char1 2959a40db1b3SPeter Maydell@end example 2960a40db1b3SPeter Maydell 2961a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2962a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2963a40db1b3SPeter Maydellmultiplexer}. 2964a40db1b3SPeter Maydell 2965a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2966a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2967a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2968a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2969a40db1b3SPeter Maydellstdio. 2970a40db1b3SPeter Maydell 2971a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2972a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 297397331287SJan Kiszka 2974d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2975d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2976d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2977d0d7708bSDaniel P. Berrangeopened. 2978d0d7708bSDaniel P. Berrange 2979dddba068SMarkus Armbruster@end table 29807273a2dbSMatthew Booth 2981dddba068SMarkus ArmbrusterThe available backends are: 2982dddba068SMarkus Armbruster 2983dddba068SMarkus Armbruster@table @option 29847273a2dbSMatthew Booth@item -chardev null,id=@var{id} 29857273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 29867273a2dbSMatthew Boothreceives. The null backend does not take any options. 29877273a2dbSMatthew Booth 2988fd4a5fd4SDaniel P. Berrange@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}] 29897273a2dbSMatthew Booth 29907273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 29917273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 29927273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 29937273a2dbSMatthew Booth 29947273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 29957273a2dbSMatthew Booth 29967273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 29977273a2dbSMatthew Boothconnect to a listening socket. 29987273a2dbSMatthew Booth 29997273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 30007273a2dbSMatthew Boothescape sequences. 30017273a2dbSMatthew Booth 3002981b06e7SJulia Suvorova@option{websocket} specifies that the socket uses WebSocket protocol for 3003981b06e7SJulia Suvorovacommunication. 3004981b06e7SJulia Suvorova 30055dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 30065dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 30075dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 30085dd1f02bSCorey Minyard 3009a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 3010a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 3011a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 3012a8fb5427SDaniel P. Berrangeargument. 3013a8fb5427SDaniel P. Berrange 3014fd4a5fd4SDaniel P. Berrange@option{tls-auth} provides the ID of the QAuthZ authorization object against 3015fd4a5fd4SDaniel P. Berrangewhich the client's x509 distinguished name will be validated. This object is 3016fd4a5fd4SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the fly 3017fd4a5fd4SDaniel P. Berrangewhile the chardev server is active. If missing, it will default to denying 3018fd4a5fd4SDaniel P. Berrangeaccess. 3019fd4a5fd4SDaniel P. Berrange 30207273a2dbSMatthew BoothTCP and unix socket options are given below: 30217273a2dbSMatthew Booth 30227273a2dbSMatthew Booth@table @option 30237273a2dbSMatthew Booth 30248d533561SAurelien Jarno@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 30257273a2dbSMatthew Booth 30267273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 30277273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 30287273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 30297273a2dbSMatthew Booth 30307273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 30317273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 30327273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 30337273a2dbSMatthew Booth@option{port} is required. 30347273a2dbSMatthew Booth 30357273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 30367273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 30377273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 30387273a2dbSMatthew Boothas a port number. 30397273a2dbSMatthew Booth 30407273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 30417273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 30427273a2dbSMatthew Booth 30437273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 30447273a2dbSMatthew Booth 30457273a2dbSMatthew Booth@item unix options: path=@var{path} 30467273a2dbSMatthew Booth 30477273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 30487273a2dbSMatthew Boothrequired. 30497273a2dbSMatthew Booth 30507273a2dbSMatthew Booth@end table 30517273a2dbSMatthew Booth 30527273a2dbSMatthew Booth@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 30537273a2dbSMatthew Booth 30547273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 30557273a2dbSMatthew Booth 30567273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 30577273a2dbSMatthew Boothdefaults to @code{localhost}. 30587273a2dbSMatthew Booth 30597273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 30607273a2dbSMatthew Boothis required. 30617273a2dbSMatthew Booth 30627273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 30637273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 30647273a2dbSMatthew Booth 30657273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 30667273a2dbSMatthew Boothavailable local port will be used. 30677273a2dbSMatthew Booth 30687273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 30697273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 30707273a2dbSMatthew Booth 30717273a2dbSMatthew Booth@item -chardev msmouse,id=@var{id} 30727273a2dbSMatthew Booth 30737273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 30747273a2dbSMatthew Boothtake any options. 30757273a2dbSMatthew Booth 30767273a2dbSMatthew Booth@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 30777273a2dbSMatthew Booth 30787273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 30797273a2dbSMatthew Boothsize. 30807273a2dbSMatthew Booth 30817273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 30827273a2dbSMatthew Booththe console, in pixels. 30837273a2dbSMatthew Booth 30847273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 30857273a2dbSMatthew Boothconsole with the given dimensions. 30867273a2dbSMatthew Booth 30874f57378fSMarkus Armbruster@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 308851767e7cSLei Li 30893949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 3090e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 309151767e7cSLei Li 30927273a2dbSMatthew Booth@item -chardev file,id=@var{id},path=@var{path} 30937273a2dbSMatthew Booth 30947273a2dbSMatthew BoothLog all traffic received from the guest to a file. 30957273a2dbSMatthew Booth 30967273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 30977273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 30987273a2dbSMatthew Boothis required. 30997273a2dbSMatthew Booth 31007273a2dbSMatthew Booth@item -chardev pipe,id=@var{id},path=@var{path} 31017273a2dbSMatthew Booth 31027273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 31037273a2dbSMatthew BoothWindows hosts and other hosts: 31047273a2dbSMatthew Booth 31057273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 31067273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 31077273a2dbSMatthew Booth 31087273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 31097273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 31107273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 31117273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 31127273a2dbSMatthew Boothbe present. 31137273a2dbSMatthew Booth 31147273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 31157273a2dbSMatthew Boothrequired. 31167273a2dbSMatthew Booth 31177273a2dbSMatthew Booth@item -chardev console,id=@var{id} 31187273a2dbSMatthew Booth 31197273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 31207273a2dbSMatthew Boothtake any options. 31217273a2dbSMatthew Booth 31227273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 31237273a2dbSMatthew Booth 31247273a2dbSMatthew Booth@item -chardev serial,id=@var{id},path=@option{path} 31257273a2dbSMatthew Booth 31267273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 31277273a2dbSMatthew Booth 3128d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 3129d59044efSGerd Hoffmannnot only serial lines. 31307273a2dbSMatthew Booth 31317273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 31327273a2dbSMatthew Booth 31337273a2dbSMatthew Booth@item -chardev pty,id=@var{id} 31347273a2dbSMatthew Booth 31357273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 31367273a2dbSMatthew Boothnot take any options. 31377273a2dbSMatthew Booth 31387273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 31397273a2dbSMatthew Booth 3140b7fdb3abSAurelien Jarno@item -chardev stdio,id=@var{id}[,signal=on|off] 3141b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 3142b7fdb3abSAurelien Jarno 3143b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 3144b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 3145b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 3146b7fdb3abSAurelien Jarno 31477273a2dbSMatthew Booth@item -chardev braille,id=@var{id} 31487273a2dbSMatthew Booth 31497273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 31507273a2dbSMatthew Booth 31517273a2dbSMatthew Booth@item -chardev tty,id=@var{id},path=@var{path} 31527273a2dbSMatthew Booth 31537273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 3154d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 31557273a2dbSMatthew Booth 31567273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 31577273a2dbSMatthew Booth 315888a946d3SGerd Hoffmann@item -chardev parallel,id=@var{id},path=@var{path} 3159f9cfd655SMarkus Armbruster@itemx -chardev parport,id=@var{id},path=@var{path} 31607273a2dbSMatthew Booth 316188a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 31627273a2dbSMatthew Booth 31637273a2dbSMatthew BoothConnect to a local parallel port. 31647273a2dbSMatthew Booth 31657273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 31667273a2dbSMatthew Boothrequired. 31677273a2dbSMatthew Booth 3168cbcc6336SAlon Levy@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 3169cbcc6336SAlon Levy 31703a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 31713a846906SStefan Hajnoczi 3172cbcc6336SAlon Levy@option{debug} debug level for spicevmc 3173cbcc6336SAlon Levy 3174cbcc6336SAlon Levy@option{name} name of spice channel to connect to 3175cbcc6336SAlon Levy 3176cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 3177cbcc6336SAlon Levy 31785a49d3e9SMarc-André Lureau@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 31795a49d3e9SMarc-André Lureau 31805a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 31815a49d3e9SMarc-André Lureau 31825a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 31835a49d3e9SMarc-André Lureau 31845a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 31855a49d3e9SMarc-André Lureau 31865a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 31875a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 31887273a2dbSMatthew BoothETEXI 31897273a2dbSMatthew Booth 3190c70a01e4SMarkus ArmbrusterSTEXI 3191c70a01e4SMarkus Armbruster@end table 3192c70a01e4SMarkus ArmbrusterETEXI 31937273a2dbSMatthew BoothDEFHEADING() 31947273a2dbSMatthew Booth 3195d1a0cf73SStefan Berger#ifdef CONFIG_TPM 3196de6b4f90SMarkus ArmbrusterDEFHEADING(TPM device options:) 3197d1a0cf73SStefan Berger 3198d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 319992dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 320092dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 320192dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 3202f4ede81eSAmarnath Valluri " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 3203f4ede81eSAmarnath Valluri "-tpmdev emulator,id=id,chardev=dev\n" 3204f4ede81eSAmarnath Valluri " configure the TPM device using chardev backend\n", 3205d1a0cf73SStefan Berger QEMU_ARCH_ALL) 3206d1a0cf73SStefan BergerSTEXI 3207d1a0cf73SStefan Berger 3208d1a0cf73SStefan BergerThe general form of a TPM device option is: 3209d1a0cf73SStefan Berger@table @option 3210d1a0cf73SStefan Berger 3211d1a0cf73SStefan Berger@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 3212d1a0cf73SStefan Berger@findex -tpmdev 3213d1a0cf73SStefan Berger 3214d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 321528c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 321628c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 3217d1a0cf73SStefan Berger 32182252aaf0SMarkus ArmbrusterUse @code{-tpmdev help} to print all available TPM backend types. 3219d1a0cf73SStefan Berger 32202252aaf0SMarkus Armbruster@end table 32212252aaf0SMarkus Armbruster 32222252aaf0SMarkus ArmbrusterThe available backends are: 32232252aaf0SMarkus Armbruster 32242252aaf0SMarkus Armbruster@table @option 3225d1a0cf73SStefan Berger 322692dcc234SStefan Berger@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 32274549a8b7SStefan Berger 32284549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 32294549a8b7SStefan Bergerdriver. 32304549a8b7SStefan Berger 32314549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 32324549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 32334549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 32344549a8b7SStefan Berger 323592dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 323692dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 323792dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 323892dcc234SStefan Bergersysfs entry to use. 323992dcc234SStefan Berger 32404549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 32414549a8b7SStefan Berger 32424549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 32434549a8b7SStefan Bergerused by any other application on the host. 32444549a8b7SStefan Berger 32454549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 32464549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 32474549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 32484549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 32494549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 32504549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 32514549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 32524549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 32534549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 32544549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 32554549a8b7SStefan Berger 32564549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 32574549a8b7SStefan Berger@example 32584549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 32594549a8b7SStefan Berger@end example 32604549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 32614549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 32624549a8b7SStefan Berger 3263f4ede81eSAmarnath Valluri@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 3264f4ede81eSAmarnath Valluri 3265f4ede81eSAmarnath Valluri(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 3266f4ede81eSAmarnath Vallurichardev backend. 3267f4ede81eSAmarnath Valluri 3268f4ede81eSAmarnath Valluri@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 3269f4ede81eSAmarnath Valluri 3270f4ede81eSAmarnath ValluriTo create a TPM emulator backend device with chardev socket backend: 3271f4ede81eSAmarnath Valluri@example 3272f4ede81eSAmarnath Valluri 3273f4ede81eSAmarnath Valluri-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 3274f4ede81eSAmarnath Valluri 3275f4ede81eSAmarnath Valluri@end example 3276f4ede81eSAmarnath Valluri 3277d1a0cf73SStefan BergerETEXI 3278d1a0cf73SStefan Berger 32792252aaf0SMarkus ArmbrusterSTEXI 32802252aaf0SMarkus Armbruster@end table 32812252aaf0SMarkus ArmbrusterETEXI 3282d1a0cf73SStefan BergerDEFHEADING() 3283d1a0cf73SStefan Berger 3284d1a0cf73SStefan Berger#endif 3285d1a0cf73SStefan Berger 3286de6b4f90SMarkus ArmbrusterDEFHEADING(Linux/Multiboot boot specific:) 32875824d651Sblueswir1STEXI 32887677f05dSAlexander Graf 32897677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 32907677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 32915824d651Sblueswir1for easier testing of various kernels. 32925824d651Sblueswir1 32935824d651Sblueswir1@table @option 32945824d651Sblueswir1ETEXI 32955824d651Sblueswir1 32965824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 3297ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 32985824d651Sblueswir1STEXI 32995824d651Sblueswir1@item -kernel @var{bzImage} 33006616b2adSStefan Weil@findex -kernel 33017677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 33027677f05dSAlexander Grafor in multiboot format. 33035824d651Sblueswir1ETEXI 33045824d651Sblueswir1 33055824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 3306ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 33075824d651Sblueswir1STEXI 33085824d651Sblueswir1@item -append @var{cmdline} 33096616b2adSStefan Weil@findex -append 33105824d651Sblueswir1Use @var{cmdline} as kernel command line 33115824d651Sblueswir1ETEXI 33125824d651Sblueswir1 33135824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 3314ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 33155824d651Sblueswir1STEXI 33165824d651Sblueswir1@item -initrd @var{file} 33176616b2adSStefan Weil@findex -initrd 33185824d651Sblueswir1Use @var{file} as initial ram disk. 33197677f05dSAlexander Graf 33207677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 33217677f05dSAlexander Graf 33227677f05dSAlexander GrafThis syntax is only available with multiboot. 33237677f05dSAlexander Graf 33247677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 33257677f05dSAlexander Graffirst module. 33265824d651Sblueswir1ETEXI 33275824d651Sblueswir1 3328412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 3329379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 3330412beee6SGrant LikelySTEXI 3331412beee6SGrant Likely@item -dtb @var{file} 3332412beee6SGrant Likely@findex -dtb 3333412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 3334412beee6SGrant Likelyon boot. 3335412beee6SGrant LikelyETEXI 3336412beee6SGrant Likely 33375824d651Sblueswir1STEXI 33385824d651Sblueswir1@end table 33395824d651Sblueswir1ETEXI 33405824d651Sblueswir1DEFHEADING() 33415824d651Sblueswir1 3342de6b4f90SMarkus ArmbrusterDEFHEADING(Debug/Expert options:) 33435824d651Sblueswir1STEXI 33445824d651Sblueswir1@table @option 33455824d651Sblueswir1ETEXI 33465824d651Sblueswir1 334781b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 334881b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 334963d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 33506407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 335163d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 335281b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 335381b2b810SGabriel L. SomloSTEXI 335463d3145aSMarkus Armbruster 335581b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 335681b2b810SGabriel L. Somlo@findex -fw_cfg 335763d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 33586407d76eSGabriel L. Somlo 33596407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 336063d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 336163d3145aSMarkus Armbruster 336263d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 336363d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 336463d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 336563d3145aSMarkus Armbruster 336663d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 336763d3145aSMarkus Armbruster 336863d3145aSMarkus ArmbrusterExample: 336963d3145aSMarkus Armbruster@example 337063d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 337163d3145aSMarkus Armbruster@end example 337263d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 337363d3145aSMarkus Armbrusterfrom ./my_blob.bin. 337463d3145aSMarkus Armbruster 337581b2b810SGabriel L. SomloETEXI 337681b2b810SGabriel L. Somlo 33775824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3378ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 3379ad96090aSBlue Swirl QEMU_ARCH_ALL) 33805824d651Sblueswir1STEXI 33815824d651Sblueswir1@item -serial @var{dev} 33826616b2adSStefan Weil@findex -serial 33835824d651Sblueswir1Redirect the virtual serial port to host character device 33845824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 33855824d651Sblueswir1@code{stdio} in non graphical mode. 33865824d651Sblueswir1 33875824d651Sblueswir1This option can be used several times to simulate up to 4 serial 33885824d651Sblueswir1ports. 33895824d651Sblueswir1 33905824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 33915824d651Sblueswir1 33925824d651Sblueswir1Available character devices are: 3393b3f046c2SKevin Wolf@table @option 33944e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 33955824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 33965824d651Sblueswir1@example 33975824d651Sblueswir1vc:800x600 33985824d651Sblueswir1@end example 33995824d651Sblueswir1It is also possible to specify width or height in characters: 34005824d651Sblueswir1@example 34015824d651Sblueswir1vc:80Cx24C 34025824d651Sblueswir1@end example 34035824d651Sblueswir1@item pty 34045824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 34055824d651Sblueswir1@item none 34065824d651Sblueswir1No device is allocated. 34075824d651Sblueswir1@item null 34085824d651Sblueswir1void device 340988e020e5SIngo van Lil@item chardev:@var{id} 341088e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 34115824d651Sblueswir1@item /dev/XXX 34125824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 34135824d651Sblueswir1parameters are set according to the emulated ones. 34145824d651Sblueswir1@item /dev/parport@var{N} 34155824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 34165824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 34175824d651Sblueswir1@item file:@var{filename} 34185824d651Sblueswir1Write output to @var{filename}. No character can be read. 34195824d651Sblueswir1@item stdio 34205824d651Sblueswir1[Unix only] standard input/output 34215824d651Sblueswir1@item pipe:@var{filename} 34225824d651Sblueswir1name pipe @var{filename} 34235824d651Sblueswir1@item COM@var{n} 34245824d651Sblueswir1[Windows only] Use host serial port @var{n} 34255824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 34265824d651Sblueswir1This implements UDP Net Console. 34275824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 34285824d651Sblueswir1they default to @code{0.0.0.0}. 34295824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 34305824d651Sblueswir1 34315824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3432b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3433b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 34345824d651Sblueswir1will appear in the netconsole session. 34355824d651Sblueswir1 34365824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3437b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 34385824d651Sblueswir1source port each time by using something like @code{-serial 3439b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 34405824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 34415824d651Sblueswir1characters via udp. If you have a patched version of netcat which 34425824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3443bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3444b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 34455824d651Sblueswir1@table @code 3446071c9394SStefan Weil@item QEMU Options: 34475824d651Sblueswir1-serial udp::4555@@:4556 34485824d651Sblueswir1@item netcat options: 34495824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 34505824d651Sblueswir1@item telnet options: 34515824d651Sblueswir1localhost 5555 34525824d651Sblueswir1@end table 34535824d651Sblueswir1 34545dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 34555824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 34565824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 34575824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 34585824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 34595824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 34605824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 34615dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 34625dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 34635dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 34645824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 34655824d651Sblueswir1connect to the corresponding character device. 34665824d651Sblueswir1@table @code 34675824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 34685824d651Sblueswir1-serial tcp:192.168.0.2:4444 34695824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 34705824d651Sblueswir1-serial tcp::4444,server 34715824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 34725824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 34735824d651Sblueswir1@end table 34745824d651Sblueswir1 34755824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 34765824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 34775824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 34785824d651Sblueswir1difference is that the port acts like a telnet server or client using 34795824d651Sblueswir1telnet option negotiation. This will also allow you to send the 34805824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 34815824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 34825824d651Sblueswir1type "send break" followed by pressing the enter key. 34835824d651Sblueswir1 3484981b06e7SJulia Suvorova@item websocket:@var{host}:@var{port},server[,nowait][,nodelay] 3485981b06e7SJulia SuvorovaThe WebSocket protocol is used instead of raw tcp socket. The port acts as 3486981b06e7SJulia Suvorovaa WebSocket server. Client mode is not supported. 3487981b06e7SJulia Suvorova 34885dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 34895824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 34905824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 34915824d651Sblueswir1@var{path} is used for connections. 34925824d651Sblueswir1 34935824d651Sblueswir1@item mon:@var{dev_string} 34945824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 34955824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 349602c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 34975824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 34985824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 34995824d651Sblueswir1listening on port 4444 would be: 35005824d651Sblueswir1@table @code 35015824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 35025824d651Sblueswir1@end table 3503be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 350402c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 35055824d651Sblueswir1 35065824d651Sblueswir1@item braille 35075824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 35085824d651Sblueswir1or fake device. 35095824d651Sblueswir1 3510be8b28a9SKevin Wolf@item msmouse 3511be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 35125824d651Sblueswir1@end table 35135824d651Sblueswir1ETEXI 35145824d651Sblueswir1 35155824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3516ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3517ad96090aSBlue Swirl QEMU_ARCH_ALL) 35185824d651Sblueswir1STEXI 35195824d651Sblueswir1@item -parallel @var{dev} 35206616b2adSStefan Weil@findex -parallel 35215824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 35225824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 35235824d651Sblueswir1be used to use hardware devices connected on the corresponding host 35245824d651Sblueswir1parallel port. 35255824d651Sblueswir1 35265824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 35275824d651Sblueswir1ports. 35285824d651Sblueswir1 35295824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 35305824d651Sblueswir1ETEXI 35315824d651Sblueswir1 35325824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3533ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3534ad96090aSBlue Swirl QEMU_ARCH_ALL) 35355824d651Sblueswir1STEXI 35364e307fc8SGerd Hoffmann@item -monitor @var{dev} 35376616b2adSStefan Weil@findex -monitor 35385824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 35395824d651Sblueswir1serial port). 35405824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 35415824d651Sblueswir1non graphical mode. 354270e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 35435824d651Sblueswir1ETEXI 35446ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3545ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3546ad96090aSBlue Swirl QEMU_ARCH_ALL) 354795d5f08bSStefan WeilSTEXI 354895d5f08bSStefan Weil@item -qmp @var{dev} 35496616b2adSStefan Weil@findex -qmp 355095d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 355195d5f08bSStefan WeilETEXI 35524821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 35534821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 35544821cd4cSMax Reitz QEMU_ARCH_ALL) 35554821cd4cSMax ReitzSTEXI 35564821cd4cSMax Reitz@item -qmp-pretty @var{dev} 35574821cd4cSMax Reitz@findex -qmp-pretty 35584821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 35594821cd4cSMax ReitzETEXI 35605824d651Sblueswir1 356122a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3562ef670726SVicente Jimenez Aguilar "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 356322a0e04bSGerd HoffmannSTEXI 3564ef670726SVicente Jimenez Aguilar@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 35656616b2adSStefan Weil@findex -mon 3566ef670726SVicente Jimenez AguilarSetup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 3567ef670726SVicente Jimenez Aguilareasing human reading and debugging. 356822a0e04bSGerd HoffmannETEXI 356922a0e04bSGerd Hoffmann 3570c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3571ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3572ad96090aSBlue Swirl QEMU_ARCH_ALL) 3573c9f398e5SH. Peter AnvinSTEXI 3574c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 35756616b2adSStefan Weil@findex -debugcon 3576c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3577c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3578c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3579c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3580c9f398e5SH. Peter Anvinnon graphical mode. 3581c9f398e5SH. Peter AnvinETEXI 3582c9f398e5SH. Peter Anvin 35835824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3584ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 35855824d651Sblueswir1STEXI 35865824d651Sblueswir1@item -pidfile @var{file} 35876616b2adSStefan Weil@findex -pidfile 35885824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 35895824d651Sblueswir1from a script. 35905824d651Sblueswir1ETEXI 35915824d651Sblueswir1 35921b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3593ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 35941b530a6dSaurel32STEXI 35951b530a6dSaurel32@item -singlestep 35966616b2adSStefan Weil@findex -singlestep 35971b530a6dSaurel32Run the emulation in single step mode. 35981b530a6dSaurel32ETEXI 35991b530a6dSaurel32 3600047f7038SIgor MammedovDEF("preconfig", 0, QEMU_OPTION_preconfig, \ 3601361ac948SMarkus Armbruster "--preconfig pause QEMU before machine is initialized (experimental)\n", 3602047f7038SIgor Mammedov QEMU_ARCH_ALL) 3603047f7038SIgor MammedovSTEXI 3604047f7038SIgor Mammedov@item --preconfig 3605047f7038SIgor Mammedov@findex --preconfig 3606047f7038SIgor MammedovPause QEMU for interactive configuration before the machine is created, 3607047f7038SIgor Mammedovwhich allows querying and configuring properties that will affect 3608361ac948SMarkus Armbrustermachine initialization. Use QMP command 'x-exit-preconfig' to exit 3609361ac948SMarkus Armbrusterthe preconfig state and move to the next state (i.e. run guest if -S 3610361ac948SMarkus Armbrusterisn't used or pause the second time if -S is used). This option is 3611361ac948SMarkus Armbrusterexperimental. 3612047f7038SIgor MammedovETEXI 3613047f7038SIgor Mammedov 36145824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3615ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3616ad96090aSBlue Swirl QEMU_ARCH_ALL) 36175824d651Sblueswir1STEXI 36185824d651Sblueswir1@item -S 36196616b2adSStefan Weil@findex -S 36205824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 36215824d651Sblueswir1ETEXI 36225824d651Sblueswir1 3623888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3624888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3625888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3626888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3627888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3628888a6bc6SSatoru MoriyaSTEXI 3629888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3630888a6bc6SSatoru Moriya@findex -realtime 3631888a6bc6SSatoru MoriyaRun qemu with realtime features. 3632888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3633888a6bc6SSatoru Moriya(enabled by default). 3634888a6bc6SSatoru MoriyaETEXI 3635888a6bc6SSatoru Moriya 36366f131f13SMichael S. TsirkinDEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, 3637dfaa7d50SBALATON Zoltan "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" 36386f131f13SMichael S. Tsirkin " run qemu with overcommit hints\n" 36396f131f13SMichael S. Tsirkin " mem-lock=on|off controls memory lock support (default: off)\n" 36406f131f13SMichael S. Tsirkin " cpu-pm=on|off controls cpu power management (default: off)\n", 36416f131f13SMichael S. Tsirkin QEMU_ARCH_ALL) 36426f131f13SMichael S. TsirkinSTEXI 36436f131f13SMichael S. Tsirkin@item -overcommit mem-lock=on|off 36446f131f13SMichael S. Tsirkin@item -overcommit cpu-pm=on|off 36456f131f13SMichael S. Tsirkin@findex -overcommit 36466f131f13SMichael S. TsirkinRun qemu with hints about host resource overcommit. The default is 36476f131f13SMichael S. Tsirkinto assume that host overcommits all resources. 36486f131f13SMichael S. Tsirkin 36496f131f13SMichael S. TsirkinLocking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled 36506f131f13SMichael S. Tsirkinby default). This works when host memory is not overcommitted and reduces the 36516f131f13SMichael S. Tsirkinworst-case latency for guest. This is equivalent to @option{realtime}. 36526f131f13SMichael S. Tsirkin 36536f131f13SMichael S. TsirkinGuest ability to manage power state of host cpus (increasing latency for other 36546f131f13SMichael S. Tsirkinprocesses on the same host cpu, but decreasing latency for guest) can be 36556f131f13SMichael S. Tsirkinenabled via @option{cpu-pm=on} (disabled by default). This works best when 36566f131f13SMichael S. Tsirkinhost CPU is not overcommitted. When used, host estimates of CPU cycle and power 36576f131f13SMichael S. Tsirkinutilization will be incorrect, not taking into account guest idle time. 36586f131f13SMichael S. TsirkinETEXI 36596f131f13SMichael S. Tsirkin 366059030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3661ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 36625824d651Sblueswir1STEXI 366359030a8cSaliguori@item -gdb @var{dev} 36646616b2adSStefan Weil@findex -gdb 366559030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 366659030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3667b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 366859030a8cSaliguoriwithin gdb and establish the connection via a pipe: 366959030a8cSaliguori@example 3670664785acSThomas Huth(gdb) target remote | exec @value{qemu_system} -gdb stdio ... 367159030a8cSaliguori@end example 36725824d651Sblueswir1ETEXI 36735824d651Sblueswir1 367459030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3675ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3676ad96090aSBlue Swirl QEMU_ARCH_ALL) 36775824d651Sblueswir1STEXI 367859030a8cSaliguori@item -s 36796616b2adSStefan Weil@findex -s 368059030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 368159030a8cSaliguori(@pxref{gdb_usage}). 36825824d651Sblueswir1ETEXI 36835824d651Sblueswir1 36845824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3685989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3686ad96090aSBlue Swirl QEMU_ARCH_ALL) 36875824d651Sblueswir1STEXI 3688989b697dSPeter Maydell@item -d @var{item1}[,...] 36896616b2adSStefan Weil@findex -d 3690989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 36915824d651Sblueswir1ETEXI 36925824d651Sblueswir1 3693c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3694989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3695c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3696c235d738SMatthew FernandezSTEXI 36978bd383b4SStefan Weil@item -D @var{logfile} 3698c235d738SMatthew Fernandez@findex -D 3699989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3700c235d738SMatthew FernandezETEXI 3701c235d738SMatthew Fernandez 37023514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 37033514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 37043514552eSAlex Bennée QEMU_ARCH_ALL) 37053514552eSAlex BennéeSTEXI 37063514552eSAlex Bennée@item -dfilter @var{range1}[,...] 37073514552eSAlex Bennée@findex -dfilter 37083514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 37093514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 37103514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 37113514552eSAlex Bennéeaddresses and sizes required. For example: 37123514552eSAlex Bennée@example 37133514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 37143514552eSAlex Bennée@end example 37153514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 37163514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 37173514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 37183514552eSAlex BennéeETEXI 37193514552eSAlex Bennée 37209c09a251SRichard HendersonDEF("seed", HAS_ARG, QEMU_OPTION_seed, \ 37219c09a251SRichard Henderson "-seed number seed the pseudo-random number generator\n", 37229c09a251SRichard Henderson QEMU_ARCH_ALL) 37239c09a251SRichard HendersonSTEXI 37249c09a251SRichard Henderson@item -seed @var{number} 37259c09a251SRichard Henderson@findex -seed 37269c09a251SRichard HendersonForce the guest to use a deterministic pseudo-random number generator, seeded 37279c09a251SRichard Hendersonwith @var{number}. This does not affect crypto routines within the host. 37289c09a251SRichard HendersonETEXI 37299c09a251SRichard Henderson 37305824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3731ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3732ad96090aSBlue Swirl QEMU_ARCH_ALL) 37335824d651Sblueswir1STEXI 37345824d651Sblueswir1@item -L @var{path} 37356616b2adSStefan Weil@findex -L 37365824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 373737146e7eSRichard W.M. Jones 373837146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 37395824d651Sblueswir1ETEXI 37405824d651Sblueswir1 37415824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3742ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 37435824d651Sblueswir1STEXI 37445824d651Sblueswir1@item -bios @var{file} 37456616b2adSStefan Weil@findex -bios 37465824d651Sblueswir1Set the filename for the BIOS. 37475824d651Sblueswir1ETEXI 37485824d651Sblueswir1 37495824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3750ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 37515824d651Sblueswir1STEXI 37525824d651Sblueswir1@item -enable-kvm 37536616b2adSStefan Weil@findex -enable-kvm 37545824d651Sblueswir1Enable KVM full virtualization support. This option is only available 37555824d651Sblueswir1if KVM support is enabled when compiling. 37565824d651Sblueswir1ETEXI 37575824d651Sblueswir1 3758e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3759ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3760e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3761e37630caSaliguori "-xen-attach attach to existing xen domain\n" 37621077bcacSAnthony PERARD " libxl will use this when starting QEMU\n", 3763ad96090aSBlue Swirl QEMU_ARCH_ALL) 37641c599472SPaul DurrantDEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 37651c599472SPaul Durrant "-xen-domid-restrict restrict set of available xen operations\n" 37661c599472SPaul Durrant " to specified domain id. (Does not affect\n" 37671c599472SPaul Durrant " xenpv machine type).\n", 37681c599472SPaul Durrant QEMU_ARCH_ALL) 376995d5f08bSStefan WeilSTEXI 377095d5f08bSStefan Weil@item -xen-domid @var{id} 37716616b2adSStefan Weil@findex -xen-domid 377295d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 377395d5f08bSStefan Weil@item -xen-attach 37746616b2adSStefan Weil@findex -xen-attach 377595d5f08bSStefan WeilAttach to existing xen domain. 37761077bcacSAnthony PERARDlibxl will use this when starting QEMU (XEN only). 37771c599472SPaul Durrant@findex -xen-domid-restrict 37781c599472SPaul DurrantRestrict set of available xen operations to specified domain id (XEN only). 377995d5f08bSStefan WeilETEXI 3780e37630caSaliguori 37815824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3782ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 37835824d651Sblueswir1STEXI 37845824d651Sblueswir1@item -no-reboot 37856616b2adSStefan Weil@findex -no-reboot 37865824d651Sblueswir1Exit instead of rebooting. 37875824d651Sblueswir1ETEXI 37885824d651Sblueswir1 37895824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3790ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 37915824d651Sblueswir1STEXI 37925824d651Sblueswir1@item -no-shutdown 37936616b2adSStefan Weil@findex -no-shutdown 37945824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 37955824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 37965824d651Sblueswir1disk image. 37975824d651Sblueswir1ETEXI 37985824d651Sblueswir1 37995824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 38005824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3801ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3802ad96090aSBlue Swirl QEMU_ARCH_ALL) 38035824d651Sblueswir1STEXI 38045824d651Sblueswir1@item -loadvm @var{file} 38056616b2adSStefan Weil@findex -loadvm 38065824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 38075824d651Sblueswir1ETEXI 38085824d651Sblueswir1 38095824d651Sblueswir1#ifndef _WIN32 38105824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3811ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 38125824d651Sblueswir1#endif 38135824d651Sblueswir1STEXI 38145824d651Sblueswir1@item -daemonize 38156616b2adSStefan Weil@findex -daemonize 38165824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 38175824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 38185824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 38195824d651Sblueswir1to cope with initialization race conditions. 38205824d651Sblueswir1ETEXI 38215824d651Sblueswir1 38225824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3823ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3824ad96090aSBlue Swirl QEMU_ARCH_ALL) 38255824d651Sblueswir1STEXI 38265824d651Sblueswir1@item -option-rom @var{file} 38276616b2adSStefan Weil@findex -option-rom 38285824d651Sblueswir1Load the contents of @var{file} as an option ROM. 38295824d651Sblueswir1This option is useful to load things like EtherBoot. 38305824d651Sblueswir1ETEXI 38315824d651Sblueswir1 38321ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 3833238d1240SArtem Pisarenko "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3834ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3835ad96090aSBlue Swirl QEMU_ARCH_ALL) 38361ed2fc1fSJan Kiszka 38375824d651Sblueswir1STEXI 38385824d651Sblueswir1 3839238d1240SArtem Pisarenko@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew] 38406616b2adSStefan Weil@findex -rtc 38411ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 38421ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 3843238d1240SArtem PisarenkoMS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the 38441ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 38451ed2fc1fSJan Kiszka 38469d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 38476875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 38486875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 384978808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 3850238d1240SArtem Pisarenkoto @code{rt} instead, which provides a host monotonic clock if host support it. 3851238d1240SArtem PisarenkoTo even prevent the RTC from progressing during suspension, you can set @option{clock} 3852238d1240SArtem Pisarenkoto @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in 3853238d1240SArtem Pisarenkoicount mode in order to preserve determinism; however, note that in icount mode 3854238d1240SArtem Pisarenkothe speed of the virtual clock is variable and can in general differ from the 3855238d1240SArtem Pisarenkohost clock. 38566875204cSJan Kiszka 38571ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 38581ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 38591ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 38601ed2fc1fSJan Kiszkare-inject them. 38615824d651Sblueswir1ETEXI 38625824d651Sblueswir1 38635824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 38649c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3865bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3866f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3867f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 38685824d651Sblueswir1STEXI 38699c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 38706616b2adSStefan Weil@findex -icount 38715824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 38724e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 38735824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 38745824d651Sblueswir1time within a few seconds of real time. 38755824d651Sblueswir1 3876f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3877778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3878778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3879f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3880f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3881f1f4b57eSVictor CLEMENTthe guest point of view. 3882f1f4b57eSVictor CLEMENT 38835824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 38845824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 38855824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 38865824d651Sblueswir1executed often has little or no correlation with actual performance. 3887a8bfac37SSebastian Tanase 3888b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3889a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3890a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3891a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 389282597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3893a8bfac37SSebastian Tanaseto inform about the delay. 3894a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3895a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3896a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3897a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 38984c27b859SPavel Dovgalyuk 38994c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 39004c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 39014c27b859SPavel Dovgalyukread from this file in replay mode. 39029c2037d0SPavel Dovgalyuk 39039c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 39049c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 39059c2037d0SPavel Dovgalyukto load the initial VM state. 39065824d651Sblueswir1ETEXI 39075824d651Sblueswir1 39089dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3909d7933ef3SXu Wang "-watchdog model\n" \ 3910ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3911ad96090aSBlue Swirl QEMU_ARCH_ALL) 39129dd986ccSRichard W.M. JonesSTEXI 39139dd986ccSRichard W.M. Jones@item -watchdog @var{model} 39146616b2adSStefan Weil@findex -watchdog 39159dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 39169dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3917d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3918d7933ef3SXu Wangwhich your guest has drivers. 39199dd986ccSRichard W.M. Jones 3920d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3921d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 39229dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3923d7933ef3SXu Wang 3924d7933ef3SXu WangThe following models may be available: 3925d7933ef3SXu Wang@table @option 3926d7933ef3SXu Wang@item ib700 3927d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3928d7933ef3SXu Wang@item i6300esb 3929d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3930d7933ef3SXu Wangdual-timer watchdog. 3931188f24c2SXu Wang@item diag288 3932188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3933188f24c2SXu Wang(currently KVM only). 3934d7933ef3SXu Wang@end table 39359dd986ccSRichard W.M. JonesETEXI 39369dd986ccSRichard W.M. Jones 39379dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 39387ad9270eSMarkus Armbruster "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 3939ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3940ad96090aSBlue Swirl QEMU_ARCH_ALL) 39419dd986ccSRichard W.M. JonesSTEXI 39429dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3943b8f490ebSMarkus Armbruster@findex -watchdog-action 39449dd986ccSRichard W.M. Jones 39459dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 39469dd986ccSRichard W.M. Jonesexpires. 39479dd986ccSRichard W.M. JonesThe default is 39489dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 39499dd986ccSRichard W.M. JonesOther possible actions are: 39509dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 39519dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 39527ad9270eSMarkus Armbruster@code{inject-nmi} (inject a NMI into the guest), 39539dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 39549dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 39559dd986ccSRichard W.M. Jones@code{none} (do nothing). 39569dd986ccSRichard W.M. Jones 39579dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 39589dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 39599dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 39609dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 39619dd986ccSRichard W.M. Jones 39629dd986ccSRichard W.M. JonesExamples: 39639dd986ccSRichard W.M. Jones 39649dd986ccSRichard W.M. Jones@table @code 39659dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3966f9cfd655SMarkus Armbruster@itemx -watchdog ib700 39679dd986ccSRichard W.M. Jones@end table 39689dd986ccSRichard W.M. JonesETEXI 39699dd986ccSRichard W.M. Jones 39705824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3971ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3972ad96090aSBlue Swirl QEMU_ARCH_ALL) 39735824d651Sblueswir1STEXI 39745824d651Sblueswir1 39754e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 39766616b2adSStefan Weil@findex -echr 39775824d651Sblueswir1Change the escape character used for switching to the monitor when using 39785824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 39795824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 39805824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 39815824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 39825824d651Sblueswir1instance you could use the either of the following to change the escape 39835824d651Sblueswir1character to Control-t. 39845824d651Sblueswir1@table @code 39855824d651Sblueswir1@item -echr 0x14 3986f9cfd655SMarkus Armbruster@itemx -echr 20 39875824d651Sblueswir1@end table 39885824d651Sblueswir1ETEXI 39895824d651Sblueswir1 39905824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3991ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 39925824d651Sblueswir1STEXI 399395d5f08bSStefan Weil@item -show-cursor 39946616b2adSStefan Weil@findex -show-cursor 399595d5f08bSStefan WeilShow cursor. 39965824d651Sblueswir1ETEXI 39975824d651Sblueswir1 39985824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3999ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 40005824d651Sblueswir1STEXI 400195d5f08bSStefan Weil@item -tb-size @var{n} 40026616b2adSStefan Weil@findex -tb-size 4003fe174132SPaolo BonziniSet TCG translation block cache size. Deprecated, use @samp{-accel tcg,tb-size=@var{n}} 4004fe174132SPaolo Bonziniinstead. 40055824d651Sblueswir1ETEXI 40065824d651Sblueswir1 40075824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 40087c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 40097c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 40107c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 40117c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 40127c601803SMichael Tokarev " specified protocol and socket address\n" \ 40137c601803SMichael Tokarev "-incoming fd:fd\n" \ 40147c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 40157c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 40161597051bSDr. David Alan Gilbert " or from given external command\n" \ 40171597051bSDr. David Alan Gilbert "-incoming defer\n" \ 40181597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 4019ad96090aSBlue Swirl QEMU_ARCH_ALL) 40205824d651Sblueswir1STEXI 40217c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 4022f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 40236616b2adSStefan Weil@findex -incoming 40247c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 40257c601803SMichael Tokarev 40267c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 40277c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 40287c601803SMichael Tokarev 40297c601803SMichael Tokarev@item -incoming fd:@var{fd} 40307c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 40317c601803SMichael Tokarev 40327c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 40337c601803SMichael TokarevAccept incoming migration as an output from specified external command. 40341597051bSDr. David Alan Gilbert 40351597051bSDr. David Alan Gilbert@item -incoming defer 40361597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 40371597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 40381597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 40395824d651Sblueswir1ETEXI 40405824d651Sblueswir1 4041d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 4042d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 4043d15c05fcSAshijeet AcharyaSTEXI 4044d15c05fcSAshijeet Acharya@item -only-migratable 4045d15c05fcSAshijeet Acharya@findex -only-migratable 4046d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 4047d15c05fcSAshijeet Acharyaunmigratable state. 4048d15c05fcSAshijeet AcharyaETEXI 4049d15c05fcSAshijeet Acharya 4050d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 4051ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 4052d8c208ddSGerd HoffmannSTEXI 40533dbf2c7fSStefan Weil@item -nodefaults 40546616b2adSStefan Weil@findex -nodefaults 405566c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 405666c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 405766c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 405866c19bf1SMichal Novotnydefault devices. 4059d8c208ddSGerd HoffmannETEXI 4060d8c208ddSGerd Hoffmann 40615824d651Sblueswir1#ifndef _WIN32 40625824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 4063ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 4064ad96090aSBlue Swirl QEMU_ARCH_ALL) 40655824d651Sblueswir1#endif 40665824d651Sblueswir1STEXI 40674e257e5eSKevin Wolf@item -chroot @var{dir} 40686616b2adSStefan Weil@findex -chroot 40695824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 40705824d651Sblueswir1directory. Especially useful in combination with -runas. 40715824d651Sblueswir1ETEXI 40725824d651Sblueswir1 40735824d651Sblueswir1#ifndef _WIN32 40745824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 40752c42f1e8SIan Jackson "-runas user change to user id user just before starting the VM\n" \ 40762c42f1e8SIan Jackson " user can be numeric uid:gid instead\n", 4077ad96090aSBlue Swirl QEMU_ARCH_ALL) 40785824d651Sblueswir1#endif 40795824d651Sblueswir1STEXI 40804e257e5eSKevin Wolf@item -runas @var{user} 40816616b2adSStefan Weil@findex -runas 40825824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 40835824d651Sblueswir1to the specified user. 40845824d651Sblueswir1ETEXI 40855824d651Sblueswir1 40865824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 40875824d651Sblueswir1 "-prom-env variable=value\n" 4088ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 4089ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 409095d5f08bSStefan WeilSTEXI 409195d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 40926616b2adSStefan Weil@findex -prom-env 409395d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 409495d5f08bSStefan WeilETEXI 40955824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 4096f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 40973b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 4098413a99a9SSandra Loosemore QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 409995d5f08bSStefan WeilSTEXI 410095d5f08bSStefan Weil@item -semihosting 41016616b2adSStefan Weil@findex -semihosting 4102413a99a9SSandra LoosemoreEnable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only). 4103a38bb079SLiviu IonescuETEXI 4104a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 41054e7f9032SAlex Bennée "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \ 4106a59d31a1SLeon Alrae " semihosting configuration\n", 41073b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 4108413a99a9SSandra LoosemoreQEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 4109a38bb079SLiviu IonescuSTEXI 41104e7f9032SAlex Bennée@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]] 4111a38bb079SLiviu Ionescu@findex -semihosting-config 4112413a99a9SSandra LoosemoreEnable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only). 4113a59d31a1SLeon Alrae@table @option 4114a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 4115a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 4116a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 4117a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 41184e7f9032SAlex Bennée@item chardev=@var{str1} 41194e7f9032SAlex BennéeSend the output to a chardev backend output for native or auto output when not in gdb 4120a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 4121a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 4122a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 4123a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 4124a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 4125a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 4126a59d31a1SLeon Alrae@end table 412795d5f08bSStefan WeilETEXI 41285824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 4129ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 413095d5f08bSStefan WeilSTEXI 413195d5f08bSStefan Weil@item -old-param 41326616b2adSStefan Weil@findex -old-param (ARM) 413395d5f08bSStefan WeilOld param mode (ARM only). 413495d5f08bSStefan WeilETEXI 413595d5f08bSStefan Weil 41367d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 413773a1e647SEduardo Otubo "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 413824f8cdc5SEduardo Otubo " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 41392b716fa6SEduardo Otubo " Enable seccomp mode 2 system call filter (default 'off').\n" \ 41402b716fa6SEduardo Otubo " use 'obsolete' to allow obsolete system calls that are provided\n" \ 41412b716fa6SEduardo Otubo " by the kernel, but typically no longer used by modern\n" \ 414273a1e647SEduardo Otubo " C library implementations.\n" \ 414373a1e647SEduardo Otubo " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 414473a1e647SEduardo Otubo " its privileges by blacklisting all set*uid|gid system calls.\n" \ 414573a1e647SEduardo Otubo " The value 'children' will deny set*uid|gid system calls for\n" \ 4146995a226fSEduardo Otubo " main QEMU process but will allow forks and execves to run unprivileged\n" \ 4147995a226fSEduardo Otubo " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 414824f8cdc5SEduardo Otubo " blacklisting *fork and execve\n" \ 414924f8cdc5SEduardo Otubo " use 'resourcecontrol' to disable process affinity and schedular priority\n", 41507d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 41517d76ad4fSEduardo OtuboSTEXI 415224f8cdc5SEduardo Otubo@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 41537d76ad4fSEduardo Otubo@findex -sandbox 41547d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 41557d76ad4fSEduardo Otubodisable it. The default is 'off'. 41562b716fa6SEduardo Otubo@table @option 41572b716fa6SEduardo Otubo@item obsolete=@var{string} 41582b716fa6SEduardo OtuboEnable Obsolete system calls 415973a1e647SEduardo Otubo@item elevateprivileges=@var{string} 416073a1e647SEduardo OtuboDisable set*uid|gid system calls 4161995a226fSEduardo Otubo@item spawn=@var{string} 4162995a226fSEduardo OtuboDisable *fork and execve 416324f8cdc5SEduardo Otubo@item resourcecontrol=@var{string} 416424f8cdc5SEduardo OtuboDisable process affinity and schedular priority 41652b716fa6SEduardo Otubo@end table 41667d76ad4fSEduardo OtuboETEXI 41677d76ad4fSEduardo Otubo 4168715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 4169ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 41703dbf2c7fSStefan WeilSTEXI 41713dbf2c7fSStefan Weil@item -readconfig @var{file} 41726616b2adSStefan Weil@findex -readconfig 4173ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 4174ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 4175ed24cfacSMichal Novotnycharacter limit. 41763dbf2c7fSStefan WeilETEXI 4177715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 4178715a664aSGerd Hoffmann "-writeconfig <file>\n" 4179ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 41803dbf2c7fSStefan WeilSTEXI 41813dbf2c7fSStefan Weil@item -writeconfig @var{file} 41826616b2adSStefan Weil@findex -writeconfig 4183ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 4184ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 4185ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 41863dbf2c7fSStefan WeilETEXI 41872feac451SThomas Huth 4188f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 4189f29a5614SEduardo Habkost "-no-user-config\n" 41903478eae9SEduardo Habkost " do not load default user-provided config files at startup\n", 4191f29a5614SEduardo Habkost QEMU_ARCH_ALL) 4192f29a5614SEduardo HabkostSTEXI 4193f29a5614SEduardo Habkost@item -no-user-config 4194f29a5614SEduardo Habkost@findex -no-user-config 4195f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 41963478eae9SEduardo Habkostconfig files on @var{sysconfdir}. 4197292444cbSAnthony LiguoriETEXI 41982feac451SThomas Huth 4199ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 420010578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 420123d15e86SLluís " specify tracing options\n", 4202ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 4203ab6540d5SPrerna SaxenaSTEXI 420423d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 420523d15e86SLluísHXCOMM HX does not support conditional compilation of text. 4206e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 4207ab6540d5SPrerna Saxena@findex -trace 4208eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 4209ab6540d5SPrerna SaxenaETEXI 421042229a75SLluís VilanovaDEF("plugin", HAS_ARG, QEMU_OPTION_plugin, 421142229a75SLluís Vilanova "-plugin [file=]<file>[,arg=<string>]\n" 421242229a75SLluís Vilanova " load a plugin\n", 421342229a75SLluís Vilanova QEMU_ARCH_ALL) 421442229a75SLluís VilanovaSTEXI 421542229a75SLluís Vilanova@item -plugin file=@var{file}[,arg=@var{string}] 421642229a75SLluís Vilanova@findex -plugin 421742229a75SLluís Vilanova 421842229a75SLluís VilanovaLoad a plugin. 421942229a75SLluís Vilanova 422042229a75SLluís Vilanova@table @option 422142229a75SLluís Vilanova@item file=@var{file} 422242229a75SLluís VilanovaLoad the given plugin from a shared library file. 422342229a75SLluís Vilanova@item arg=@var{string} 422442229a75SLluís VilanovaArgument string passed to the plugin. (Can be given multiple times.) 422542229a75SLluís Vilanova@end table 422642229a75SLluís VilanovaETEXI 42273dbf2c7fSStefan Weil 422831e70d6cSMarkus ArmbrusterHXCOMM Internal use 422931e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 423031e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 4231c7f0f3b1SAnthony Liguori 42320f66998fSPaul Moore#ifdef __linux__ 42330f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 42340f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 42350f66998fSPaul Moore QEMU_ARCH_ALL) 42360f66998fSPaul Moore#endif 42370f66998fSPaul MooreSTEXI 42380f66998fSPaul Moore@item -enable-fips 42390f66998fSPaul Moore@findex -enable-fips 42400f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 42410f66998fSPaul MooreETEXI 42420f66998fSPaul Moore 4243976e8c54SThomas HuthHXCOMM Deprecated by -accel tcg 4244c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 4245a0dac021SJan Kiszka 42465e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 42475e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 4248deda497bSMarkus Armbruster " control error message format\n" 4249deda497bSMarkus Armbruster " timestamp=on enables timestamps (default: off)\n", 42505e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 42515e2ac519SSeiji AguchiSTEXI 42525e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 42535e2ac519SSeiji Aguchi@findex -msg 4254deda497bSMarkus ArmbrusterControl error message format. 4255deda497bSMarkus Armbruster@table @option 4256deda497bSMarkus Armbruster@item timestamp=on|off 4257deda497bSMarkus ArmbrusterPrefix messages with a timestamp. Default is off. 4258deda497bSMarkus Armbruster@end table 42595e2ac519SSeiji AguchiETEXI 42605e2ac519SSeiji Aguchi 4261abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 4262abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 4263abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 4264abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 4265abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 42662382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 4267abfd9ce3SAmit Shah QEMU_ARCH_ALL) 4268abfd9ce3SAmit ShahSTEXI 4269abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 4270abfd9ce3SAmit Shah@findex -dump-vmstate 4271abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 4272abfd9ce3SAmit Shahin @var{file} 4273abfd9ce3SAmit ShahETEXI 4274abfd9ce3SAmit Shah 427512df189dSEmilio G. CotaDEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, 427612df189dSEmilio G. Cota "-enable-sync-profile\n" 427712df189dSEmilio G. Cota " enable synchronization profiling\n", 427812df189dSEmilio G. Cota QEMU_ARCH_ALL) 427912df189dSEmilio G. CotaSTEXI 428012df189dSEmilio G. Cota@item -enable-sync-profile 428112df189dSEmilio G. Cota@findex -enable-sync-profile 428212df189dSEmilio G. CotaEnable synchronization profiling. 428312df189dSEmilio G. CotaETEXI 428412df189dSEmilio G. Cota 428543f187a5SPaolo BonziniSTEXI 428643f187a5SPaolo Bonzini@end table 428743f187a5SPaolo BonziniETEXI 428843f187a5SPaolo BonziniDEFHEADING() 4289de6b4f90SMarkus Armbruster 4290de6b4f90SMarkus ArmbrusterDEFHEADING(Generic object creation:) 429143f187a5SPaolo BonziniSTEXI 429243f187a5SPaolo Bonzini@table @option 429343f187a5SPaolo BonziniETEXI 4294b9174d4fSDaniel P. Berrange 4295b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 4296b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 4297b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 4298b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 4299b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 4300b9174d4fSDaniel P. Berrange " '/objects' path.\n", 4301b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 4302b9174d4fSDaniel P. BerrangeSTEXI 4303b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 4304b9174d4fSDaniel P. Berrange@findex -object 4305b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 4306b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 4307b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 4308b9174d4fSDaniel P. Berrange'/objects' path. 4309b9174d4fSDaniel P. Berrange 4310b9174d4fSDaniel P. Berrange@table @option 4311b9174d4fSDaniel P. Berrange 431298376843SHaozhong Zhang@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},align=@var{align} 4313b9174d4fSDaniel P. Berrange 4314b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 4315c7cddce1SStefan Hajnoczithe guest RAM with huge pages. 4316c7cddce1SStefan Hajnoczi 4317c7cddce1SStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 4318c7cddce1SStefan Hajnoczimemory region when configuring the @option{-numa} argument. 4319c7cddce1SStefan Hajnoczi 4320c7cddce1SStefan HajnocziThe @option{size} option provides the size of the memory region, and accepts 4321c7cddce1SStefan Hajnoczicommon suffixes, eg @option{500M}. 4322c7cddce1SStefan Hajnoczi 4323c7cddce1SStefan HajnocziThe @option{mem-path} provides the path to either a shared memory or huge page 4324c7cddce1SStefan Hajnoczifilesystem mount. 4325c7cddce1SStefan Hajnoczi 4326b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 4327b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 4328b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 4329c7cddce1SStefan Hajnoczi 433006329cceSMarcel ApfelbaumThe @option{share} is also required for pvrdma devices due to 433106329cceSMarcel Apfelbaumlimitations in the RDMA API provided by Linux. 433206329cceSMarcel Apfelbaum 433306329cceSMarcel ApfelbaumSetting share=on might affect the ability to configure NUMA 433406329cceSMarcel Apfelbaumbindings for the memory backend under some circumstances, see 433506329cceSMarcel ApfelbaumDocumentation/vm/numa_memory_policy.txt on the Linux kernel 433606329cceSMarcel Apfelbaumsource tree for additional details. 433706329cceSMarcel Apfelbaum 433811ae6ed8SEduardo HabkostSetting the @option{discard-data} boolean option to @var{on} 433911ae6ed8SEduardo Habkostindicates that file contents can be destroyed when QEMU exits, 434011ae6ed8SEduardo Habkostto avoid unnecessarily flushing data to the backing file. Note 434111ae6ed8SEduardo Habkostthat @option{discard-data} is only an optimization, and QEMU 434211ae6ed8SEduardo Habkostmight not discard file contents if it aborts unexpectedly or is 434311ae6ed8SEduardo Habkostterminated using SIGKILL. 4344b9174d4fSDaniel P. Berrange 4345c7cddce1SStefan HajnocziThe @option{merge} boolean option enables memory merge, also known as 4346c7cddce1SStefan HajnocziMADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 4347c7cddce1SStefan Hajnoczimemory deduplication. 4348c7cddce1SStefan Hajnoczi 4349c7cddce1SStefan HajnocziSetting the @option{dump} boolean option to @var{off} excludes the memory from 4350c7cddce1SStefan Hajnoczicore dumps. This feature is also known as MADV_DONTDUMP. 4351c7cddce1SStefan Hajnoczi 4352c7cddce1SStefan HajnocziThe @option{prealloc} boolean option enables memory preallocation. 4353c7cddce1SStefan Hajnoczi 4354c7cddce1SStefan HajnocziThe @option{host-nodes} option binds the memory range to a list of NUMA host 4355c7cddce1SStefan Hajnoczinodes. 4356c7cddce1SStefan Hajnoczi 4357c7cddce1SStefan HajnocziThe @option{policy} option sets the NUMA policy to one of the following values: 4358c7cddce1SStefan Hajnoczi 4359c7cddce1SStefan Hajnoczi@table @option 4360c7cddce1SStefan Hajnoczi@item @var{default} 4361c7cddce1SStefan Hajnoczidefault host policy 4362c7cddce1SStefan Hajnoczi 4363c7cddce1SStefan Hajnoczi@item @var{preferred} 4364c7cddce1SStefan Hajnocziprefer the given host node list for allocation 4365c7cddce1SStefan Hajnoczi 4366c7cddce1SStefan Hajnoczi@item @var{bind} 4367c7cddce1SStefan Hajnoczirestrict memory allocation to the given host node list 4368c7cddce1SStefan Hajnoczi 4369c7cddce1SStefan Hajnoczi@item @var{interleave} 4370c7cddce1SStefan Hajnocziinterleave memory allocations across the given host node list 4371c7cddce1SStefan Hajnoczi@end table 4372c7cddce1SStefan Hajnoczi 437398376843SHaozhong ZhangThe @option{align} option specifies the base address alignment when 437498376843SHaozhong ZhangQEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 437598376843SHaozhong Zhang@option{2M}. Some backend store specified by @option{mem-path} 437698376843SHaozhong Zhangrequires an alignment different than the default one used by QEMU, eg 437798376843SHaozhong Zhangthe device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 437898376843SHaozhong Zhangsuch cases, users can specify the required alignment via this option. 437998376843SHaozhong Zhang 4380a4de8552SJunyan HeThe @option{pmem} option specifies whether the backing file specified 4381a4de8552SJunyan Heby @option{mem-path} is in host persistent memory that can be accessed 4382a4de8552SJunyan Heusing the SNIA NVM programming model (e.g. Intel NVDIMM). 4383a4de8552SJunyan HeIf @option{pmem} is set to 'on', QEMU will take necessary operations to 4384a4de8552SJunyan Heguarantee the persistence of its own writes to @option{mem-path} 4385a4de8552SJunyan He(e.g. in vNVDIMM label emulation and live migration). 4386119906afSZhang YiAlso, we will map the backend-file with MAP_SYNC flag, which ensures the 4387119906afSZhang Yifile metadata is in sync for @option{mem-path} in case of host crash 4388119906afSZhang Yior a power failure. MAP_SYNC requires support from both the host kernel 4389119906afSZhang Yi(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted 4390119906afSZhang Yiwith DAX option. 4391a4de8552SJunyan He 439206329cceSMarcel Apfelbaum@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave} 4393cd19491aSStefan Hajnoczi 4394cd19491aSStefan HajnocziCreates a memory backend object, which can be used to back the guest RAM. 4395cd19491aSStefan HajnocziMemory backend objects offer more control than the @option{-m} option that is 4396cd19491aSStefan Hajnoczitraditionally used to define guest RAM. Please refer to 4397cd19491aSStefan Hajnoczi@option{memory-backend-file} for a description of the options. 4398cd19491aSStefan Hajnoczi 439936ea3979SMarc-André Lureau@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size} 4400dbb9e0f4SMarc-André Lureau 4401dbb9e0f4SMarc-André LureauCreates an anonymous memory file backend object, which allows QEMU to 4402dbb9e0f4SMarc-André Lureaushare the memory with an external process (e.g. when using 4403dbb9e0f4SMarc-André Lureauvhost-user). The memory is allocated with memfd and optional 4404dbb9e0f4SMarc-André Lureausealing. (Linux only) 4405dbb9e0f4SMarc-André Lureau 4406dbb9e0f4SMarc-André LureauThe @option{seal} option creates a sealed-file, that will block 4407dbb9e0f4SMarc-André Lureaufurther resizing the memory ('on' by default). 4408dbb9e0f4SMarc-André Lureau 4409dbb9e0f4SMarc-André LureauThe @option{hugetlb} option specify the file to be created resides in 4410dbb9e0f4SMarc-André Lureauthe hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 4411dbb9e0f4SMarc-André Lureauthe @option{hugetlb} option, the @option{hugetlbsize} option specify 4412dbb9e0f4SMarc-André Lureauthe hugetlb page size on systems that support multiple hugetlb page 4413dbb9e0f4SMarc-André Lureausizes (it must be a power of 2 value supported by the system). 4414dbb9e0f4SMarc-André Lureau 4415dbb9e0f4SMarc-André LureauIn some versions of Linux, the @option{hugetlb} option is incompatible 4416dbb9e0f4SMarc-André Lureauwith the @option{seal} option (requires at least Linux 4.16). 4417dbb9e0f4SMarc-André Lureau 4418dbb9e0f4SMarc-André LureauPlease refer to @option{memory-backend-file} for a description of the 4419dbb9e0f4SMarc-André Lureauother options. 4420dbb9e0f4SMarc-André Lureau 442136ea3979SMarc-André LureauThe @option{share} boolean option is @var{on} by default with memfd. 442236ea3979SMarc-André Lureau 44236c4e9d48SLaurent Vivier@item -object rng-builtin,id=@var{id} 44246c4e9d48SLaurent Vivier 44256c4e9d48SLaurent VivierCreates a random number generator backend which obtains entropy from 44266c4e9d48SLaurent VivierQEMU builtin functions. The @option{id} parameter is a unique ID that 44276c4e9d48SLaurent Vivierwill be used to reference this entropy backend from the @option{virtio-rng} 44280198c262SLaurent Vivierdevice. By default, the @option{virtio-rng} device uses this RNG backend. 44296c4e9d48SLaurent Vivier 4430b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4431b9174d4fSDaniel P. Berrange 4432b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4433b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 4434b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 4435b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 4436a2230bd7SKashyap Chamarthyentropy from and if omitted defaults to @option{/dev/urandom}. 4437b9174d4fSDaniel P. Berrange 4438b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4439b9174d4fSDaniel P. Berrange 4440b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4441b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 4442b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 4443b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 4444b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 4445b9174d4fSDaniel P. Berrangeto the RNG daemon. 4446b9174d4fSDaniel P. Berrange 4447e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4448e00adf6cSDaniel P. Berrange 4449e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 4450e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 4451e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 4452e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 4453e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 4454e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 4455e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 4456e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 4457e00adf6cSDaniel P. Berrange 4458e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 4459e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 4460e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 4461e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 4462e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 4463e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 4464e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 4465e00adf6cSDaniel P. Berrangeupfront and saved. 4466e00adf6cSDaniel P. Berrange 4467e1a6dc91SRichard W.M. Jones@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}] 4468e1a6dc91SRichard W.M. Jones 4469e1a6dc91SRichard W.M. JonesCreates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide 4470e1a6dc91SRichard W.M. JonesTLS support on network backends. The @option{id} parameter is a unique 4471e1a6dc91SRichard W.M. JonesID which network backends will use to access the credentials. The 4472e1a6dc91SRichard W.M. Jones@option{endpoint} is either @option{server} or @option{client} depending 4473e1a6dc91SRichard W.M. Joneson whether the QEMU network backend that uses the credentials will be 4474e1a6dc91SRichard W.M. Jonesacting as a client or as a server. For clients only, @option{username} 4475e1a6dc91SRichard W.M. Jonesis the username which will be sent to the server. If omitted 4476e1a6dc91SRichard W.M. Jonesit defaults to ``qemu''. 4477e1a6dc91SRichard W.M. Jones 4478e1a6dc91SRichard W.M. JonesThe @var{dir} parameter tells QEMU where to find the keys file. 4479e1a6dc91SRichard W.M. JonesIt is called ``@var{dir}/keys.psk'' and contains ``username:key'' 4480e1a6dc91SRichard W.M. Jonespairs. This file can most easily be created using the GnuTLS 4481e1a6dc91SRichard W.M. Jones@code{psktool} program. 4482e1a6dc91SRichard W.M. Jones 4483e1a6dc91SRichard W.M. JonesFor server endpoints, @var{dir} may also contain a file 4484e1a6dc91SRichard W.M. Jones@var{dh-params.pem} providing diffie-hellman parameters to use 4485e1a6dc91SRichard W.M. Jonesfor the TLS server. If the file is missing, QEMU will generate 4486e1a6dc91SRichard W.M. Jonesa set of DH parameters at startup. This is a computationally 4487e1a6dc91SRichard W.M. Jonesexpensive operation that consumes random pool entropy, so it is 4488e1a6dc91SRichard W.M. Jonesrecommended that a persistent set of parameters be generated 4489e1a6dc91SRichard W.M. Jonesup front and saved. 4490e1a6dc91SRichard W.M. Jones 449100e5e9dfSChristophe Fergeau@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id} 449285bcbc78SDaniel P. Berrange 449385bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 449485bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 449585bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 449685bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 449785bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 449885bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 449985bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 450085bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 450185bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 450285bcbc78SDaniel P. Berrange 450385bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 450485bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 450585bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 450685bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 450785bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 450885bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 450985bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 451085bcbc78SDaniel P. Berrangeupfront and saved. 451185bcbc78SDaniel P. Berrange 451285bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 451385bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 451485bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 451585bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 451685bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 451785bcbc78SDaniel P. Berrange 45181d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 45191d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 45201d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 45211d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 45221d7b5b4aSDaniel P. Berrangepassword for decryption. 45231d7b5b4aSDaniel P. Berrange 452400e5e9dfSChristophe FergeauThe @var{priority} parameter allows to override the global default 452500e5e9dfSChristophe Fergeaupriority used by gnutls. This can be useful if the system administrator 452600e5e9dfSChristophe Fergeauneeds to use a weaker set of crypto priorities for QEMU without 452700e5e9dfSChristophe Fergeaupotentially forcing the weakness onto all applications. Or conversely 452800e5e9dfSChristophe Fergeauif one wants wants a stronger default for QEMU than for all other 452900e5e9dfSChristophe Fergeauapplications, they can do this through this parameter. Its format is 453000e5e9dfSChristophe Fergeaua gnutls priority string as described at 453100e5e9dfSChristophe Fergeau@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 453200e5e9dfSChristophe Fergeau 4533338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 45347dbb11c8SYang Hongyang 45357dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 45367dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 45377dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 4538338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 4539338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 45407dbb11c8SYang Hongyang 45417dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 45427dbb11c8SYang Hongyang 45437dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 45447dbb11c8SYang Hongyang queue of the netdev (default). 45457dbb11c8SYang Hongyang 45467dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 45477dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 45487dbb11c8SYang Hongyang 45497dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 45507dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 45517dbb11c8SYang Hongyang 4552e2521f0eSZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4553f6d3afb5SZhang Chen 4554e2521f0eSZhang Chenfilter-mirror on netdev @var{netdevid},mirror net packet to chardev@var{chardevid}, if it has the vnet_hdr_support flag, filter-mirror will mirror packet with vnet_hdr_len. 4555f6d3afb5SZhang Chen 455600d5c240SZhang Chen@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4557d46f75b2SZhang Chen 4558d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 455900d5c240SZhang Chen@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 456000d5c240SZhang Chenfilter-redirector will redirect packet with vnet_hdr_len. 4561d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 4562d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 4563d46f75b2SZhang Chenneed to be specified. 4564d46f75b2SZhang Chen 45654b39bdceSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4566e6eee8abSZhang Chen 4567e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 4568e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 4569e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 45704b39bdceSZhang Chenclient.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4571e6eee8abSZhang Chen 4572e6eee8abSZhang Chenusage: 4573e6eee8abSZhang Chencolo secondary: 4574e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4575e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4576e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4577e6eee8abSZhang Chen 4578c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4579d3e0c032SThomas Huth 4580d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 4581d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4582d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 4583d3e0c032SThomas Huthor Wireshark. 4584d3e0c032SThomas Huth 4585cf6af766SZhang Chen@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid},iothread=@var{id}[,vnet_hdr_support][,notify_dev=@var{id}] 45867dce4e6fSZhang Chen 45877dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 45887dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 45897dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 45907dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 45915aede7f4SZhang ChenIn order to improve efficiency, we need to put the task of comparison 45925aede7f4SZhang Chenin another thread. If it has the vnet_hdr_support flag, colo compare 45935aede7f4SZhang Chenwill send/recv packet with vnet_hdr_len. 4594cf6af766SZhang ChenIf you want to use Xen COLO, will need the notify_dev to notify Xen 4595cf6af766SZhang Chencolo-frame to do checkpoint. 45967dce4e6fSZhang Chen 45977dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 45987dce4e6fSZhang Chen 45997dce4e6fSZhang Chen@example 46007dce4e6fSZhang Chen 4601cf6af766SZhang ChenKVM COLO 4602cf6af766SZhang Chen 46037dce4e6fSZhang Chenprimary: 46047dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 46057dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 46067dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 46077dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 46087dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 46097dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 46107dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 46117dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 46125aede7f4SZhang Chen-object iothread,id=iothread1 46137dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 46147dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 46157dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 46165aede7f4SZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 46177dce4e6fSZhang Chen 46187dce4e6fSZhang Chensecondary: 46197dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 46207dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 46217dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 46227dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 46237dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 46247dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 46257dce4e6fSZhang Chen 4626cf6af766SZhang Chen 4627cf6af766SZhang ChenXen COLO 4628cf6af766SZhang Chen 4629cf6af766SZhang Chenprimary: 4630cf6af766SZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 4631cf6af766SZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 4632cf6af766SZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 4633cf6af766SZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 4634cf6af766SZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 4635cf6af766SZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 4636cf6af766SZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 4637cf6af766SZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 4638cf6af766SZhang Chen-chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait 4639cf6af766SZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 4640cf6af766SZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 4641cf6af766SZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 4642cf6af766SZhang Chen-object iothread,id=iothread1 4643cf6af766SZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 4644cf6af766SZhang Chen 4645cf6af766SZhang Chensecondary: 4646cf6af766SZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 4647cf6af766SZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 4648cf6af766SZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 4649cf6af766SZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 4650cf6af766SZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4651cf6af766SZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4652cf6af766SZhang Chen 46537dce4e6fSZhang Chen@end example 46547dce4e6fSZhang Chen 46557dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 46567dce4e6fSZhang Chenthe colo-compare git log. 46577dce4e6fSZhang Chen 46581653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 46591653a5f3SGonglei 46601653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 46611653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 46621653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 46631653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 46641653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 46651653a5f3SGonglei@var{queues} is 1. 46661653a5f3SGonglei 46671653a5f3SGonglei@example 46681653a5f3SGonglei 4669664785acSThomas Huth # @value{qemu_system} \ 46701653a5f3SGonglei [...] \ 46711653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 46721653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 46731653a5f3SGonglei [...] 46741653a5f3SGonglei@end example 46751653a5f3SGonglei 4676042cea27SGonglei@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 4677042cea27SGonglei 4678042cea27SGongleiCreates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 4679042cea27SGongleiThe @var{id} parameter is a unique ID that will be used to reference this 4680042cea27SGongleicryptodev backend from the @option{virtio-crypto} device. 4681042cea27SGongleiThe chardev should be a unix domain socket backed one. The vhost-user uses 4682042cea27SGongleia specifically defined protocol to pass vhost ioctl replacement messages 4683042cea27SGongleito an application on the other end of the socket. 4684042cea27SGongleiThe @var{queues} parameter is optional, which specify the queue number 4685042cea27SGongleiof cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 4686042cea27SGonglei 4687042cea27SGonglei@example 4688042cea27SGonglei 4689664785acSThomas Huth # @value{qemu_system} \ 4690042cea27SGonglei [...] \ 4691042cea27SGonglei -chardev socket,id=chardev0,path=/path/to/socket \ 4692042cea27SGonglei -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 4693042cea27SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4694042cea27SGonglei [...] 4695042cea27SGonglei@end example 4696042cea27SGonglei 4697ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4698ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4699ac1d8878SDaniel P. Berrange 4700ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4701ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4702ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4703ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4704ac1d8878SDaniel P. Berrange 4705ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4706ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4707ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4708ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4709ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4710ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4711ac1d8878SDaniel P. Berrange 4712ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4713ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4714ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4715ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4716ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4717ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4718ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 471969c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4720ac1d8878SDaniel P. Berrange 4721ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4722ac1d8878SDaniel P. Berrange 4723ac1d8878SDaniel P. Berrange@example 4724ac1d8878SDaniel P. Berrange 4725664785acSThomas Huth # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw 4726ac1d8878SDaniel P. Berrange 4727ac1d8878SDaniel P. Berrange@end example 4728ac1d8878SDaniel P. Berrange 4729ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4730ac1d8878SDaniel P. Berrange 4731b43671f8SEric Blake # printf "letmein" > mypasswd.txt 4732664785acSThomas Huth # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw 4733ac1d8878SDaniel P. Berrange 4734ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4735ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4736ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4737ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4738ac1d8878SDaniel P. Berrange 4739ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4740ac1d8878SDaniel P. Berrange 4741ac1d8878SDaniel P. Berrange@example 4742ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4743ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4744ac1d8878SDaniel P. Berrange@end example 4745ac1d8878SDaniel P. Berrange 4746ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4747ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4748ac1d8878SDaniel P. Berrange 4749ac1d8878SDaniel P. Berrange@example 4750ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4751ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4752ac1d8878SDaniel P. Berrange@end example 4753ac1d8878SDaniel P. Berrange 4754ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4755ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4756ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4757ac1d8878SDaniel P. Berrange 4758ac1d8878SDaniel P. Berrange@example 4759b43671f8SEric Blake # SECRET=$(printf "letmein" | 4760ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4761ac1d8878SDaniel P. Berrange@end example 4762ac1d8878SDaniel P. Berrange 4763ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4764ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4765ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4766ac1d8878SDaniel P. Berrange 4767ac1d8878SDaniel P. Berrange@example 4768664785acSThomas Huth # @value{qemu_system} \ 4769ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4770ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4771ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4772ac1d8878SDaniel P. Berrange@end example 4773ac1d8878SDaniel P. Berrange 4774a9b4942fSBrijesh Singh@item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}] 4775a9b4942fSBrijesh Singh 4776a9b4942fSBrijesh SinghCreate a Secure Encrypted Virtualization (SEV) guest object, which can be used 4777a9b4942fSBrijesh Singhto provide the guest memory encryption support on AMD processors. 4778a9b4942fSBrijesh Singh 4779a9b4942fSBrijesh SinghWhen memory encryption is enabled, one of the physical address bit (aka the 4780a9b4942fSBrijesh SinghC-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 4781a9b4942fSBrijesh Singhis used to provide the C-bit position. The C-bit position is Host family dependent 4782a9b4942fSBrijesh Singhhence user must provide this value. On EPYC, the value should be 47. 4783a9b4942fSBrijesh Singh 4784a9b4942fSBrijesh SinghWhen memory encryption is enabled, we loose certain bits in physical address space. 4785a9b4942fSBrijesh SinghThe @option{reduced-phys-bits} is used to provide the number of bits we loose in 4786a9b4942fSBrijesh Singhphysical address space. Similar to C-bit, the value is Host family dependent. 4787a9b4942fSBrijesh SinghOn EPYC, the value should be 5. 4788a9b4942fSBrijesh Singh 4789a9b4942fSBrijesh SinghThe @option{sev-device} provides the device file to use for communicating with 4790a9b4942fSBrijesh Singhthe SEV firmware running inside AMD Secure Processor. The default device is 4791a9b4942fSBrijesh Singh'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 4792a9b4942fSBrijesh Singhcreated by CCP driver. 4793a9b4942fSBrijesh Singh 4794a9b4942fSBrijesh SinghThe @option{policy} provides the guest policy to be enforced by the SEV firmware 4795a9b4942fSBrijesh Singhand restrict what configuration and operational commands can be performed on this 4796a9b4942fSBrijesh Singhguest by the hypervisor. The policy should be provided by the guest owner and is 4797a9b4942fSBrijesh Singhbound to the guest and cannot be changed throughout the lifetime of the guest. 4798a9b4942fSBrijesh SinghThe default is 0. 4799a9b4942fSBrijesh Singh 4800a9b4942fSBrijesh SinghIf guest @option{policy} allows sharing the key with another SEV guest then 4801a9b4942fSBrijesh Singh@option{handle} can be use to provide handle of the guest from which to share 4802a9b4942fSBrijesh Singhthe key. 4803a9b4942fSBrijesh Singh 4804a9b4942fSBrijesh SinghThe @option{dh-cert-file} and @option{session-file} provides the guest owner's 4805a9b4942fSBrijesh SinghPublic Diffie-Hillman key defined in SEV spec. The PDH and session parameters 4806a9b4942fSBrijesh Singhare used for establishing a cryptographic session with the guest owner to 4807a9b4942fSBrijesh Singhnegotiate keys used for attestation. The file must be encoded in base64. 4808a9b4942fSBrijesh Singh 4809a9b4942fSBrijesh Singhe.g to launch a SEV guest 4810a9b4942fSBrijesh Singh@example 4811664785acSThomas Huth # @value{qemu_system_x86} \ 4812a9b4942fSBrijesh Singh ...... 4813a9b4942fSBrijesh Singh -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 4814a9b4942fSBrijesh Singh -machine ...,memory-encryption=sev0 4815a9b4942fSBrijesh Singh ..... 4816a9b4942fSBrijesh Singh 4817a9b4942fSBrijesh Singh@end example 4818fb5c4ebcSDaniel P. Berrangé 4819fb5c4ebcSDaniel P. Berrangé 4820fb5c4ebcSDaniel P. Berrangé@item -object authz-simple,id=@var{id},identity=@var{string} 4821fb5c4ebcSDaniel P. Berrangé 4822fb5c4ebcSDaniel P. BerrangéCreate an authorization object that will control access to network services. 4823fb5c4ebcSDaniel P. Berrangé 4824fb5c4ebcSDaniel P. BerrangéThe @option{identity} parameter is identifies the user and its format 4825fb5c4ebcSDaniel P. Berrangédepends on the network service that authorization object is associated 4826fb5c4ebcSDaniel P. Berrangéwith. For authorizing based on TLS x509 certificates, the identity must 4827fb5c4ebcSDaniel P. Berrangébe the x509 distinguished name. Note that care must be taken to escape 4828fb5c4ebcSDaniel P. Berrangéany commas in the distinguished name. 4829fb5c4ebcSDaniel P. Berrangé 4830fb5c4ebcSDaniel P. BerrangéAn example authorization object to validate a x509 distinguished name 4831fb5c4ebcSDaniel P. Berrangéwould look like: 4832fb5c4ebcSDaniel P. Berrangé@example 4833664785acSThomas Huth # @value{qemu_system} \ 4834fb5c4ebcSDaniel P. Berrangé ... 4835fb5c4ebcSDaniel P. Berrangé -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \ 4836fb5c4ebcSDaniel P. Berrangé ... 4837fb5c4ebcSDaniel P. Berrangé@end example 4838fb5c4ebcSDaniel P. Berrangé 4839fb5c4ebcSDaniel P. BerrangéNote the use of quotes due to the x509 distinguished name containing 4840fb5c4ebcSDaniel P. Berrangéwhitespace, and escaping of ','. 4841fb5c4ebcSDaniel P. Berrangé 484255d86984SDaniel P. Berrangé@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no} 484355d86984SDaniel P. Berrangé 484455d86984SDaniel P. BerrangéCreate an authorization object that will control access to network services. 484555d86984SDaniel P. Berrangé 484655d86984SDaniel P. BerrangéThe @option{filename} parameter is the fully qualified path to a file 484755d86984SDaniel P. Berrangécontaining the access control list rules in JSON format. 484855d86984SDaniel P. Berrangé 484955d86984SDaniel P. BerrangéAn example set of rules that match against SASL usernames might look 485055d86984SDaniel P. Berrangélike: 485155d86984SDaniel P. Berrangé 485255d86984SDaniel P. Berrangé@example 485355d86984SDaniel P. Berrangé @{ 485455d86984SDaniel P. Berrangé "rules": [ 485555d86984SDaniel P. Berrangé @{ "match": "fred", "policy": "allow", "format": "exact" @}, 485655d86984SDaniel P. Berrangé @{ "match": "bob", "policy": "allow", "format": "exact" @}, 485755d86984SDaniel P. Berrangé @{ "match": "danb", "policy": "deny", "format": "glob" @}, 485855d86984SDaniel P. Berrangé @{ "match": "dan*", "policy": "allow", "format": "exact" @}, 485955d86984SDaniel P. Berrangé ], 486055d86984SDaniel P. Berrangé "policy": "deny" 486155d86984SDaniel P. Berrangé @} 486255d86984SDaniel P. Berrangé@end example 486355d86984SDaniel P. Berrangé 486455d86984SDaniel P. BerrangéWhen checking access the object will iterate over all the rules and 486555d86984SDaniel P. Berrangéthe first rule to match will have its @option{policy} value returned 486655d86984SDaniel P. Berrangéas the result. If no rules match, then the default @option{policy} 486755d86984SDaniel P. Berrangévalue is returned. 486855d86984SDaniel P. Berrangé 486955d86984SDaniel P. BerrangéThe rules can either be an exact string match, or they can use the 487055d86984SDaniel P. Berrangésimple UNIX glob pattern matching to allow wildcards to be used. 487155d86984SDaniel P. Berrangé 487255d86984SDaniel P. BerrangéIf @option{refresh} is set to true the file will be monitored 487355d86984SDaniel P. Berrangéand automatically reloaded whenever its content changes. 487455d86984SDaniel P. Berrangé 487555d86984SDaniel P. BerrangéAs with the @code{authz-simple} object, the format of the identity 487655d86984SDaniel P. Berrangéstrings being matched depends on the network service, but is usually 487755d86984SDaniel P. Berrangéa TLS x509 distinguished name, or a SASL username. 487855d86984SDaniel P. Berrangé 487955d86984SDaniel P. BerrangéAn example authorization object to validate a SASL username 488055d86984SDaniel P. Berrangéwould look like: 488155d86984SDaniel P. Berrangé@example 4882664785acSThomas Huth # @value{qemu_system} \ 488355d86984SDaniel P. Berrangé ... 488455d86984SDaniel P. Berrangé -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes 488555d86984SDaniel P. Berrangé ... 488655d86984SDaniel P. Berrangé@end example 488755d86984SDaniel P. Berrangé 48888953caf3SDaniel P. Berrange@item -object authz-pam,id=@var{id},service=@var{string} 48898953caf3SDaniel P. Berrange 48908953caf3SDaniel P. BerrangeCreate an authorization object that will control access to network services. 48918953caf3SDaniel P. Berrange 48928953caf3SDaniel P. BerrangeThe @option{service} parameter provides the name of a PAM service to use 48938953caf3SDaniel P. Berrangefor authorization. It requires that a file @code{/etc/pam.d/@var{service}} 48948953caf3SDaniel P. Berrangeexist to provide the configuration for the @code{account} subsystem. 48958953caf3SDaniel P. Berrange 48968953caf3SDaniel P. BerrangeAn example authorization object to validate a TLS x509 distinguished 48978953caf3SDaniel P. Berrangename would look like: 48988953caf3SDaniel P. Berrange 48998953caf3SDaniel P. Berrange@example 4900664785acSThomas Huth # @value{qemu_system} \ 49018953caf3SDaniel P. Berrange ... 49028953caf3SDaniel P. Berrange -object authz-pam,id=auth0,service=qemu-vnc 49038953caf3SDaniel P. Berrange ... 49048953caf3SDaniel P. Berrange@end example 49058953caf3SDaniel P. Berrange 49068953caf3SDaniel P. BerrangeThere would then be a corresponding config file for PAM at 49078953caf3SDaniel P. Berrange@code{/etc/pam.d/qemu-vnc} that contains: 49088953caf3SDaniel P. Berrange 49098953caf3SDaniel P. Berrange@example 49108953caf3SDaniel P. Berrangeaccount requisite pam_listfile.so item=user sense=allow \ 49118953caf3SDaniel P. Berrange file=/etc/qemu/vnc.allow 49128953caf3SDaniel P. Berrange@end example 49138953caf3SDaniel P. Berrange 49148953caf3SDaniel P. BerrangeFinally the @code{/etc/qemu/vnc.allow} file would contain 49158953caf3SDaniel P. Berrangethe list of x509 distingished names that are permitted 49168953caf3SDaniel P. Berrangeaccess 49178953caf3SDaniel P. Berrange 49188953caf3SDaniel P. Berrange@example 49198953caf3SDaniel P. BerrangeCN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB 49208953caf3SDaniel P. Berrange@end example 49218953caf3SDaniel P. Berrange 492286d2a49bSStefan Hajnoczi@item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink} 492386d2a49bSStefan Hajnoczi 492486d2a49bSStefan HajnocziCreates a dedicated event loop thread that devices can be assigned to. This is 492586d2a49bSStefan Hajnocziknown as an IOThread. By default device emulation happens in vCPU threads or 492686d2a49bSStefan Hajnoczithe main event loop thread. This can become a scalability bottleneck. 492786d2a49bSStefan HajnocziIOThreads allow device emulation and I/O to run on other host CPUs. 492886d2a49bSStefan Hajnoczi 492986d2a49bSStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 493086d2a49bSStefan HajnocziIOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be 493186d2a49bSStefan Hajnocziassigned to an IOThread. Note that not all devices support an 493286d2a49bSStefan Hajnoczi@option{iothread} parameter. 493386d2a49bSStefan Hajnoczi 493486d2a49bSStefan HajnocziThe @code{query-iothreads} QMP command lists IOThreads and reports their thread 493586d2a49bSStefan HajnocziIDs so that the user can configure host CPU pinning/affinity. 493686d2a49bSStefan Hajnoczi 493786d2a49bSStefan HajnocziIOThreads use an adaptive polling algorithm to reduce event loop latency. 493886d2a49bSStefan HajnocziInstead of entering a blocking system call to monitor file descriptors and then 493986d2a49bSStefan Hajnoczipay the cost of being woken up when an event occurs, the polling algorithm 494086d2a49bSStefan Hajnoczispins waiting for events for a short time. The algorithm's default parameters 494186d2a49bSStefan Hajnocziare suitable for many cases but can be adjusted based on knowledge of the 494286d2a49bSStefan Hajnocziworkload and/or host device latency. 494386d2a49bSStefan Hajnoczi 494486d2a49bSStefan HajnocziThe @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy 494586d2a49bSStefan Hajnocziwait for events. Polling can be disabled by setting this value to 0. 494686d2a49bSStefan Hajnoczi 494786d2a49bSStefan HajnocziThe @option{poll-grow} parameter is the multiplier used to increase the polling 494886d2a49bSStefan Hajnoczitime when the algorithm detects it is missing events due to not polling long 494986d2a49bSStefan Hajnoczienough. 495086d2a49bSStefan Hajnoczi 495186d2a49bSStefan HajnocziThe @option{poll-shrink} parameter is the divisor used to decrease the polling 495286d2a49bSStefan Hajnoczitime when the algorithm detects it is spending too long polling without 495386d2a49bSStefan Hajnocziencountering events. 495486d2a49bSStefan Hajnoczi 495586d2a49bSStefan HajnocziThe polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}): 495686d2a49bSStefan Hajnoczi 495786d2a49bSStefan Hajnoczi@example 495886d2a49bSStefan Hajnoczi(qemu) qom-set /objects/iothread1 poll-max-ns 100000 495986d2a49bSStefan Hajnoczi@end example 49608953caf3SDaniel P. Berrange 4961b9174d4fSDaniel P. Berrange@end table 4962b9174d4fSDaniel P. Berrange 4963b9174d4fSDaniel P. BerrangeETEXI 4964b9174d4fSDaniel P. Berrange 4965b9174d4fSDaniel P. Berrange 49663dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 49673dbf2c7fSStefan WeilSTEXI 49683dbf2c7fSStefan Weil@end table 49693dbf2c7fSStefan WeilETEXI 4970