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" 3532c18a2dSMatt Gingell " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n" 36d1048befSDon Slutz " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 3796404013SPeter Maydell " kvm_shadow_mem=size of KVM shadow MMU in bytes\n" 388490fc78SLuiz Capitulino " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 39a52a7fdfSLe Tan " mem-merge=on|off controls memory merge support (default: on)\n" 4079814179STiejun Chen " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n" 412eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 429850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4387252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 44902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 45274250c3SXiao Feng Ren " enforce-config-section=on|off enforce configuration section migration (default=off)\n" 46db588194SBrijesh Singh " memory-encryption=@var{} memory encryption object to use (default=none)\n", 4780f52a66SJan Kiszka QEMU_ARCH_ALL) 485824d651Sblueswir1STEXI 4980f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 5080f52a66SJan Kiszka@findex -machine 51585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 528bfce83aSDaniel P. Berrangeavailable machines. 538bfce83aSDaniel P. Berrange 548bfce83aSDaniel P. BerrangeFor architectures which aim to support live migration compatibility 558bfce83aSDaniel P. Berrangeacross releases, each release will introduce a new versioned machine 568bfce83aSDaniel P. Berrangetype. For example, the 2.8.0 release introduced machine types 578bfce83aSDaniel P. Berrange``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 588bfce83aSDaniel P. Berrange 598bfce83aSDaniel P. BerrangeTo allow live migration of guests from QEMU version 2.8.0, to QEMU 608bfce83aSDaniel P. Berrangeversion 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 618bfce83aSDaniel P. Berrangeand ``pc-q35-2.8'' machines too. To allow users live migrating VMs 628bfce83aSDaniel P. Berrangeto skip multiple intermediate releases when upgrading, new releases 638bfce83aSDaniel P. Berrangeof QEMU will support machine types from many previous versions. 648bfce83aSDaniel P. Berrange 658bfce83aSDaniel P. BerrangeSupported machine properties are: 6680f52a66SJan Kiszka@table @option 6780f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 6880f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 69d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 70bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 71bde4d920SThomas Huthfails to initialize. 726a48ffaaSJan Kiszka@item kernel_irqchip=on|off 7332c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 7479814179STiejun Chen@item gfx_passthru=on|off 7579814179STiejun ChenEnables IGD GFX passthrough support for the chosen machine when available. 76d1048befSDon Slutz@item vmport=on|off|auto 77d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 78d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 79d1048befSDon Slutzis on. 8039d6960aSJan Kiszka@item kvm_shadow_mem=size 8139d6960aSJan KiszkaDefines the size of the KVM shadow MMU. 82ddb97f1dSJason Baron@item dump-guest-core=on|off 83ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 848490fc78SLuiz Capitulino@item mem-merge=on|off 858490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 868490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 878490fc78SLuiz Capitulino(enabled by default). 882eb1cd07STony Krowiak@item aes-key-wrap=on|off 892eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 902eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 912eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 922eb1cd07STony Krowiak@item dea-key-wrap=on|off 932eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 942eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 952eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 9687252e1bSXiao Guangrong@item nvdimm=on|off 9787252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 9816f72448SPeter Xu@item enforce-config-section=on|off 9916f72448SPeter XuIf @option{enforce-config-section} is set to @var{on}, force migration 10016f72448SPeter Xucode to send configuration section even if the machine-type sets the 10116f72448SPeter Xu@option{migration.send-configuration} property to @var{off}. 10216f72448SPeter XuNOTE: this parameter is deprecated. Please use @option{-global} 10316f72448SPeter Xu@option{migration.send-configuration}=@var{on|off} instead. 104db588194SBrijesh Singh@item memory-encryption=@var{} 105db588194SBrijesh SinghMemory encryption object to use. The default is none. 10680f52a66SJan Kiszka@end table 1075824d651Sblueswir1ETEXI 1085824d651Sblueswir1 10980f52a66SJan KiszkaHXCOMM Deprecated by -machine 11080f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 11180f52a66SJan Kiszka 1125824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 113585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 1145824d651Sblueswir1STEXI 1155824d651Sblueswir1@item -cpu @var{model} 1166616b2adSStefan Weil@findex -cpu 117585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 1185824d651Sblueswir1ETEXI 1195824d651Sblueswir1 1208d4e9146SKONRAD FredericDEF("accel", HAS_ARG, QEMU_OPTION_accel, 1218d4e9146SKONRAD Frederic "-accel [accel=]accelerator[,thread=single|multi]\n" 122d661d9a4SJustin Terry (VM) " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n" 1230b3c5c81SEduardo Habkost " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL) 1248d4e9146SKONRAD FredericSTEXI 1258d4e9146SKONRAD Frederic@item -accel @var{name}[,prop=@var{value}[,...]] 1268d4e9146SKONRAD Frederic@findex -accel 1278d4e9146SKONRAD FredericThis is used to enable an accelerator. Depending on the target architecture, 128d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 129bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 130bde4d920SThomas Huthfails to initialize. 1318d4e9146SKONRAD Frederic@table @option 1328d4e9146SKONRAD Frederic@item thread=single|multi 1338d4e9146SKONRAD FredericControls number of TCG threads. When the TCG is multi-threaded there will be one 1348d4e9146SKONRAD Fredericthread per vCPU therefor taking advantage of additional host cores. The default 1358d4e9146SKONRAD Fredericis to enable multi-threading where both the back-end and front-ends support it and 1368d4e9146SKONRAD Fredericno incompatible TCG features have been enabled (e.g. icount/replay). 1378d4e9146SKONRAD Frederic@end table 1388d4e9146SKONRAD FredericETEXI 1398d4e9146SKONRAD Frederic 1405824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 1411b458422SLike Xu "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n" 1426be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1436be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 144ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 1451b458422SLike Xu " cores= number of CPU cores on one socket (for PC, it's on one die)\n" 14658a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 1471b458422SLike Xu " dies= number of CPU dies on one socket (for PC only)\n" 148ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 149ad96090aSBlue Swirl QEMU_ARCH_ALL) 1505824d651Sblueswir1STEXI 1511b458422SLike Xu@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1526616b2adSStefan Weil@findex -smp 1535824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1545824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1555824d651Sblueswir1to 4. 1561b458422SLike XuFor the PC target, the number of @var{cores} per die, the number of @var{threads} 1571b458422SLike Xuper cores, the number of @var{dies} per packages and the total number of 1581b458422SLike Xu@var{sockets} can be specified. Missing values will be computed. 1591b458422SLike XuIf any on the three values is given, the total number of CPUs @var{n} can be omitted. 1601b458422SLike Xu@var{maxcpus} specifies the maximum number of hotpluggable CPUs. 1615824d651Sblueswir1ETEXI 1625824d651Sblueswir1 163268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 164e0ee9fd0SEduardo Habkost "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1650f203430SHe Chen "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1662d19c656SIgor Mammedov "-numa dist,src=source,dst=destination,val=distance\n" 1672d19c656SIgor Mammedov "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n", 1682d19c656SIgor Mammedov QEMU_ARCH_ALL) 169268a362cSaliguoriSTEXI 170e0ee9fd0SEduardo Habkost@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 171e0ee9fd0SEduardo Habkost@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 1720f203430SHe Chen@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 173419fcdecSIgor Mammedov@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 1746616b2adSStefan Weil@findex -numa 1754b9a5dd7SEduardo HabkostDefine a NUMA node and assign RAM and VCPUs to it. 1760f203430SHe ChenSet the NUMA distance from a source node to a destination node. 1777febe36fSPaolo Bonzini 178419fcdecSIgor MammedovLegacy VCPU assignment uses @samp{cpus} option where 1794b9a5dd7SEduardo Habkost@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 1804b9a5dd7SEduardo Habkost@samp{cpus} option represent a contiguous range of CPU indexes 1814b9a5dd7SEduardo Habkost(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 1824b9a5dd7SEduardo Habkostset of VCPUs can be represented by providing multiple @samp{cpus} 1834b9a5dd7SEduardo Habkostoptions. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 1844b9a5dd7SEduardo Habkostsplit between them. 1854b9a5dd7SEduardo Habkost 1864b9a5dd7SEduardo HabkostFor example, the following option assigns VCPUs 0, 1, 2 and 5 to 1874b9a5dd7SEduardo Habkosta NUMA node: 1884b9a5dd7SEduardo Habkost@example 1894b9a5dd7SEduardo Habkost-numa node,cpus=0-2,cpus=5 1904b9a5dd7SEduardo Habkost@end example 1914b9a5dd7SEduardo Habkost 192419fcdecSIgor Mammedov@samp{cpu} option is a new alternative to @samp{cpus} option 193419fcdecSIgor Mammedovwhich uses @samp{socket-id|core-id|thread-id} properties to assign 194419fcdecSIgor MammedovCPU objects to a @var{node} using topology layout properties of CPU. 195419fcdecSIgor MammedovThe set of properties is machine specific, and depends on used 196419fcdecSIgor Mammedovmachine type/@samp{smp} options. It could be queried with 197419fcdecSIgor Mammedov@samp{hotpluggable-cpus} monitor command. 198419fcdecSIgor Mammedov@samp{node-id} property specifies @var{node} to which CPU object 199419fcdecSIgor Mammedovwill be assigned, it's required for @var{node} to be declared 200419fcdecSIgor Mammedovwith @samp{node} option before it's used with @samp{cpu} option. 201419fcdecSIgor Mammedov 202419fcdecSIgor MammedovFor example: 203419fcdecSIgor Mammedov@example 204419fcdecSIgor Mammedov-M pc \ 205419fcdecSIgor Mammedov-smp 1,sockets=2,maxcpus=2 \ 206419fcdecSIgor Mammedov-numa node,nodeid=0 -numa node,nodeid=1 \ 207419fcdecSIgor Mammedov-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 208419fcdecSIgor Mammedov@end example 209419fcdecSIgor Mammedov 2104b9a5dd7SEduardo Habkost@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 2114b9a5dd7SEduardo Habkostassigns RAM from a given memory backend device to a node. If 2124b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 2134b9a5dd7SEduardo Habkostsplit equally between them. 2144b9a5dd7SEduardo Habkost 2154b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 2164b9a5dd7SEduardo Habkostif one node uses @samp{memdev}, all of them have to use it. 2174b9a5dd7SEduardo Habkost 2180f203430SHe Chen@var{source} and @var{destination} are NUMA node IDs. 2190f203430SHe Chen@var{distance} is the NUMA distance from @var{source} to @var{destination}. 2200f203430SHe ChenThe distance from a node to itself is always 10. If any pair of nodes is 2210f203430SHe Chengiven a distance, then all pairs must be given distances. Although, when 2220f203430SHe Chendistances are only given in one direction for each pair of nodes, then 2230f203430SHe Chenthe distances in the opposite directions are assumed to be the same. If, 2240f203430SHe Chenhowever, an asymmetrical pair of distances is given for even one node 2250f203430SHe Chenpair, then all node pairs must be provided distance values for both 2260f203430SHe Chendirections, even when they are symmetrical. When a node is unreachable 2270f203430SHe Chenfrom another node, set the pair's distance to 255. 2280f203430SHe Chen 2294b9a5dd7SEduardo HabkostNote that the -@option{numa} option doesn't allocate any of the 2304b9a5dd7SEduardo Habkostspecified resources, it just assigns existing resources to NUMA 2314b9a5dd7SEduardo Habkostnodes. This means that one still has to use the @option{-m}, 2324b9a5dd7SEduardo Habkost@option{-smp} options to allocate RAM and VCPUs respectively. 2334b9a5dd7SEduardo Habkost 234268a362cSaliguoriETEXI 235268a362cSaliguori 23610adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 23710adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 23810adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 23910adb8beSMarkus ArmbrusterSTEXI 24010adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 24110adb8beSMarkus Armbruster@findex -add-fd 24210adb8beSMarkus Armbruster 24310adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 24410adb8beSMarkus Armbruster 24510adb8beSMarkus Armbruster@table @option 24610adb8beSMarkus Armbruster@item fd=@var{fd} 24710adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 24810adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 24910adb8beSMarkus Armbruster@item set=@var{set} 25010adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 25110adb8beSMarkus Armbruster@item opaque=@var{opaque} 25210adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 25310adb8beSMarkus Armbruster@end table 25410adb8beSMarkus Armbruster 25510adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 25610adb8beSMarkus Armbruster@example 257664785acSThomas Huth@value{qemu_system} \ 258664785acSThomas Huth -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 259664785acSThomas Huth -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 26010adb8beSMarkus Armbruster -drive file=/dev/fdset/2,index=0,media=disk 26110adb8beSMarkus Armbruster@end example 26210adb8beSMarkus ArmbrusterETEXI 26310adb8beSMarkus Armbruster 26410adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 26510adb8beSMarkus Armbruster "-set group.id.arg=value\n" 26610adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 26710adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 26810adb8beSMarkus ArmbrusterSTEXI 26910adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 27010adb8beSMarkus Armbruster@findex -set 271e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 27210adb8beSMarkus ArmbrusterETEXI 27310adb8beSMarkus Armbruster 27410adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 2753751d7c4SPaolo Bonzini "-global driver.property=value\n" 2763751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 27710adb8beSMarkus Armbruster " set a global default for a driver property\n", 27810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 27910adb8beSMarkus ArmbrusterSTEXI 28010adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 2813751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 28210adb8beSMarkus Armbruster@findex -global 28310adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 28410adb8beSMarkus Armbruster 28510adb8beSMarkus Armbruster@example 286664785acSThomas Huth@value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img 28710adb8beSMarkus Armbruster@end example 28810adb8beSMarkus Armbruster 28910adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 29010adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 29110adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 2923751d7c4SPaolo Bonzini 293ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 294ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 295ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 29610adb8beSMarkus ArmbrusterETEXI 29710adb8beSMarkus Armbruster 29810adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 29910adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 300c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 30110adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 30210adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 30310adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 30410adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 30510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 30610adb8beSMarkus ArmbrusterSTEXI 307c8a6ae8bSAmos 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] 30810adb8beSMarkus Armbruster@findex -boot 30910adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 310d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 31110adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 31210adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 31310adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 314c0d9f7d0SThomas Huth@option{once}. Note that the @option{order} or @option{once} parameter 315c0d9f7d0SThomas Huthshould not be used together with the @option{bootindex} property of 316c0d9f7d0SThomas Huthdevices, since the firmware implementations normally do not support both 317c0d9f7d0SThomas Huthat the same time. 31810adb8beSMarkus Armbruster 31910adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 32010adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 32110adb8beSMarkus Armbruster 32210adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 32310adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 32410adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 32510adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 32610adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 32710adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 32810adb8beSMarkus Armbruster 32910adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 330bbd9e698SHan Hanwhen boot failed, then reboot. If @option{reboot-timeout} is not set, 331bbd9e698SHan Hanguest will not reboot by default. Currently Seabios for X86 33210adb8beSMarkus Armbrustersystem support it. 33310adb8beSMarkus Armbruster 334c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 335c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 336c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 337c8a6ae8bSAmos Kong 33810adb8beSMarkus Armbruster@example 33910adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 340664785acSThomas Huth@value{qemu_system_x86} -boot order=nc 34110adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 342664785acSThomas Huth@value{qemu_system_x86} -boot once=d 34310adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 344664785acSThomas Huth@value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000 34510adb8beSMarkus Armbruster@end example 34610adb8beSMarkus Armbruster 34710adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 34810adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 34910adb8beSMarkus ArmbrusterETEXI 35010adb8beSMarkus Armbruster 35110adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 35289f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 3536e1d3c1cSIgor Mammedov " configure guest RAM\n" 3540daba1f0SAlexander Graf " size: initial amount of guest memory\n" 355c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 356b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 357b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 3586e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 35910adb8beSMarkus ArmbrusterSTEXI 3609fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 36110adb8beSMarkus Armbruster@findex -m 3629fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 3639fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 3649fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 3659fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 3669fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 3679fcc0794SLuiz Capitulino 3689fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 3699fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 3709fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 3719fcc0794SLuiz Capitulino 3729fcc0794SLuiz Capitulino@example 373664785acSThomas Huth@value{qemu_system} -m 1G,slots=3,maxmem=4G 3749fcc0794SLuiz Capitulino@end example 3759fcc0794SLuiz Capitulino 3769fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 3779fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 37810adb8beSMarkus ArmbrusterETEXI 37910adb8beSMarkus Armbruster 38010adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 38110adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 38210adb8beSMarkus ArmbrusterSTEXI 38310adb8beSMarkus Armbruster@item -mem-path @var{path} 38410adb8beSMarkus Armbruster@findex -mem-path 38510adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 38610adb8beSMarkus ArmbrusterETEXI 38710adb8beSMarkus Armbruster 38810adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 38910adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 39010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 39110adb8beSMarkus ArmbrusterSTEXI 39210adb8beSMarkus Armbruster@item -mem-prealloc 39310adb8beSMarkus Armbruster@findex -mem-prealloc 39410adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 39510adb8beSMarkus ArmbrusterETEXI 39610adb8beSMarkus Armbruster 39710adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 39810adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 39910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 40010adb8beSMarkus ArmbrusterSTEXI 40110adb8beSMarkus Armbruster@item -k @var{language} 40210adb8beSMarkus Armbruster@findex -k 40310adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 40410adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 40532945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 40610adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 40710adb8beSMarkus Armbrusterhosts. 40810adb8beSMarkus Armbruster 40910adb8beSMarkus ArmbrusterThe available layouts are: 41010adb8beSMarkus Armbruster@example 41110adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 41210adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 41310adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 41410adb8beSMarkus Armbruster@end example 41510adb8beSMarkus Armbruster 41610adb8beSMarkus ArmbrusterThe default is @code{en-us}. 41710adb8beSMarkus ArmbrusterETEXI 41810adb8beSMarkus Armbruster 41910adb8beSMarkus Armbruster 420f0b3d811SKővágó, ZoltánHXCOMM Deprecated by -audiodev 42110adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 422f0b3d811SKővágó, Zoltán "-audio-help show -audiodev equivalent of the currently specified audio settings\n", 42310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 42410adb8beSMarkus ArmbrusterSTEXI 42510adb8beSMarkus Armbruster@item -audio-help 42610adb8beSMarkus Armbruster@findex -audio-help 427f0b3d811SKővágó, ZoltánWill show the -audiodev equivalent of the currently specified 428f0b3d811SKővágó, Zoltán(deprecated) environment variables. 429f0b3d811SKővágó, ZoltánETEXI 430f0b3d811SKővágó, Zoltán 431f0b3d811SKővágó, ZoltánDEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev, 432f0b3d811SKővágó, Zoltán "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n" 433f0b3d811SKővágó, Zoltán " specifies the audio backend to use\n" 434f0b3d811SKővágó, Zoltán " id= identifier of the backend\n" 435f0b3d811SKővágó, Zoltán " timer-period= timer period in microseconds\n" 4368efac073SKővágó, Zoltán " in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n" 437f0b3d811SKővágó, Zoltán " in|out.fixed-settings= use fixed settings for host audio\n" 438f0b3d811SKővágó, Zoltán " in|out.frequency= frequency to use with fixed settings\n" 439f0b3d811SKővágó, Zoltán " in|out.channels= number of channels to use with fixed settings\n" 440f0b3d811SKővágó, Zoltán " in|out.format= sample format to use with fixed settings\n" 441f0b3d811SKővágó, Zoltán " valid values: s8, s16, s32, u8, u16, u32\n" 442f0b3d811SKővágó, Zoltán " in|out.voices= number of voices to use\n" 4438624725bSStefan Hajnoczi " in|out.buffer-length= length of buffer in microseconds\n" 444f0b3d811SKővágó, Zoltán "-audiodev none,id=id,[,prop[=value][,...]]\n" 445f0b3d811SKővágó, Zoltán " dummy driver that discards all output\n" 446f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_ALSA 447f0b3d811SKővágó, Zoltán "-audiodev alsa,id=id[,prop[=value][,...]]\n" 448f0b3d811SKővágó, Zoltán " in|out.dev= name of the audio device to use\n" 449dfc54343SStefan Hajnoczi " in|out.period-length= length of period in microseconds\n" 450f0b3d811SKővágó, Zoltán " in|out.try-poll= attempt to use poll mode\n" 451f0b3d811SKővágó, Zoltán " threshold= threshold (in microseconds) when playback starts\n" 452f0b3d811SKővágó, Zoltán#endif 453f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_COREAUDIO 454f0b3d811SKővágó, Zoltán "-audiodev coreaudio,id=id[,prop[=value][,...]]\n" 455f0b3d811SKővágó, Zoltán " in|out.buffer-count= number of buffers\n" 456f0b3d811SKővágó, Zoltán#endif 457f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_DSOUND 458f0b3d811SKővágó, Zoltán "-audiodev dsound,id=id[,prop[=value][,...]]\n" 459f0b3d811SKővágó, Zoltán " latency= add extra latency to playback in microseconds\n" 460f0b3d811SKővágó, Zoltán#endif 461f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_OSS 462f0b3d811SKővágó, Zoltán "-audiodev oss,id=id[,prop[=value][,...]]\n" 463f0b3d811SKővágó, Zoltán " in|out.dev= path of the audio device to use\n" 464f0b3d811SKővágó, Zoltán " in|out.buffer-count= number of buffers\n" 465f0b3d811SKővágó, Zoltán " in|out.try-poll= attempt to use poll mode\n" 466f0b3d811SKővágó, Zoltán " try-mmap= try using memory mapped access\n" 467f0b3d811SKővágó, Zoltán " exclusive= open device in exclusive mode\n" 468f0b3d811SKővágó, Zoltán " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n" 469f0b3d811SKővágó, Zoltán#endif 470f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_PA 471f0b3d811SKővágó, Zoltán "-audiodev pa,id=id[,prop[=value][,...]]\n" 472f0b3d811SKővágó, Zoltán " server= PulseAudio server address\n" 473f0b3d811SKővágó, Zoltán " in|out.name= source/sink device name\n" 47414d4f011SStefan Hajnoczi " in|out.latency= desired latency in microseconds\n" 475f0b3d811SKővágó, Zoltán#endif 476f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_SDL 477f0b3d811SKővágó, Zoltán "-audiodev sdl,id=id[,prop[=value][,...]]\n" 478f0b3d811SKővágó, Zoltán#endif 479f0b3d811SKővágó, Zoltán#ifdef CONFIG_SPICE 480f0b3d811SKővágó, Zoltán "-audiodev spice,id=id[,prop[=value][,...]]\n" 481f0b3d811SKővágó, Zoltán#endif 482f0b3d811SKővágó, Zoltán "-audiodev wav,id=id[,prop[=value][,...]]\n" 483f0b3d811SKővágó, Zoltán " path= path of wav file to record\n", 484f0b3d811SKővágó, Zoltán QEMU_ARCH_ALL) 485f0b3d811SKővágó, ZoltánSTEXI 486f0b3d811SKővágó, Zoltán@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]] 487f0b3d811SKővágó, Zoltán@findex -audiodev 488f0b3d811SKővágó, ZoltánAdds a new audio backend @var{driver} identified by @var{id}. There are 489f0b3d811SKővágó, Zoltánglobal and driver specific properties. Some values can be set 490f0b3d811SKővágó, Zoltándifferently for input and output, they're marked with @code{in|out.}. 491f0b3d811SKővágó, ZoltánYou can set the input's property with @code{in.@var{prop}} and the 492f0b3d811SKővágó, Zoltánoutput's property with @code{out.@var{prop}}. For example: 493f0b3d811SKővágó, Zoltán@example 494f0b3d811SKővágó, Zoltán-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 495f0b3d811SKővágó, Zoltán-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified 496f0b3d811SKővágó, Zoltán@end example 497f0b3d811SKővágó, Zoltán 4988efac073SKővágó, ZoltánNOTE: parameter validation is known to be incomplete, in many cases 4998efac073SKővágó, Zoltánspecifying an invalid option causes QEMU to print an error message and 5008efac073SKővágó, Zoltáncontinue emulation without sound. 5018efac073SKővágó, Zoltán 502f0b3d811SKővágó, ZoltánValid global options are: 503f0b3d811SKővágó, Zoltán 504f0b3d811SKővágó, Zoltán@table @option 505f0b3d811SKővágó, Zoltán@item id=@var{identifier} 506f0b3d811SKővágó, ZoltánIdentifies the audio backend. 507f0b3d811SKővágó, Zoltán 508f0b3d811SKővágó, Zoltán@item timer-period=@var{period} 509f0b3d811SKővágó, ZoltánSets the timer @var{period} used by the audio subsystem in microseconds. 510f0b3d811SKővágó, ZoltánDefault is 10000 (10 ms). 511f0b3d811SKővágó, Zoltán 5128efac073SKővágó, Zoltán@item in|out.mixing-engine=on|off 5138efac073SKővágó, ZoltánUse QEMU's mixing engine to mix all streams inside QEMU and convert 5148efac073SKővágó, Zoltánaudio formats when not supported by the backend. When off, 5158efac073SKővágó, Zoltán@var{fixed-settings} must be off too. Note that disabling this option 5168efac073SKővágó, Zoltánmeans that the selected backend must support multiple streams and the 5178efac073SKővágó, Zoltánaudio formats used by the virtual cards, otherwise you'll get no sound. 5188efac073SKővágó, ZoltánIt's not recommended to disable this option unless you want to use 5.1 5198efac073SKővágó, Zoltánor 7.1 audio, as mixing engine only supports mono and stereo audio. 5208efac073SKővágó, ZoltánDefault is on. 5218efac073SKővágó, Zoltán 522f0b3d811SKővágó, Zoltán@item in|out.fixed-settings=on|off 523f0b3d811SKővágó, ZoltánUse fixed settings for host audio. When off, it will change based on 524f0b3d811SKővágó, Zoltánhow the guest opens the sound card. In this case you must not specify 525f0b3d811SKővágó, Zoltán@var{frequency}, @var{channels} or @var{format}. Default is on. 526f0b3d811SKővágó, Zoltán 527f0b3d811SKővágó, Zoltán@item in|out.frequency=@var{frequency} 528f0b3d811SKővágó, ZoltánSpecify the @var{frequency} to use when using @var{fixed-settings}. 529f0b3d811SKővágó, ZoltánDefault is 44100Hz. 530f0b3d811SKővágó, Zoltán 531f0b3d811SKővágó, Zoltán@item in|out.channels=@var{channels} 532f0b3d811SKővágó, ZoltánSpecify the number of @var{channels} to use when using 533f0b3d811SKővágó, Zoltán@var{fixed-settings}. Default is 2 (stereo). 534f0b3d811SKővágó, Zoltán 535f0b3d811SKővágó, Zoltán@item in|out.format=@var{format} 536f0b3d811SKővágó, ZoltánSpecify the sample @var{format} to use when using @var{fixed-settings}. 537f0b3d811SKővágó, ZoltánValid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8}, 538f0b3d811SKővágó, Zoltán@code{u16}, @code{u32}. Default is @code{s16}. 539f0b3d811SKővágó, Zoltán 540f0b3d811SKővágó, Zoltán@item in|out.voices=@var{voices} 541f0b3d811SKővágó, ZoltánSpecify the number of @var{voices} to use. Default is 1. 542f0b3d811SKővágó, Zoltán 5438624725bSStefan Hajnoczi@item in|out.buffer-length=@var{usecs} 544f0b3d811SKővágó, ZoltánSets the size of the buffer in microseconds. 545f0b3d811SKővágó, Zoltán 546f0b3d811SKővágó, Zoltán@end table 547f0b3d811SKővágó, Zoltán 548f0b3d811SKővágó, Zoltán@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]] 549f0b3d811SKővágó, ZoltánCreates a dummy backend that discards all outputs. This backend has no 550f0b3d811SKővágó, Zoltánbackend specific properties. 551f0b3d811SKővágó, Zoltán 552f0b3d811SKővágó, Zoltán@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 553f0b3d811SKővágó, ZoltánCreates backend using the ALSA. This backend is only available on 554f0b3d811SKővágó, ZoltánLinux. 555f0b3d811SKővágó, Zoltán 556f0b3d811SKővágó, ZoltánALSA specific options are: 557f0b3d811SKővágó, Zoltán 558f0b3d811SKővágó, Zoltán@table @option 559f0b3d811SKővágó, Zoltán 560f0b3d811SKővágó, Zoltán@item in|out.dev=@var{device} 561f0b3d811SKővágó, ZoltánSpecify the ALSA @var{device} to use for input and/or output. Default 562f0b3d811SKővágó, Zoltánis @code{default}. 563f0b3d811SKővágó, Zoltán 564dfc54343SStefan Hajnoczi@item in|out.period-length=@var{usecs} 565f0b3d811SKővágó, ZoltánSets the period length in microseconds. 566f0b3d811SKővágó, Zoltán 567f0b3d811SKővágó, Zoltán@item in|out.try-poll=on|off 568f0b3d811SKővágó, ZoltánAttempt to use poll mode with the device. Default is on. 569f0b3d811SKővágó, Zoltán 570f0b3d811SKővágó, Zoltán@item threshold=@var{threshold} 571f0b3d811SKővágó, ZoltánThreshold (in microseconds) when playback starts. Default is 0. 572f0b3d811SKővágó, Zoltán 573f0b3d811SKővágó, Zoltán@end table 574f0b3d811SKővágó, Zoltán 575f0b3d811SKővágó, Zoltán@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]] 576f0b3d811SKővágó, ZoltánCreates a backend using Apple's Core Audio. This backend is only 577f0b3d811SKővágó, Zoltánavailable on Mac OS and only supports playback. 578f0b3d811SKővágó, Zoltán 579f0b3d811SKővágó, ZoltánCore Audio specific options are: 580f0b3d811SKővágó, Zoltán 581f0b3d811SKővágó, Zoltán@table @option 582f0b3d811SKővágó, Zoltán 583f0b3d811SKővágó, Zoltán@item in|out.buffer-count=@var{count} 584f0b3d811SKővágó, ZoltánSets the @var{count} of the buffers. 585f0b3d811SKővágó, Zoltán 586f0b3d811SKővágó, Zoltán@end table 587f0b3d811SKővágó, Zoltán 588f0b3d811SKővágó, Zoltán@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]] 589f0b3d811SKővágó, ZoltánCreates a backend using Microsoft's DirectSound. This backend is only 590f0b3d811SKővágó, Zoltánavailable on Windows and only supports playback. 591f0b3d811SKővágó, Zoltán 592f0b3d811SKővágó, ZoltánDirectSound specific options are: 593f0b3d811SKővágó, Zoltán 594f0b3d811SKővágó, Zoltán@table @option 595f0b3d811SKővágó, Zoltán 596f0b3d811SKővágó, Zoltán@item latency=@var{usecs} 597f0b3d811SKővágó, ZoltánAdd extra @var{usecs} microseconds latency to playback. Default is 598f0b3d811SKővágó, Zoltán10000 (10 ms). 599f0b3d811SKővágó, Zoltán 600f0b3d811SKővágó, Zoltán@end table 601f0b3d811SKővágó, Zoltán 602f0b3d811SKővágó, Zoltán@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]] 603f0b3d811SKővágó, ZoltánCreates a backend using OSS. This backend is available on most 604f0b3d811SKővágó, ZoltánUnix-like systems. 605f0b3d811SKővágó, Zoltán 606f0b3d811SKővágó, ZoltánOSS specific options are: 607f0b3d811SKővágó, Zoltán 608f0b3d811SKővágó, Zoltán@table @option 609f0b3d811SKővágó, Zoltán 610f0b3d811SKővágó, Zoltán@item in|out.dev=@var{device} 611f0b3d811SKővágó, ZoltánSpecify the file name of the OSS @var{device} to use. Default is 612f0b3d811SKővágó, Zoltán@code{/dev/dsp}. 613f0b3d811SKővágó, Zoltán 614f0b3d811SKővágó, Zoltán@item in|out.buffer-count=@var{count} 615f0b3d811SKővágó, ZoltánSets the @var{count} of the buffers. 616f0b3d811SKővágó, Zoltán 617f0b3d811SKővágó, Zoltán@item in|out.try-poll=on|of 618f0b3d811SKővágó, ZoltánAttempt to use poll mode with the device. Default is on. 619f0b3d811SKővágó, Zoltán 620f0b3d811SKővágó, Zoltán@item try-mmap=on|off 621f0b3d811SKővágó, ZoltánTry using memory mapped device access. Default is off. 622f0b3d811SKővágó, Zoltán 623f0b3d811SKővágó, Zoltán@item exclusive=on|off 624f0b3d811SKővágó, ZoltánOpen the device in exclusive mode (vmix won't work in this case). 625f0b3d811SKővágó, ZoltánDefault is off. 626f0b3d811SKővágó, Zoltán 627f0b3d811SKővágó, Zoltán@item dsp-policy=@var{policy} 628f0b3d811SKővágó, ZoltánSets the timing policy (between 0 and 10, where smaller number means 629f0b3d811SKővágó, Zoltánsmaller latency but higher CPU usage). Use -1 to use buffer sizes 630f0b3d811SKővágó, Zoltánspecified by @code{buffer} and @code{buffer-count}. This option is 631f0b3d811SKővágó, Zoltánignored if you do not have OSS 4. Default is 5. 632f0b3d811SKővágó, Zoltán 633f0b3d811SKővágó, Zoltán@end table 634f0b3d811SKővágó, Zoltán 635f0b3d811SKővágó, Zoltán@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 636f0b3d811SKővágó, ZoltánCreates a backend using PulseAudio. This backend is available on most 637f0b3d811SKővágó, Zoltánsystems. 638f0b3d811SKővágó, Zoltán 639f0b3d811SKővágó, ZoltánPulseAudio specific options are: 640f0b3d811SKővágó, Zoltán 641f0b3d811SKővágó, Zoltán@table @option 642f0b3d811SKővágó, Zoltán 643f0b3d811SKővágó, Zoltán@item server=@var{server} 644f0b3d811SKővágó, ZoltánSets the PulseAudio @var{server} to connect to. 645f0b3d811SKővágó, Zoltán 646f0b3d811SKővágó, Zoltán@item in|out.name=@var{sink} 647f0b3d811SKővágó, ZoltánUse the specified source/sink for recording/playback. 648f0b3d811SKővágó, Zoltán 64914d4f011SStefan Hajnoczi@item in|out.latency=@var{usecs} 65014d4f011SStefan HajnocziDesired latency in microseconds. The PulseAudio server will try to honor this 65114d4f011SStefan Hajnoczivalue but actual latencies may be lower or higher. 65214d4f011SStefan Hajnoczi 653f0b3d811SKővágó, Zoltán@end table 654f0b3d811SKővágó, Zoltán 655f0b3d811SKővágó, Zoltán@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]] 656f0b3d811SKővágó, ZoltánCreates a backend using SDL. This backend is available on most systems, 657f0b3d811SKővágó, Zoltánbut you should use your platform's native backend if possible. This 658f0b3d811SKővágó, Zoltánbackend has no backend specific properties. 659f0b3d811SKővágó, Zoltán 660f0b3d811SKővágó, Zoltán@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]] 661f0b3d811SKővágó, ZoltánCreates a backend that sends audio through SPICE. This backend requires 662f0b3d811SKővágó, Zoltán@code{-spice} and automatically selected in that case, so usually you 663f0b3d811SKővágó, Zoltáncan ignore this option. This backend has no backend specific 664f0b3d811SKővágó, Zoltánproperties. 665f0b3d811SKővágó, Zoltán 666f0b3d811SKővágó, Zoltán@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]] 667f0b3d811SKővágó, ZoltánCreates a backend that writes audio to a WAV file. 668f0b3d811SKővágó, Zoltán 669f0b3d811SKővágó, ZoltánBackend 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 path=@var{path} 674f0b3d811SKővágó, ZoltánWrite recorded audio into the specified file. Default is 675f0b3d811SKővágó, Zoltán@code{qemu.wav}. 676f0b3d811SKővágó, Zoltán 677f0b3d811SKővágó, Zoltán@end table 67810adb8beSMarkus ArmbrusterETEXI 67910adb8beSMarkus Armbruster 68010adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 68110adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 68210adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 68310adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 68410adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 68510adb8beSMarkus ArmbrusterSTEXI 68610adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 68710adb8beSMarkus Armbruster@findex -soundhw 68810adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 689664785acSThomas Huthavailable sound hardware. For example: 69010adb8beSMarkus Armbruster 69110adb8beSMarkus Armbruster@example 692664785acSThomas Huth@value{qemu_system_x86} -soundhw sb16,adlib disk.img 693664785acSThomas Huth@value{qemu_system_x86} -soundhw es1370 disk.img 694664785acSThomas Huth@value{qemu_system_x86} -soundhw ac97 disk.img 695664785acSThomas Huth@value{qemu_system_x86} -soundhw hda disk.img 696664785acSThomas Huth@value{qemu_system_x86} -soundhw all disk.img 697664785acSThomas Huth@value{qemu_system_x86} -soundhw help 69810adb8beSMarkus Armbruster@end example 69910adb8beSMarkus Armbruster 70010adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 70110adb8beSMarkus Armbrusterrequire manually specifying clocking. 70210adb8beSMarkus Armbruster 70310adb8beSMarkus Armbruster@example 70410adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 70510adb8beSMarkus Armbruster@end example 70610adb8beSMarkus ArmbrusterETEXI 70710adb8beSMarkus Armbruster 70810adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 70910adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 71010adb8beSMarkus Armbruster " add device (based on driver)\n" 71110adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 71210adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 71310adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 71410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 71510adb8beSMarkus ArmbrusterSTEXI 71610adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 71710adb8beSMarkus Armbruster@findex -device 71810adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 71910adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 72010adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 72110adb8beSMarkus Armbruster@code{-device @var{driver},help}. 722f8490451SCorey Minyard 723f8490451SCorey MinyardSome drivers are: 7247b0cd78bSCorey 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}] 725f8490451SCorey Minyard 726f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 727f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 728f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 729f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 730f8490451SCorey Minyard 731f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 732f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 733f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 734f8490451SCorey Minyardit. 735f8490451SCorey Minyard 7368c6fd7f3SCédric Le Goater@table @option 7377b0cd78bSCorey Minyard@item id=@var{id} 7387b0cd78bSCorey MinyardThe BMC id for interfaces to use this device. 7398c6fd7f3SCédric Le Goater@item slave_addr=@var{val} 7408c6fd7f3SCédric Le GoaterDefine slave address to use for the BMC. The default is 0x20. 7418c6fd7f3SCédric Le Goater@item sdrfile=@var{file} 7428c6fd7f3SCédric Le Goaterfile containing raw Sensor Data Records (SDR) data. The default is none. 743540c07d3SCédric Le Goater@item fruareasize=@var{val} 744540c07d3SCédric Le Goatersize of a Field Replaceable Unit (FRU) area. The default is 1024. 745540c07d3SCédric Le Goater@item frudatafile=@var{file} 746540c07d3SCédric Le Goaterfile containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 7477b0cd78bSCorey Minyard@item guid=@var{uuid} 7487b0cd78bSCorey Minyardvalue for the GUID for the BMC, in standard UUID format. If this is set, 7497b0cd78bSCorey Minyardget "Get GUID" command to the BMC will return it. Otherwise "Get GUID" 7507b0cd78bSCorey Minyardwill return an error. 7518c6fd7f3SCédric Le Goater@end table 7528c6fd7f3SCédric Le Goater 753f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 754f8490451SCorey Minyard 755f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 756f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 757f8490451SCorey Minyardto an external entity that provides the IPMI services. 758f8490451SCorey Minyard 759f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 760f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 761f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 762f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 763f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 764f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 765f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 766f8490451SCorey Minyardexposed to any outside network. 767f8490451SCorey Minyard 768f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 769f8490451SCorey Minyarddetails on the external interface. 770f8490451SCorey Minyard 771f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 772f8490451SCorey Minyard 773f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 774f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 775f8490451SCorey Minyard 776f8490451SCorey Minyard@table @option 777f8490451SCorey Minyard@item bmc=@var{id} 778f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 779f8490451SCorey Minyard@item ioport=@var{val} 780f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 781f8490451SCorey Minyard@item irq=@var{val} 782f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 783f8490451SCorey Minyardset this to 0. 784f8490451SCorey Minyard@end table 785f8490451SCorey Minyard 786f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 787f8490451SCorey Minyard 788f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 789f8490451SCorey Minyard0xe4 and the default interrupt is 5. 790f8490451SCorey Minyard 79110adb8beSMarkus ArmbrusterETEXI 79210adb8beSMarkus Armbruster 79310adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 7948f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 79510adb8beSMarkus Armbruster " set the name of the guest\n" 796479a5747SRoman Bolshakov " string1 sets the window title and string2 the process name\n" 797479a5747SRoman Bolshakov " When debug-threads is enabled, individual threads are given a separate name\n" 7988f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 79910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 80010adb8beSMarkus ArmbrusterSTEXI 80110adb8beSMarkus Armbruster@item -name @var{name} 80210adb8beSMarkus Armbruster@findex -name 80310adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 80410adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 80510adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 80610adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 8078f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 80810adb8beSMarkus ArmbrusterETEXI 80910adb8beSMarkus Armbruster 81010adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 81110adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 81210adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 81310adb8beSMarkus ArmbrusterSTEXI 81410adb8beSMarkus Armbruster@item -uuid @var{uuid} 81510adb8beSMarkus Armbruster@findex -uuid 81610adb8beSMarkus ArmbrusterSet system UUID. 81710adb8beSMarkus ArmbrusterETEXI 81810adb8beSMarkus Armbruster 81910adb8beSMarkus ArmbrusterSTEXI 82010adb8beSMarkus Armbruster@end table 82110adb8beSMarkus ArmbrusterETEXI 82210adb8beSMarkus ArmbrusterDEFHEADING() 82310adb8beSMarkus Armbruster 824de6b4f90SMarkus ArmbrusterDEFHEADING(Block device options:) 82510adb8beSMarkus ArmbrusterSTEXI 82610adb8beSMarkus Armbruster@table @option 82710adb8beSMarkus ArmbrusterETEXI 82810adb8beSMarkus Armbruster 8295824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 830ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 831ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 8325824d651Sblueswir1STEXI 8335824d651Sblueswir1@item -fda @var{file} 834f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 8356616b2adSStefan Weil@findex -fda 8366616b2adSStefan Weil@findex -fdb 83792a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 8385824d651Sblueswir1ETEXI 8395824d651Sblueswir1 8405824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 841ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 842ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 8435824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 844ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 845ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 8465824d651Sblueswir1STEXI 8475824d651Sblueswir1@item -hda @var{file} 848f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 849f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 850f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 8516616b2adSStefan Weil@findex -hda 8526616b2adSStefan Weil@findex -hdb 8536616b2adSStefan Weil@findex -hdc 8546616b2adSStefan Weil@findex -hdd 8555824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 8565824d651Sblueswir1ETEXI 8575824d651Sblueswir1 8585824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 859ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 860ad96090aSBlue Swirl QEMU_ARCH_ALL) 8615824d651Sblueswir1STEXI 8625824d651Sblueswir1@item -cdrom @var{file} 8636616b2adSStefan Weil@findex -cdrom 8645824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 8655824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 8665824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 8675824d651Sblueswir1ETEXI 8685824d651Sblueswir1 86942e5f393SMarkus ArmbrusterDEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 87042e5f393SMarkus Armbruster "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 87142e5f393SMarkus Armbruster " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 872c9b749d7SKevin Wolf " [,read-only=on|off][,auto-read-only=on|off]\n" 873c9b749d7SKevin Wolf " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n" 87442e5f393SMarkus Armbruster " [,driver specific parameters...]\n" 87542e5f393SMarkus Armbruster " configure a block backend\n", QEMU_ARCH_ALL) 876dfaca464SKevin WolfSTEXI 877dfaca464SKevin Wolf@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 878dfaca464SKevin Wolf@findex -blockdev 879dfaca464SKevin Wolf 880370e8328SKevin WolfDefine a new block driver node. Some of the options apply to all block drivers, 881370e8328SKevin Wolfother options are only accepted for a specific block driver. See below for a 882370e8328SKevin Wolflist of generic options and options for the most common block drivers. 883370e8328SKevin Wolf 884370e8328SKevin WolfOptions that expect a reference to another node (e.g. @code{file}) can be 885370e8328SKevin Wolfgiven in two ways. Either you specify the node name of an already existing node 886370e8328SKevin Wolf(file=@var{node-name}), or you define a new node inline, adding options 887370e8328SKevin Wolffor the referenced node after a dot (file.filename=@var{path},file.aio=native). 888370e8328SKevin Wolf 889370e8328SKevin WolfA block driver node created with @option{-blockdev} can be used for a guest 890370e8328SKevin Wolfdevice by specifying its node name for the @code{drive} property in a 891370e8328SKevin Wolf@option{-device} argument that defines a block device. 892dfaca464SKevin Wolf 893dfaca464SKevin Wolf@table @option 894dfaca464SKevin Wolf@item Valid options for any block driver node: 895dfaca464SKevin Wolf 896dfaca464SKevin Wolf@table @code 897dfaca464SKevin Wolf@item driver 898dfaca464SKevin WolfSpecifies the block driver to use for the given node. 899dfaca464SKevin Wolf@item node-name 900dfaca464SKevin WolfThis defines the name of the block driver node by which it will be referenced 901dfaca464SKevin Wolflater. The name must be unique, i.e. it must not match the name of a different 902dfaca464SKevin Wolfblock driver node, or (if you use @option{-drive} as well) the ID of a drive. 903dfaca464SKevin Wolf 904dfaca464SKevin WolfIf no node name is specified, it is automatically generated. The generated node 905dfaca464SKevin Wolfname is not intended to be predictable and changes between QEMU invocations. 906dfaca464SKevin WolfFor the top level, an explicit node name must be specified. 907dfaca464SKevin Wolf@item read-only 908dfaca464SKevin WolfOpen the node read-only. Guest write attempts will fail. 909c9b749d7SKevin Wolf 910c9b749d7SKevin WolfNote that some block drivers support only read-only access, either generally or 911c9b749d7SKevin Wolfin certain configurations. In this case, the default value 912c9b749d7SKevin Wolf@option{read-only=off} does not work and the option must be specified 913c9b749d7SKevin Wolfexplicitly. 914c9b749d7SKevin Wolf@item auto-read-only 915c9b749d7SKevin WolfIf @option{auto-read-only=on} is set, QEMU may fall back to read-only usage 916c9b749d7SKevin Wolfeven when @option{read-only=off} is requested, or even switch between modes as 917c9b749d7SKevin Wolfneeded, e.g. depending on whether the image file is writable or whether a 918c9b749d7SKevin Wolfwriting user is attached to the node. 919c9b749d7SKevin Wolf@item force-share 920c9b749d7SKevin WolfOverride the image locking system of QEMU by forcing the node to utilize 921c9b749d7SKevin Wolfweaker shared access for permissions where it would normally request exclusive 922c9b749d7SKevin Wolfaccess. When there is the potential for multiple instances to have the same 923c9b749d7SKevin Wolffile open (whether this invocation of QEMU is the first or the second 924c9b749d7SKevin Wolfinstance), both instances must permit shared access for the second instance to 925c9b749d7SKevin Wolfsucceed at opening the file. 926c9b749d7SKevin Wolf 927c9b749d7SKevin WolfEnabling @option{force-share=on} requires @option{read-only=on}. 928dfaca464SKevin Wolf@item cache.direct 929dfaca464SKevin WolfThe host page cache can be avoided with @option{cache.direct=on}. This will 930dfaca464SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform an 931dfaca464SKevin Wolfinternal copy of the data. 932dfaca464SKevin Wolf@item cache.no-flush 933dfaca464SKevin WolfIn case you don't care about data integrity over host failures, you can use 934dfaca464SKevin Wolf@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 935dfaca464SKevin Wolfany data to the disk but can instead keep things in cache. If anything goes 936dfaca464SKevin Wolfwrong, like your host losing power, the disk storage getting disconnected 937dfaca464SKevin Wolfaccidentally, etc. your image will most probably be rendered unusable. 938dfaca464SKevin Wolf@item discard=@var{discard} 939dfaca464SKevin Wolf@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 940dfaca464SKevin Wolfwhether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 941dfaca464SKevin Wolfignored or passed to the filesystem. Some machine types may not support 942dfaca464SKevin Wolfdiscard requests. 943dfaca464SKevin Wolf@item detect-zeroes=@var{detect-zeroes} 944dfaca464SKevin Wolf@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 945dfaca464SKevin Wolfconversion of plain zero writes by the OS to driver specific optimized 946dfaca464SKevin Wolfzero write commands. You may even choose "unmap" if @var{discard} is set 947dfaca464SKevin Wolfto "unmap" to allow a zero write to be converted to an @code{unmap} operation. 948dfaca464SKevin Wolf@end table 949dfaca464SKevin Wolf 950370e8328SKevin Wolf@item Driver-specific options for @code{file} 951370e8328SKevin Wolf 952370e8328SKevin WolfThis is the protocol-level block driver for accessing regular files. 953370e8328SKevin Wolf 954370e8328SKevin Wolf@table @code 955370e8328SKevin Wolf@item filename 956370e8328SKevin WolfThe path to the image file in the local filesystem 957370e8328SKevin Wolf@item aio 958370e8328SKevin WolfSpecifies the AIO backend (threads/native, default: threads) 9591878eaffSFam Zheng@item locking 9601878eaffSFam ZhengSpecifies whether the image file is protected with Linux OFD / POSIX locks. The 9611878eaffSFam Zhengdefault is to use the Linux Open File Descriptor API if available, otherwise no 9621878eaffSFam Zhenglock is applied. (auto/on/off, default: auto) 963370e8328SKevin Wolf@end table 964370e8328SKevin WolfExample: 965370e8328SKevin Wolf@example 966370e8328SKevin Wolf-blockdev driver=file,node-name=disk,filename=disk.img 967370e8328SKevin Wolf@end example 968370e8328SKevin Wolf 969370e8328SKevin Wolf@item Driver-specific options for @code{raw} 970370e8328SKevin Wolf 971370e8328SKevin WolfThis is the image format block driver for raw images. It is usually 972370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 973370e8328SKevin Wolf 974370e8328SKevin Wolf@table @code 975370e8328SKevin Wolf@item file 976370e8328SKevin WolfReference to or definition of the data source block driver node 977370e8328SKevin Wolf(e.g. a @code{file} driver node) 978370e8328SKevin Wolf@end table 979370e8328SKevin WolfExample 1: 980370e8328SKevin Wolf@example 981370e8328SKevin Wolf-blockdev driver=file,node-name=disk_file,filename=disk.img 982370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file=disk_file 983370e8328SKevin Wolf@end example 984370e8328SKevin WolfExample 2: 985370e8328SKevin Wolf@example 986370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 987370e8328SKevin Wolf@end example 988370e8328SKevin Wolf 989370e8328SKevin Wolf@item Driver-specific options for @code{qcow2} 990370e8328SKevin Wolf 991370e8328SKevin WolfThis is the image format block driver for qcow2 images. It is usually 992370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 993370e8328SKevin Wolf 994370e8328SKevin Wolf@table @code 995370e8328SKevin Wolf@item file 996370e8328SKevin WolfReference to or definition of the data source block driver node 997370e8328SKevin Wolf(e.g. a @code{file} driver node) 998370e8328SKevin Wolf 999370e8328SKevin Wolf@item backing 1000370e8328SKevin WolfReference to or definition of the backing file block device (default is taken 10014f7be280SMax Reitzfrom the image file). It is allowed to pass @code{null} here in order to disable 10024f7be280SMax Reitzthe default backing file. 1003370e8328SKevin Wolf 1004370e8328SKevin Wolf@item lazy-refcounts 1005370e8328SKevin WolfWhether to enable the lazy refcounts feature (on/off; default is taken from the 1006370e8328SKevin Wolfimage file) 1007370e8328SKevin Wolf 1008370e8328SKevin Wolf@item cache-size 1009370e8328SKevin WolfThe maximum total size of the L2 table and refcount block caches in bytes 101040fb215dSLeonid Bloch(default: the sum of l2-cache-size and refcount-cache-size) 1011370e8328SKevin Wolf 1012370e8328SKevin Wolf@item l2-cache-size 1013370e8328SKevin WolfThe maximum size of the L2 table cache in bytes 101480668d0fSLeonid Bloch(default: if cache-size is not specified - 32M on Linux platforms, and 8M on 101580668d0fSLeonid Blochnon-Linux platforms; otherwise, as large as possible within the cache-size, 101680668d0fSLeonid Blochwhile permitting the requested or the minimal refcount cache size) 1017370e8328SKevin Wolf 1018370e8328SKevin Wolf@item refcount-cache-size 1019370e8328SKevin WolfThe maximum size of the refcount block cache in bytes 102040fb215dSLeonid Bloch(default: 4 times the cluster size; or if cache-size is specified, the part of 102140fb215dSLeonid Blochit which is not used for the L2 cache) 1022370e8328SKevin Wolf 1023370e8328SKevin Wolf@item cache-clean-interval 1024370e8328SKevin WolfClean unused entries in the L2 and refcount caches. The interval is in seconds. 1025e3a7b455SLeonid BlochThe default value is 600 on supporting platforms, and 0 on other platforms. 1026e3a7b455SLeonid BlochSetting it to 0 disables this feature. 1027370e8328SKevin Wolf 1028370e8328SKevin Wolf@item pass-discard-request 1029370e8328SKevin WolfWhether discard requests to the qcow2 device should be forwarded to the data 1030370e8328SKevin Wolfsource (on/off; default: on if discard=unmap is specified, off otherwise) 1031370e8328SKevin Wolf 1032370e8328SKevin Wolf@item pass-discard-snapshot 1033370e8328SKevin WolfWhether discard requests for the data source should be issued when a snapshot 1034370e8328SKevin Wolfoperation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 1035370e8328SKevin Wolfdefault: on) 1036370e8328SKevin Wolf 1037370e8328SKevin Wolf@item pass-discard-other 1038370e8328SKevin WolfWhether discard requests for the data source should be issued on other 1039370e8328SKevin Wolfoccasions where a cluster gets freed (on/off; default: off) 1040370e8328SKevin Wolf 1041370e8328SKevin Wolf@item overlap-check 1042370e8328SKevin WolfWhich overlap checks to perform for writes to the image 1043370e8328SKevin Wolf(none/constant/cached/all; default: cached). For details or finer 1044370e8328SKevin Wolfgranularity control refer to the QAPI documentation of @code{blockdev-add}. 1045370e8328SKevin Wolf@end table 1046370e8328SKevin Wolf 1047370e8328SKevin WolfExample 1: 1048370e8328SKevin Wolf@example 1049370e8328SKevin Wolf-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 1050370e8328SKevin Wolf-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 1051370e8328SKevin Wolf@end example 1052370e8328SKevin WolfExample 2: 1053370e8328SKevin Wolf@example 1054370e8328SKevin Wolf-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 1055370e8328SKevin Wolf@end example 1056370e8328SKevin Wolf 1057370e8328SKevin Wolf@item Driver-specific options for other drivers 1058370e8328SKevin WolfPlease refer to the QAPI documentation of the @code{blockdev-add} QMP command. 1059370e8328SKevin Wolf 1060dfaca464SKevin Wolf@end table 1061dfaca464SKevin Wolf 1062dfaca464SKevin WolfETEXI 106342e5f393SMarkus Armbruster 10645824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 10655824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 106692196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 1067572023f7SKevin Wolf " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 1068d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 1069fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 10702f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 10713e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 10723e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 10733e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 10743e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 10752024c1dfSBenoît Canet " [[,iops_size=is]]\n" 107676f4afb4SAlberto Garcia " [[,group=g]]\n" 1077ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 10785824d651Sblueswir1STEXI 10795824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 10806616b2adSStefan Weil@findex -drive 10815824d651Sblueswir1 1082dfaca464SKevin WolfDefine a new drive. This includes creating a block driver node (the backend) as 1083dfaca464SKevin Wolfwell as a guest device, and is mostly a shortcut for defining the corresponding 1084dfaca464SKevin Wolf@option{-blockdev} and @option{-device} options. 1085dfaca464SKevin Wolf 1086dfaca464SKevin Wolf@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 1087dfaca464SKevin Wolfaddition, it knows the following options: 10885824d651Sblueswir1 1089b3f046c2SKevin Wolf@table @option 10905824d651Sblueswir1@item file=@var{file} 10915824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 10925824d651Sblueswir1this drive. If the filename contains comma, you must double it 10935824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 10940f5314a2SRonnie Sahlberg 10950f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 10960f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 10975824d651Sblueswir1@item if=@var{interface} 10985824d651Sblueswir1This option defines on which type on interface the drive is connected. 1099ed1fcd00SCraig JellickAvailable types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 11005824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 11015824d651Sblueswir1These options define where is connected the drive by defining the bus number and 11025824d651Sblueswir1the unit id. 11035824d651Sblueswir1@item index=@var{index} 11045824d651Sblueswir1This option defines where is connected the drive by using an index in the list 11055824d651Sblueswir1of available connectors of a given interface type. 11065824d651Sblueswir1@item media=@var{media} 11075824d651Sblueswir1This option defines the type of the media: disk or cdrom. 11085824d651Sblueswir1@item snapshot=@var{snapshot} 11099d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 11109d85d557SMichael Tokarev(see @option{-snapshot}). 11115824d651Sblueswir1@item cache=@var{cache} 1112dfaca464SKevin Wolf@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 1113dfaca464SKevin Wolfand controls how the host cache is used to access block data. This is a 1114dfaca464SKevin Wolfshortcut that sets the @option{cache.direct} and @option{cache.no-flush} 1115dfaca464SKevin Wolfoptions (as in @option{-blockdev}), and additionally @option{cache.writeback}, 1116dfaca464SKevin Wolfwhich provides a default for the @option{write-cache} option of block guest 1117dfaca464SKevin Wolfdevices (as in @option{-device}). The modes correspond to the following 1118dfaca464SKevin Wolfsettings: 1119dfaca464SKevin Wolf 1120dfaca464SKevin Wolf@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 1121dfaca464SKevin Wolf@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 1122dfaca464SKevin Wolf@c and the HTML output. 1123dfaca464SKevin Wolf@example 1124dfaca464SKevin Wolf@ │ cache.writeback cache.direct cache.no-flush 1125dfaca464SKevin Wolf─────────────┼───────────────────────────────────────────────── 1126dfaca464SKevin Wolfwriteback │ on off off 1127dfaca464SKevin Wolfnone │ on on off 1128dfaca464SKevin Wolfwritethrough │ off off off 1129dfaca464SKevin Wolfdirectsync │ off on off 1130dfaca464SKevin Wolfunsafe │ on off on 1131dfaca464SKevin Wolf@end example 1132dfaca464SKevin Wolf 1133dfaca464SKevin WolfThe default mode is @option{cache=writeback}. 1134dfaca464SKevin Wolf 11355c6c3a6cSChristoph Hellwig@item aio=@var{aio} 11365c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 11375824d651Sblueswir1@item format=@var{format} 11385824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 1139d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 11405824d651Sblueswir1an untrusted format header. 1141ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 1142ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 1143ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 1144ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 1145ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 1146ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 1147fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 1148fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 1149fb0490f6SStefan Hajnoczifile sectors into the image file. 115001f9cfabSStefan Hajnoczi@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 115101f9cfabSStefan HajnocziSpecify bandwidth throttling limits in bytes per second, either for all request 115201f9cfabSStefan Hajnoczitypes or for reads or writes only. Small values can lead to timeouts or hangs 115301f9cfabSStefan Hajnocziinside the guest. A safe minimum for disks is 2 MB/s. 115401f9cfabSStefan Hajnoczi@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 115501f9cfabSStefan HajnocziSpecify bursts in bytes per second, either for all request types or for reads 115601f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 115701f9cfabSStefan Hajnoczitemporarily. 115801f9cfabSStefan Hajnoczi@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 115901f9cfabSStefan HajnocziSpecify request rate limits in requests per second, either for all request 116001f9cfabSStefan Hajnoczitypes or for reads or writes only. 116101f9cfabSStefan Hajnoczi@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 116201f9cfabSStefan HajnocziSpecify bursts in requests per second, either for all request types or for reads 116301f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 116401f9cfabSStefan Hajnoczitemporarily. 116501f9cfabSStefan Hajnoczi@item iops_size=@var{is} 116601f9cfabSStefan HajnocziLet every @var{is} bytes of a request count as a new request for iops 116701f9cfabSStefan Hajnoczithrottling purposes. Use this option to prevent guests from circumventing iops 116801f9cfabSStefan Hajnoczilimits by sending fewer but larger requests. 116901f9cfabSStefan Hajnoczi@item group=@var{g} 117001f9cfabSStefan HajnocziJoin a throttling quota group with given name @var{g}. All drives that are 117101f9cfabSStefan Hajnoczimembers of the same group are accounted for together. Use this option to 117201f9cfabSStefan Hajnocziprevent guests from circumventing throttling limits by using many small disks 117301f9cfabSStefan Hajnocziinstead of a single larger disk. 11745824d651Sblueswir1@end table 11755824d651Sblueswir1 1176dfaca464SKevin WolfBy default, the @option{cache.writeback=on} mode is used. It will report data 1177a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 1178a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 1179a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 1180a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 1181a13e5e05SKevin Wolfdata corruption. 11825824d651Sblueswir1 1183dfaca464SKevin WolfFor such guests, you should consider using @option{cache.writeback=off}. This 1184a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 1185a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 1186a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 11875824d651Sblueswir1 1188dfaca464SKevin WolfWhen using the @option{-snapshot} option, unsafe caching is always used. 1189016f5cf6SAlexander Graf 1190fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 1191fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 1192fb0490f6SStefan Hajnocziis off. 1193fb0490f6SStefan Hajnoczi 11945824d651Sblueswir1Instead of @option{-cdrom} you can use: 11955824d651Sblueswir1@example 1196664785acSThomas Huth@value{qemu_system} -drive file=file,index=2,media=cdrom 11975824d651Sblueswir1@end example 11985824d651Sblueswir1 11995824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 12005824d651Sblueswir1use: 12015824d651Sblueswir1@example 1202664785acSThomas Huth@value{qemu_system} -drive file=file,index=0,media=disk 1203664785acSThomas Huth@value{qemu_system} -drive file=file,index=1,media=disk 1204664785acSThomas Huth@value{qemu_system} -drive file=file,index=2,media=disk 1205664785acSThomas Huth@value{qemu_system} -drive file=file,index=3,media=disk 12065824d651Sblueswir1@end example 12075824d651Sblueswir1 1208587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 1209587ed6beSCorey Bryant@example 1210664785acSThomas Huth@value{qemu_system} \ 1211664785acSThomas Huth -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 1212664785acSThomas Huth -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 1213587ed6beSCorey Bryant -drive file=/dev/fdset/2,index=0,media=disk 1214587ed6beSCorey Bryant@end example 1215587ed6beSCorey Bryant 12165824d651Sblueswir1You can connect a CDROM to the slave of ide0: 12175824d651Sblueswir1@example 1218664785acSThomas Huth@value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom 12195824d651Sblueswir1@end example 12205824d651Sblueswir1 12215824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 12225824d651Sblueswir1@example 1223664785acSThomas Huth@value{qemu_system_x86} -drive if=ide,index=1,media=cdrom 12245824d651Sblueswir1@end example 12255824d651Sblueswir1 12265824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 12275824d651Sblueswir1@example 1228664785acSThomas Huth@value{qemu_system_x86} -drive file=file,index=0,if=floppy 1229664785acSThomas Huth@value{qemu_system_x86} -drive file=file,index=1,if=floppy 12305824d651Sblueswir1@end example 12315824d651Sblueswir1 12325824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 12335824d651Sblueswir1incremented: 12345824d651Sblueswir1@example 1235664785acSThomas Huth@value{qemu_system_x86} -drive file=a -drive file=b" 12365824d651Sblueswir1@end example 12375824d651Sblueswir1is interpreted like: 12385824d651Sblueswir1@example 1239664785acSThomas Huth@value{qemu_system_x86} -hda a -hdb b 12405824d651Sblueswir1@end example 12415824d651Sblueswir1ETEXI 12425824d651Sblueswir1 12435824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 1244ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 1245ad96090aSBlue Swirl QEMU_ARCH_ALL) 12465824d651Sblueswir1STEXI 12474e257e5eSKevin Wolf@item -mtdblock @var{file} 12486616b2adSStefan Weil@findex -mtdblock 12494e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 12505824d651Sblueswir1ETEXI 12515824d651Sblueswir1 12525824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 1253ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 12545824d651Sblueswir1STEXI 12554e257e5eSKevin Wolf@item -sd @var{file} 12566616b2adSStefan Weil@findex -sd 12574e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 12585824d651Sblueswir1ETEXI 12595824d651Sblueswir1 12605824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 1261ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 12625824d651Sblueswir1STEXI 12634e257e5eSKevin Wolf@item -pflash @var{file} 12646616b2adSStefan Weil@findex -pflash 12654e257e5eSKevin WolfUse @var{file} as a parallel flash image. 12665824d651Sblueswir1ETEXI 12675824d651Sblueswir1 12685824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 1269ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 1270ad96090aSBlue Swirl QEMU_ARCH_ALL) 12715824d651Sblueswir1STEXI 12725824d651Sblueswir1@item -snapshot 12736616b2adSStefan Weil@findex -snapshot 12745824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 12755824d651Sblueswir1the raw disk image you use is not written back. You can however force 12765824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 12775824d651Sblueswir1ETEXI 12785824d651Sblueswir1 127974db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 1280b44a6b09SGreg Kurz "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n" 1281b44a6b09SGreg Kurz " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n" 1282b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1283b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1284b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1285b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1286b44a6b09SGreg Kurz " [[,throttling.iops-size=is]]\n" 1287b44a6b09SGreg Kurz "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n" 1288b44a6b09SGreg Kurz "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n" 1289b44a6b09SGreg Kurz "-fsdev synth,id=id\n", 129074db920cSGautham R Shenoy QEMU_ARCH_ALL) 129174db920cSGautham R Shenoy 129274db920cSGautham R ShenoySTEXI 129374db920cSGautham R Shenoy 1294b44a6b09SGreg 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}[,...]]] 1295b44a6b09SGreg Kurz@itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly] 1296b44a6b09SGreg Kurz@itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly] 1297b44a6b09SGreg Kurz@itemx -fsdev synth,id=@var{id}[,readonly] 129874db920cSGautham R Shenoy@findex -fsdev 12997c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 13007c92a3d2SAneesh Kumar K.V@table @option 1301b44a6b09SGreg Kurz@item local 1302b44a6b09SGreg KurzAccesses to the filesystem are done by QEMU. 1303b44a6b09SGreg Kurz@item proxy 1304b44a6b09SGreg KurzAccesses to the filesystem are done by virtfs-proxy-helper(1). 1305b44a6b09SGreg Kurz@item synth 1306b44a6b09SGreg KurzSynthetic filesystem, only used by QTests. 13077c92a3d2SAneesh Kumar K.V@item id=@var{id} 1308b44a6b09SGreg KurzSpecifies identifier for this device. 13097c92a3d2SAneesh Kumar K.V@item path=@var{path} 13107c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 13117c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 13127c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 13137c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 13142c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 13157c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1316b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 13172c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 13187c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 13192c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 13202c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 13217c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 13227c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1323d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 132493aee84fSGreg Kurzonly for local fsdriver. Other fsdrivers (like proxy) don't take 1325d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 13267c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 13277c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 13287c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 13297c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 13307c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 13312c74c2cbSM. Mohan Kumar@item readonly 13322c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 13332c74c2cbSM. Mohan Kumarread-write access is given. 133484a87cc4SM. Mohan Kumar@item socket=@var{socket} 133584a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 1336b44a6b09SGreg Kurzwith virtfs-proxy-helper(1). 1337f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 1338f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 1339b44a6b09SGreg Kurzcommunicating with virtfs-proxy-helper(1). Usually a helper like libvirt 1340b44a6b09SGreg Kurzwill create socketpair and pass one of the fds as sock_fd. 1341b96feb2cSTobias Schramm@item fmode=@var{fmode} 1342b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1343b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1344b96feb2cSTobias Schramm@item dmode=@var{dmode} 1345b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1346b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 1347b44a6b09SGreg Kurz@item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w} 1348b44a6b09SGreg KurzSpecify bandwidth throttling limits in bytes per second, either for all request 1349b44a6b09SGreg Kurztypes or for reads or writes only. 1350b44a6b09SGreg Kurz@item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm} 1351b44a6b09SGreg KurzSpecify bursts in bytes per second, either for all request types or for reads 1352b44a6b09SGreg Kurzor writes only. Bursts allow the guest I/O to spike above the limit 1353b44a6b09SGreg Kurztemporarily. 1354b44a6b09SGreg Kurz@item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w} 1355b44a6b09SGreg KurzSpecify request rate limits in requests per second, either for all request 1356b44a6b09SGreg Kurztypes or for reads or writes only. 1357b44a6b09SGreg Kurz@item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm} 1358b44a6b09SGreg KurzSpecify bursts in requests per second, either for all request types or for reads 1359b44a6b09SGreg Kurzor writes only. Bursts allow the guest I/O to spike above the limit temporarily. 1360b44a6b09SGreg Kurz@item throttling.iops-size=@var{is} 1361b44a6b09SGreg KurzLet every @var{is} bytes of a request count as a new request for iops 1362b44a6b09SGreg Kurzthrottling purposes. 136374db920cSGautham R Shenoy@end table 13647c92a3d2SAneesh Kumar K.V 1365b44a6b09SGreg Kurz-fsdev option is used along with -device driver "virtio-9p-...". 1366b44a6b09SGreg Kurz@item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag} 1367b44a6b09SGreg KurzOptions for virtio-9p-... driver are: 13687c92a3d2SAneesh Kumar K.V@table @option 1369b44a6b09SGreg Kurz@item @var{type} 1370b44a6b09SGreg KurzSpecifies the variant to be used. Supported values are "pci", "ccw" or "device", 1371b44a6b09SGreg Kurzdepending on the machine type. 13727c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 1373b44a6b09SGreg KurzSpecifies the id value specified along with -fsdev option. 13747c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 1375b44a6b09SGreg KurzSpecifies the tag name to be used by the guest to mount this export point. 13767c92a3d2SAneesh Kumar K.V@end table 13777c92a3d2SAneesh Kumar K.V 137874db920cSGautham R ShenoyETEXI 137974db920cSGautham R Shenoy 13803d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 1381b44a6b09SGreg Kurz "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n" 13821a6ed33cSAntonios Motakis " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n" 1383b44a6b09SGreg Kurz "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n" 1384b44a6b09SGreg Kurz "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n" 1385b44a6b09SGreg Kurz "-virtfs synth,mount_tag=tag[,id=id][,readonly]\n", 13863d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 13873d54abc7SGautham R Shenoy 13883d54abc7SGautham R ShenoySTEXI 13893d54abc7SGautham R Shenoy 13901a6ed33cSAntonios 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}] 1391b44a6b09SGreg Kurz@itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 1392b44a6b09SGreg Kurz@itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 1393b44a6b09SGreg Kurz@itemx -virtfs synth,mount_tag=@var{mount_tag} 13943d54abc7SGautham R Shenoy@findex -virtfs 13953d54abc7SGautham R Shenoy 1396b44a6b09SGreg 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: 13977c92a3d2SAneesh Kumar K.V@table @option 1398b44a6b09SGreg Kurz@item local 1399b44a6b09SGreg KurzAccesses to the filesystem are done by QEMU. 1400b44a6b09SGreg Kurz@item proxy 1401b44a6b09SGreg KurzAccesses to the filesystem are done by virtfs-proxy-helper(1). 1402b44a6b09SGreg Kurz@item synth 1403b44a6b09SGreg KurzSynthetic filesystem, only used by QTests. 14047c92a3d2SAneesh Kumar K.V@item id=@var{id} 1405b44a6b09SGreg KurzSpecifies identifier for the filesystem device 14067c92a3d2SAneesh Kumar K.V@item path=@var{path} 14077c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 14087c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 14097c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 14107c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 14112c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 14127c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1413b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 14142c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 14157c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 14162c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 14172c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 14187c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 14197c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1420d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 142193aee84fSGreg Kurzfor local fsdriver. Other fsdrivers (like proxy) don't take security 1422d9b36a6eSM. Mohan Kumarmodel as a parameter. 14237c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 14247c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 14257c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 14267c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 14277c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 14282c74c2cbSM. Mohan Kumar@item readonly 14292c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 14302c74c2cbSM. Mohan Kumarread-write access is given. 143184a87cc4SM. Mohan Kumar@item socket=@var{socket} 143284a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 1433b44a6b09SGreg Kurzcommunicating with virtfs-proxy-helper(1). Usually a helper like libvirt 1434b44a6b09SGreg Kurzwill create socketpair and pass one of the fds as sock_fd. 1435f67e3ffdSM. Mohan Kumar@item sock_fd 1436f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 1437b44a6b09SGreg Kurzdescriptor for interfacing with virtfs-proxy-helper(1). 1438b96feb2cSTobias Schramm@item fmode=@var{fmode} 1439b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1440b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1441b96feb2cSTobias Schramm@item dmode=@var{dmode} 1442b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1443b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 1444b44a6b09SGreg Kurz@item mount_tag=@var{mount_tag} 1445b44a6b09SGreg KurzSpecifies the tag name to be used by the guest to mount this export point. 14461a6ed33cSAntonios Motakis@item multidevs=@var{multidevs} 14471a6ed33cSAntonios MotakisSpecifies how to deal with multiple devices being shared with a 9p export. 14481a6ed33cSAntonios MotakisSupported behaviours are either "remap", "forbid" or "warn". The latter is 14491a6ed33cSAntonios Motakisthe default behaviour on which virtfs 9p expects only one device to be 14501a6ed33cSAntonios Motakisshared with the same export, and if more than one device is shared and 14511a6ed33cSAntonios Motakisaccessed via the same 9p export then only a warning message is logged 14521a6ed33cSAntonios Motakis(once) by qemu on host side. In order to avoid file ID collisions on guest 14531a6ed33cSAntonios Motakisyou should either create a separate virtfs export for each device to be 14541a6ed33cSAntonios Motakisshared with guests (recommended way) or you might use "remap" instead which 14551a6ed33cSAntonios Motakisallows you to share multiple devices with only one export instead, which is 14561a6ed33cSAntonios Motakisachieved by remapping the original inode numbers from host to guest in a 14571a6ed33cSAntonios Motakisway that would prevent such collisions. Remapping inodes in such use cases 14581a6ed33cSAntonios Motakisis required because the original device IDs from host are never passed and 14591a6ed33cSAntonios Motakisexposed on guest. Instead all files of an export shared with virtfs always 14601a6ed33cSAntonios Motakisshare the same device id on guest. So two files with identical inode 14611a6ed33cSAntonios Motakisnumbers but from actually different devices on host would otherwise cause a 14621a6ed33cSAntonios Motakisfile ID collision and hence potential misbehaviours on guest. "forbid" on 14631a6ed33cSAntonios Motakisthe other hand assumes like "warn" that only one device is shared by the 14641a6ed33cSAntonios Motakissame export, however it will not only log a warning message but also 14651a6ed33cSAntonios Motakisdeny access to additional devices on guest. Note though that "forbid" does 14661a6ed33cSAntonios Motakiscurrently not block all possible file access operations (e.g. readdir() 14671a6ed33cSAntonios Motakiswould still return entries from other devices). 14683d54abc7SGautham R Shenoy@end table 14693d54abc7SGautham R ShenoyETEXI 14703d54abc7SGautham R Shenoy 14719db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 14729db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 14739db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 14749db221aeSAneesh Kumar K.VSTEXI 14759db221aeSAneesh Kumar K.V@item -virtfs_synth 14769db221aeSAneesh Kumar K.V@findex -virtfs_synth 14776e4199afSGreg KurzCreate synthetic file system image. Note that this option is now deprecated. 14786e4199afSGreg KurzPlease use @code{-fsdev synth} and @code{-device virtio-9p-...} instead. 14799db221aeSAneesh Kumar K.VETEXI 14809db221aeSAneesh Kumar K.V 148161d70487SMarkus ArmbrusterDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 148261d70487SMarkus Armbruster "-iscsi [user=user][,password=password]\n" 148361d70487SMarkus Armbruster " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 148461d70487SMarkus Armbruster " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 148561d70487SMarkus Armbruster " [,timeout=timeout]\n" 148661d70487SMarkus Armbruster " iSCSI session parameters\n", QEMU_ARCH_ALL) 148761d70487SMarkus Armbruster 14885824d651Sblueswir1STEXI 148944743148SMarkus Armbruster@item -iscsi 149044743148SMarkus Armbruster@findex -iscsi 149144743148SMarkus ArmbrusterConfigure iSCSI session parameters. 149244743148SMarkus ArmbrusterETEXI 149344743148SMarkus Armbruster 149444743148SMarkus ArmbrusterSTEXI 14955824d651Sblueswir1@end table 14965824d651Sblueswir1ETEXI 14975824d651Sblueswir1DEFHEADING() 14985824d651Sblueswir1 1499de6b4f90SMarkus ArmbrusterDEFHEADING(USB options:) 150010adb8beSMarkus ArmbrusterSTEXI 150110adb8beSMarkus Armbruster@table @option 150210adb8beSMarkus ArmbrusterETEXI 150310adb8beSMarkus Armbruster 150410adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 150573f46fefSStefan Hajnoczi "-usb enable on-board USB host controller (if not enabled by default)\n", 150610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 150710adb8beSMarkus ArmbrusterSTEXI 150810adb8beSMarkus Armbruster@item -usb 150910adb8beSMarkus Armbruster@findex -usb 151073f46fefSStefan HajnocziEnable USB emulation on machine types with an on-board USB host controller (if 151173f46fefSStefan Hajnoczinot enabled by default). Note that on-board USB host controllers may not 151273f46fefSStefan Hajnoczisupport USB 3.0. In this case @option{-device qemu-xhci} can be used instead 151373f46fefSStefan Hajnoczion machines with PCI. 151410adb8beSMarkus ArmbrusterETEXI 151510adb8beSMarkus Armbruster 151610adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 151710adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 151810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 151910adb8beSMarkus ArmbrusterSTEXI 152010adb8beSMarkus Armbruster 152110adb8beSMarkus Armbruster@item -usbdevice @var{devname} 152210adb8beSMarkus Armbruster@findex -usbdevice 1523a358a3afSThomas HuthAdd the USB device @var{devname}. Note that this option is deprecated, 1524a358a3afSThomas Huthplease use @code{-device usb-...} instead. @xref{usb_devices}. 152510adb8beSMarkus Armbruster 152610adb8beSMarkus Armbruster@table @option 152710adb8beSMarkus Armbruster 152810adb8beSMarkus Armbruster@item mouse 152910adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 153010adb8beSMarkus Armbruster 153110adb8beSMarkus Armbruster@item tablet 153210adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 153310adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 153410adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 153510adb8beSMarkus Armbruster 153610adb8beSMarkus Armbruster@item braille 153710adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 153810adb8beSMarkus Armbrusteror fake device. 153910adb8beSMarkus Armbruster 154010adb8beSMarkus Armbruster@end table 154110adb8beSMarkus ArmbrusterETEXI 154210adb8beSMarkus Armbruster 154310adb8beSMarkus ArmbrusterSTEXI 154410adb8beSMarkus Armbruster@end table 154510adb8beSMarkus ArmbrusterETEXI 154610adb8beSMarkus ArmbrusterDEFHEADING() 154710adb8beSMarkus Armbruster 1548de6b4f90SMarkus ArmbrusterDEFHEADING(Display options:) 15495824d651Sblueswir1STEXI 15505824d651Sblueswir1@table @option 15515824d651Sblueswir1ETEXI 15525824d651Sblueswir1 15531472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 155488b40c68SThomas Huth#if defined(CONFIG_SPICE) 1555d8aec9d9SMarc-André Lureau "-display spice-app[,gl=on|off]\n" 155688b40c68SThomas Huth#endif 155788b40c68SThomas Huth#if defined(CONFIG_SDL) 155888b40c68SThomas Huth "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n" 15594867e47cSElie Tournier " [,window_close=on|off][,gl=on|core|es|off]\n" 156088b40c68SThomas Huth#endif 156188b40c68SThomas Huth#if defined(CONFIG_GTK) 1562f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 156388b40c68SThomas Huth#endif 156488b40c68SThomas Huth#if defined(CONFIG_VNC) 1565f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 156688b40c68SThomas Huth#endif 156788b40c68SThomas Huth#if defined(CONFIG_CURSES) 15682f8b7cd5SSamuel Thibault "-display curses[,charset=<encoding>]\n" 156988b40c68SThomas Huth#endif 157088b40c68SThomas Huth#if defined(CONFIG_OPENGL) 157188b40c68SThomas Huth "-display egl-headless[,rendernode=<file>]\n" 157288b40c68SThomas Huth#endif 1573144aaa99SErik Skultety "-display none\n" 157488b40c68SThomas Huth " select display backend type\n" 1575f04ec5afSRobert Ho " The default display is equivalent to\n " 1576f04ec5afSRobert Ho#if defined(CONFIG_GTK) 157788b40c68SThomas Huth "\"-display gtk\"\n" 1578f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 157988b40c68SThomas Huth "\"-display sdl\"\n" 1580f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 158188b40c68SThomas Huth "\"-display cocoa\"\n" 1582f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 158388b40c68SThomas Huth "\"-vnc localhost:0,to=99,id=default\"\n" 1584f04ec5afSRobert Ho#else 158588b40c68SThomas Huth "\"-display none\"\n" 1586f04ec5afSRobert Ho#endif 1587f04ec5afSRobert Ho , QEMU_ARCH_ALL) 15881472a95bSJes SorensenSTEXI 15891472a95bSJes Sorensen@item -display @var{type} 15901472a95bSJes Sorensen@findex -display 15911472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 15921472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 15931472a95bSJes Sorensen@table @option 15941472a95bSJes Sorensen@item sdl 15951472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 15961472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 15971472a95bSJes Sorensen@item curses 15981472a95bSJes SorensenDisplay video output via curses. For graphics device models which 15991472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 16001472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 16011472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 16021472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 16032f8b7cd5SSamuel ThibaultThe font charset used by the guest can be specified with the 16042f8b7cd5SSamuel Thibault@code{charset} option, for example @code{charset=CP850} for IBM CP850 16052f8b7cd5SSamuel Thibaultencoding. The default is @code{CP437}. 16064171d32eSJes Sorensen@item none 16074171d32eSJes SorensenDo not display video output. The guest will still see an emulated 16084171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 16094171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 16104171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 16114171d32eSJes Sorensenthe destination of the serial and parallel port data. 1612881249c7SJan Kiszka@item gtk 1613881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 1614881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 1615881249c7SJan Kiszkaruntime. 16163264ff12SJes Sorensen@item vnc 16173264ff12SJes SorensenStart a VNC server on display <arg> 1618144aaa99SErik Skultety@item egl-headless 1619144aaa99SErik SkultetyOffload all OpenGL operations to a local DRI device. For any graphical display, 1620144aaa99SErik Skultetythis display needs to be paired with either VNC or SPICE displays. 1621d8aec9d9SMarc-André Lureau@item spice-app 1622d8aec9d9SMarc-André LureauStart QEMU as a Spice server and launch the default Spice client 1623d8aec9d9SMarc-André Lureauapplication. The Spice server will redirect the serial consoles and 1624d8aec9d9SMarc-André LureauQEMU monitors. (Since 4.0) 16251472a95bSJes Sorensen@end table 16261472a95bSJes SorensenETEXI 16271472a95bSJes Sorensen 16285824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 1629ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1630ad96090aSBlue Swirl QEMU_ARCH_ALL) 16315824d651Sblueswir1STEXI 16325824d651Sblueswir1@item -nographic 16336616b2adSStefan Weil@findex -nographic 1634dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1635dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1636dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1637dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1638dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1639dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1640dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1641dc0a3e44SColin Lordswitching between the console and monitor. 16425824d651Sblueswir1ETEXI 16435824d651Sblueswir1 16445824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1645f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1646ad96090aSBlue Swirl QEMU_ARCH_ALL) 16475824d651Sblueswir1STEXI 16485824d651Sblueswir1@item -curses 1649b8f490ebSMarkus Armbruster@findex -curses 1650dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1651dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1652dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1653dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1654dc0a3e44SColin Lordmode. 16555824d651Sblueswir1ETEXI 16565824d651Sblueswir1 16575824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1658ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1659ad96090aSBlue Swirl QEMU_ARCH_ALL) 16605824d651Sblueswir1STEXI 16615824d651Sblueswir1@item -alt-grab 16626616b2adSStefan Weil@findex -alt-grab 1663de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1664de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 16655824d651Sblueswir1ETEXI 16665824d651Sblueswir1 16670ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1668ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1669ad96090aSBlue Swirl QEMU_ARCH_ALL) 16700ca9f8a4SDustin KirklandSTEXI 16710ca9f8a4SDustin Kirkland@item -ctrl-grab 16726616b2adSStefan Weil@findex -ctrl-grab 1673de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1674de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 16750ca9f8a4SDustin KirklandETEXI 16760ca9f8a4SDustin Kirkland 16775824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1678ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 16795824d651Sblueswir1STEXI 16805824d651Sblueswir1@item -no-quit 16816616b2adSStefan Weil@findex -no-quit 16825824d651Sblueswir1Disable SDL window close capability. 16835824d651Sblueswir1ETEXI 16845824d651Sblueswir1 16855824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1686f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 16875824d651Sblueswir1STEXI 16885824d651Sblueswir1@item -sdl 16896616b2adSStefan Weil@findex -sdl 16905824d651Sblueswir1Enable SDL. 16915824d651Sblueswir1ETEXI 16925824d651Sblueswir1 169329b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 169427af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 169527af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 169627af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1697fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 169827af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 169927af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 170027af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 170127af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 170227af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 170327af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 170427af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 170527af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 17065ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 17075ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 17087b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 170927af7788SYonit Halperin " enable spice\n" 171027af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 171127af7788SYonit Halperin QEMU_ARCH_ALL) 171229b0040bSGerd HoffmannSTEXI 171329b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 171429b0040bSGerd Hoffmann@findex -spice 171529b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 171629b0040bSGerd Hoffmann 171729b0040bSGerd Hoffmann@table @option 171829b0040bSGerd Hoffmann 171929b0040bSGerd Hoffmann@item port=<nr> 1720c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 172129b0040bSGerd Hoffmann 1722333b0eebSGerd Hoffmann@item addr=<addr> 1723333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1724333b0eebSGerd Hoffmann 1725333b0eebSGerd Hoffmann@item ipv4 1726f9cfd655SMarkus Armbruster@itemx ipv6 1727f9cfd655SMarkus Armbruster@itemx unix 1728333b0eebSGerd HoffmannForce using the specified IP version. 1729333b0eebSGerd Hoffmann 173029b0040bSGerd Hoffmann@item password=<secret> 173129b0040bSGerd HoffmannSet the password you need to authenticate. 173229b0040bSGerd Hoffmann 173348b3ed0aSMarc-André Lureau@item sasl 173448b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 173548b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 173648b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 173748b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 173848b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 173948b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 174048b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 174148b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 174248b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 174348b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 174448b3ed0aSMarc-André Lureaucredentials. 174548b3ed0aSMarc-André Lureau 174629b0040bSGerd Hoffmann@item disable-ticketing 174729b0040bSGerd HoffmannAllow client connects without authentication. 174829b0040bSGerd Hoffmann 1749d4970b07SHans de Goede@item disable-copy-paste 1750d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1751d4970b07SHans de Goede 17525ad24e5fSHans de Goede@item disable-agent-file-xfer 17535ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 17545ad24e5fSHans de Goede 1755c448e855SGerd Hoffmann@item tls-port=<nr> 1756c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1757c448e855SGerd Hoffmann 1758c448e855SGerd Hoffmann@item x509-dir=<dir> 1759c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1760c448e855SGerd Hoffmann 1761c448e855SGerd Hoffmann@item x509-key-file=<file> 1762f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1763f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1764f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1765f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1766c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1767c448e855SGerd Hoffmann 1768c448e855SGerd Hoffmann@item tls-ciphers=<list> 1769c448e855SGerd HoffmannSpecify which ciphers to use. 1770c448e855SGerd Hoffmann 1771d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1772f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 177317b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 177417b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 177517b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 177617b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 177717b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 177817b6dea0SGerd Hoffmann 17799f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 17809f04e09eSYonit HalperinConfigure image compression (lossless). 17819f04e09eSYonit HalperinDefault is auto_glz. 17829f04e09eSYonit Halperin 17839f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1784f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 17859f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 17869f04e09eSYonit HalperinDefault is auto. 17879f04e09eSYonit Halperin 178884a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 178993ca519eSLi ZhijianConfigure video stream detection. Default is off. 179084a23f25SGerd Hoffmann 179184a23f25SGerd Hoffmann@item agent-mouse=[on|off] 179284a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 179384a23f25SGerd Hoffmann 179484a23f25SGerd Hoffmann@item playback-compression=[on|off] 179584a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 179684a23f25SGerd Hoffmann 17978c957053SYonit Halperin@item seamless-migration=[on|off] 17988c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 17998c957053SYonit Halperin 1800474114b7SGerd Hoffmann@item gl=[on|off] 1801474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1802474114b7SGerd Hoffmann 18037b525508SMarc-André Lureau@item rendernode=<file> 18047b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 18057b525508SMarc-André Lureauthe first available. (Since 2.9) 18067b525508SMarc-André Lureau 180729b0040bSGerd Hoffmann@end table 180829b0040bSGerd HoffmannETEXI 180929b0040bSGerd Hoffmann 18105824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1811ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1812ad96090aSBlue Swirl QEMU_ARCH_ALL) 18135824d651Sblueswir1STEXI 18145824d651Sblueswir1@item -portrait 18156616b2adSStefan Weil@findex -portrait 18165824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 18175824d651Sblueswir1ETEXI 18185824d651Sblueswir1 18199312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 18209312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 18219312805dSVasily Khoruzhick QEMU_ARCH_ALL) 18229312805dSVasily KhoruzhickSTEXI 18236265c43bSMarkus Armbruster@item -rotate @var{deg} 18249312805dSVasily Khoruzhick@findex -rotate 18259312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 18269312805dSVasily KhoruzhickETEXI 18279312805dSVasily Khoruzhick 18285824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1829a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1830ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 18315824d651Sblueswir1STEXI 1832e4558dcaSmalc@item -vga @var{type} 18336616b2adSStefan Weil@findex -vga 18345824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1835b3f046c2SKevin Wolf@table @option 18365824d651Sblueswir1@item cirrus 18375824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 18385824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 18395824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 184041eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 18415824d651Sblueswir1@item std 18425824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 18435824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 18445824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 184541eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 18465824d651Sblueswir1@item vmware 18475824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 18485824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 18495824d651Sblueswir1card. 1850a19cbfb3SGerd Hoffmann@item qxl 1851a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1852a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1853a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 185433632788SMark Cave-Ayland@item tcx 185533632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 185633632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 185733632788SMark Cave-Aylandfixed resolution of 1024x768. 185833632788SMark Cave-Ayland@item cg3 185933632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 186033632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 186133632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1862a94f0c5cSGerd Hoffmann@item virtio 1863a94f0c5cSGerd HoffmannVirtio VGA card. 18645824d651Sblueswir1@item none 18655824d651Sblueswir1Disable VGA card. 18665824d651Sblueswir1@end table 18675824d651Sblueswir1ETEXI 18685824d651Sblueswir1 18695824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1870ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 18715824d651Sblueswir1STEXI 18725824d651Sblueswir1@item -full-screen 18736616b2adSStefan Weil@findex -full-screen 18745824d651Sblueswir1Start in full screen. 18755824d651Sblueswir1ETEXI 18765824d651Sblueswir1 18775824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1878ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 18798ac919a0SLaurent Vivier QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K) 18805824d651Sblueswir1STEXI 188195d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 18826616b2adSStefan Weil@findex -g 188395d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 18845824d651Sblueswir1ETEXI 18855824d651Sblueswir1 18865824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1887f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 18885824d651Sblueswir1STEXI 18895824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 18906616b2adSStefan Weil@findex -vnc 1891dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1892dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1893dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1894dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1895dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1896a358a3afSThomas Huth(option @option{-device usb-tablet}). When using the VNC display, you 1897dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1898dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 18995824d651Sblueswir1 1900b3f046c2SKevin Wolf@table @option 19015824d651Sblueswir1 190299a9a52aSRobert Ho@item to=@var{L} 190399a9a52aSRobert Ho 190499a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 190599a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 190699a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 190799a9a52aSRobert Hoapplication. By default, to=0. 190899a9a52aSRobert Ho 19095824d651Sblueswir1@item @var{host}:@var{d} 19105824d651Sblueswir1 19115824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 19125824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 19135824d651Sblueswir1be omitted in which case the server will accept connections from any host. 19145824d651Sblueswir1 19154e257e5eSKevin Wolf@item unix:@var{path} 19165824d651Sblueswir1 19175824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 19185824d651Sblueswir1location of a unix socket to listen for connections on. 19195824d651Sblueswir1 19205824d651Sblueswir1@item none 19215824d651Sblueswir1 19225824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 19235824d651Sblueswir1can be used to later start the VNC server. 19245824d651Sblueswir1 19255824d651Sblueswir1@end table 19265824d651Sblueswir1 19275824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 19285824d651Sblueswir1separated by commas. Valid options are 19295824d651Sblueswir1 1930b3f046c2SKevin Wolf@table @option 19315824d651Sblueswir1 19325824d651Sblueswir1@item reverse 19335824d651Sblueswir1 19345824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 19355824d651Sblueswir1client is specified by the @var{display}. For reverse network 19365824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 19375824d651Sblueswir1is a TCP port number, not a display number. 19385824d651Sblueswir1 19397536ee4bSTim Hardeck@item websocket 19407536ee4bSTim Hardeck 19417536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1942275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 1943275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 1944275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 1945275e0d61SDaniel P. Berrange 1946275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 1947275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 1948275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 1949275e0d61SDaniel P. Berrange 19503e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 19513e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 19523e305e4aSDaniel P. Berrangerequires encrypted client connections. 19537536ee4bSTim Hardeck 19545824d651Sblueswir1@item password 19555824d651Sblueswir1 19565824d651Sblueswir1Require that password based authentication is used for client connections. 195786ee5bc3SMichal Novotny 195886ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 195986ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 196086ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 196186ee5bc3SMichal Novotny"vnc" or "spice". 196286ee5bc3SMichal Novotny 196386ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 196486ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 196586ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 196686ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 196786ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 196886ee5bc3SMichal Novotnydate and time). 196986ee5bc3SMichal Novotny 197086ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 197186ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 19725824d651Sblueswir1 19733e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 19743e305e4aSDaniel P. Berrange 19753e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 19763e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 19773e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 19783e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 19793e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 19803e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 19813e305e4aSDaniel P. Berrange 198255cf09a0SDaniel P. Berrange@item tls-authz=@var{ID} 198355cf09a0SDaniel P. Berrange 198455cf09a0SDaniel P. BerrangeProvides the ID of the QAuthZ authorization object against which 198555cf09a0SDaniel P. Berrangethe client's x509 distinguished name will validated. This object is 198655cf09a0SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the 198755cf09a0SDaniel P. Berrangefly while the VNC server is active. If missing, it will default 198855cf09a0SDaniel P. Berrangeto denying access. 198955cf09a0SDaniel P. Berrange 19905824d651Sblueswir1@item sasl 19915824d651Sblueswir1 19925824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 19935824d651Sblueswir1The exact choice of authentication method used is controlled from the 19945824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 19955824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 19965824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 19975824d651Sblueswir1to make it search alternate locations for the service config. 19985824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 19995824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 20005824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 20015824d651Sblueswir1ensures a data encryption preventing compromise of authentication 20025824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 20035824d651Sblueswir1SASL authentication. 20045824d651Sblueswir1 200555cf09a0SDaniel P. Berrange@item sasl-authz=@var{ID} 200655cf09a0SDaniel P. Berrange 200755cf09a0SDaniel P. BerrangeProvides the ID of the QAuthZ authorization object against which 200855cf09a0SDaniel P. Berrangethe client's SASL username will validated. This object is 200955cf09a0SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the 201055cf09a0SDaniel P. Berrangefly while the VNC server is active. If missing, it will default 201155cf09a0SDaniel P. Berrangeto denying access. 201255cf09a0SDaniel P. Berrange 20135824d651Sblueswir1@item acl 20145824d651Sblueswir1 201555cf09a0SDaniel P. BerrangeLegacy method for enabling authorization of clients against the 201655cf09a0SDaniel P. Berrangex509 distinguished name and SASL username. It results in the creation 201755cf09a0SDaniel P. Berrangeof two @code{authz-list} objects with IDs of @code{vnc.username} and 201855cf09a0SDaniel P. Berrange@code{vnc.x509dname}. The rules for these objects must be configured 201955cf09a0SDaniel P. Berrangewith the HMP ACL commands. 202055cf09a0SDaniel P. Berrange 202155cf09a0SDaniel P. BerrangeThis option is deprecated and should no longer be used. The new 202255cf09a0SDaniel P. Berrange@option{sasl-authz} and @option{tls-authz} options are a 202355cf09a0SDaniel P. Berrangereplacement. 20245824d651Sblueswir1 20256f9c78c1SCorentin Chary@item lossy 20266f9c78c1SCorentin Chary 20276f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 20286f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 20296f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 20306f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 20316f9c78c1SCorentin Chary 203280e0c8c3SCorentin Chary@item non-adaptive 203380e0c8c3SCorentin Chary 203480e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 203580e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 203680e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 203761cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 20389d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 203980e0c8c3SCorentin Charylike Tight. 204080e0c8c3SCorentin Chary 20418cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 20428cf36489SGerd Hoffmann 20438cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 20448cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 20458cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 20468cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 20478cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 20488cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 20498cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 20508cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 20518cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 2052b65ee4faSStefan Weilspec but is traditional QEMU behavior. 20538cf36489SGerd Hoffmann 2054c5ce8333SGerd Hoffmann@item key-delay-ms 2055c5ce8333SGerd Hoffmann 2056c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 2057d3b0db6dSAlexander GrafDefault is 10. Keyboards are low-bandwidth devices, so this slowdown 2058c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 2059c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 2060c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 2061c5ce8333SGerd Hoffmann 2062f0b9f36dSKővágó, Zoltán@item audiodev=@var{audiodev} 2063f0b9f36dSKővágó, Zoltán 2064f0b9f36dSKővágó, ZoltánUse the specified @var{audiodev} when the VNC client requests audio 2065f0b9f36dSKővágó, Zoltántransmission. When not using an -audiodev argument, this option must 2066f0b9f36dSKővágó, Zoltánbe omitted, otherwise is must be present and specify a valid audiodev. 2067f0b9f36dSKővágó, Zoltán 20685824d651Sblueswir1@end table 20695824d651Sblueswir1ETEXI 20705824d651Sblueswir1 20715824d651Sblueswir1STEXI 20725824d651Sblueswir1@end table 20735824d651Sblueswir1ETEXI 2074a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 20755824d651Sblueswir1 2076de6b4f90SMarkus ArmbrusterARCHHEADING(i386 target only:, QEMU_ARCH_I386) 20775824d651Sblueswir1STEXI 20785824d651Sblueswir1@table @option 20795824d651Sblueswir1ETEXI 20805824d651Sblueswir1 20815824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 2082ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 2083ad96090aSBlue Swirl QEMU_ARCH_I386) 20845824d651Sblueswir1STEXI 20855824d651Sblueswir1@item -win2k-hack 20866616b2adSStefan Weil@findex -win2k-hack 20875824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 20885824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 20895824d651Sblueswir1slows down the IDE transfers). 20905824d651Sblueswir1ETEXI 20915824d651Sblueswir1 20925824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 2093ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 2094ad96090aSBlue Swirl QEMU_ARCH_I386) 20955824d651Sblueswir1STEXI 20965824d651Sblueswir1@item -no-fd-bootchk 20976616b2adSStefan Weil@findex -no-fd-bootchk 20984eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 20995824d651Sblueswir1be needed to boot from old floppy disks. 21005824d651Sblueswir1ETEXI 21015824d651Sblueswir1 21025824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 2103f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 21045824d651Sblueswir1STEXI 21055824d651Sblueswir1@item -no-acpi 21066616b2adSStefan Weil@findex -no-acpi 21075824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 21085824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 21095824d651Sblueswir1only). 21105824d651Sblueswir1ETEXI 21115824d651Sblueswir1 21125824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 2113ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 21145824d651Sblueswir1STEXI 21155824d651Sblueswir1@item -no-hpet 21166616b2adSStefan Weil@findex -no-hpet 21175824d651Sblueswir1Disable HPET support. 21185824d651Sblueswir1ETEXI 21195824d651Sblueswir1 21205824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 2121104bf02eSMichael 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" 2122ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 21235824d651Sblueswir1STEXI 21245824d651Sblueswir1@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}]...] 21256616b2adSStefan Weil@findex -acpitable 21265824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 2127104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 2128104bf02eSMichael TokarevACPI headers (possible overridden by other options). 2129104bf02eSMichael TokarevFor data=, only data 2130104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 2131104bf02eSMichael Tokarevcommand line. 2132ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 2133ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 2134ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 2135ae123749SLaszlo Ersekspec. 21365824d651Sblueswir1ETEXI 21375824d651Sblueswir1 2138b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 2139b6f6e3d3Saliguori "-smbios file=binary\n" 2140ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 2141b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 2142b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 2143ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 2144b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2145b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 2146b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 2147b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2148b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 2149b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 2150b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 2151b155eb1dSGabriel L. Somlo " [,sku=str]\n" 2152b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 2153b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 2154b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 2155b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 2156b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 21573ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 2158b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 2159c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 2160b6f6e3d3SaliguoriSTEXI 2161b6f6e3d3Saliguori@item -smbios file=@var{binary} 21626616b2adSStefan Weil@findex -smbios 2163b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 2164b6f6e3d3Saliguori 216584351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 2166b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 2167b6f6e3d3Saliguori 2168b6f6e3d3Saliguori@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}] 2169b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 2170b155eb1dSGabriel L. Somlo 21713fdbd1d7SIgor Mammedov@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}] 2172b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 2173b155eb1dSGabriel L. Somlo 2174b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 2175b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 2176b155eb1dSGabriel L. Somlo 2177b155eb1dSGabriel 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}] 2178b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 2179b155eb1dSGabriel L. Somlo 21803ebd6cc8SGabriel 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}] 2181b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 2182b6f6e3d3SaliguoriETEXI 2183b6f6e3d3Saliguori 21845824d651Sblueswir1STEXI 21855824d651Sblueswir1@end table 21865824d651Sblueswir1ETEXI 2187c70a01e4SMarkus ArmbrusterDEFHEADING() 21885824d651Sblueswir1 2189de6b4f90SMarkus ArmbrusterDEFHEADING(Network options:) 21905824d651Sblueswir1STEXI 21915824d651Sblueswir1@table @option 21925824d651Sblueswir1ETEXI 21935824d651Sblueswir1 21946a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 21955824d651Sblueswir1#ifdef CONFIG_SLIRP 21960b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 21970b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 21980b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 2199f18d1375SBenjamin Drung " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 22000fca92b9SFam Zheng " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 2201ad196a9dSJan Kiszka#ifndef _WIN32 2202c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 2203ad196a9dSJan Kiszka#endif 22046a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 22056a8b4a5bSThomas Huth " its DHCP server and optional services\n" 22065824d651Sblueswir1#endif 22075824d651Sblueswir1#ifdef _WIN32 22086a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 22096a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 22105824d651Sblueswir1#else 22116a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 2212584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 22136a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 221469e87b32SJason Wang " [,poll-us=n]\n" 22156a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 2216584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 2217a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 2218a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 2219a7c36ee4SCorey Bryant " to deconfigure it\n" 2220ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 2221a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 2222a7c36ee4SCorey Bryant " configure it\n" 22235824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 22242ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 2225ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 2226f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 2227ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 2228ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 222982b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 22305430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 22315430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 223282b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 22332ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 2234ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 223569e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 223669e87b32SJason Wang " spent on busy polling for vhost net\n" 22376a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 22386a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 22396a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 22406a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 22410df0ff6dSMark McLoughlin#endif 22423fb69aa1SAnton Ivanov#ifdef __linux__ 22436a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 22446a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 22456a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 22466a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 22476a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 22486a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 22493fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 22502f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 22513fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 22523fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 22533fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 22543fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 22553fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 22563fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 22573952651aSGonglei " use 'srcport=' to specify source udp port\n" 22583fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 22593fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 22603fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 22613fb69aa1SAnton Ivanov " well as a weak security measure\n" 22623fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 22633fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 22643fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 22653fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 22663fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 22673fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 22683fb69aa1SAnton Ivanov#endif 22696a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 22706a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 22716a8b4a5bSThomas Huth " using a socket connection\n" 22726a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 22736a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 22743a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 22756a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 22766a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 22776a8b4a5bSThomas Huth " using an UDP tunnel\n" 22785824d651Sblueswir1#ifdef CONFIG_VDE 22796a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 22806a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 22816a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 22825824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 22835824d651Sblueswir1 " ownership and permissions for communication port.\n" 22845824d651Sblueswir1#endif 228558952137SVincenzo Maffione#ifdef CONFIG_NETMAP 22866a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 228758952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 228858952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 228958952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 229058952137SVincenzo Maffione#endif 2291253dc14cSThomas Huth#ifdef CONFIG_POSIX 22926a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 22936a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 2294253dc14cSThomas Huth#endif 229518d65d22SThomas Huth "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 2296af1a5c3eSThomas Huth " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 229778cd6f7bSThomas HuthDEF("nic", HAS_ARG, QEMU_OPTION_nic, 2298dfaa7d50SBALATON Zoltan "-nic [tap|bridge|" 229978cd6f7bSThomas Huth#ifdef CONFIG_SLIRP 230078cd6f7bSThomas Huth "user|" 230178cd6f7bSThomas Huth#endif 230278cd6f7bSThomas Huth#ifdef __linux__ 230378cd6f7bSThomas Huth "l2tpv3|" 230478cd6f7bSThomas Huth#endif 230578cd6f7bSThomas Huth#ifdef CONFIG_VDE 230678cd6f7bSThomas Huth "vde|" 230778cd6f7bSThomas Huth#endif 230878cd6f7bSThomas Huth#ifdef CONFIG_NETMAP 230978cd6f7bSThomas Huth "netmap|" 231078cd6f7bSThomas Huth#endif 231178cd6f7bSThomas Huth#ifdef CONFIG_POSIX 231278cd6f7bSThomas Huth "vhost-user|" 231378cd6f7bSThomas Huth#endif 231478cd6f7bSThomas Huth "socket][,option][,...][mac=macaddr]\n" 231578cd6f7bSThomas Huth " initialize an on-board / default host NIC (using MAC address\n" 231678cd6f7bSThomas Huth " macaddr) and connect it to the given host network backend\n" 2317dfaa7d50SBALATON Zoltan "-nic none use it alone to have zero network devices (the default is to\n" 231878cd6f7bSThomas Huth " provided a 'user' network connection)\n", 231978cd6f7bSThomas Huth QEMU_ARCH_ALL) 23206a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 2321af1a5c3eSThomas Huth "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 23220e60a82dSThomas Huth " configure or create an on-board (or machine default) NIC and\n" 2323af1a5c3eSThomas Huth " connect it to hub 0 (please use -nic unless you need a hub)\n" 23246a8b4a5bSThomas Huth "-net [" 2325a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 2326a1ea458fSMark McLoughlin "user|" 2327a1ea458fSMark McLoughlin#endif 2328a1ea458fSMark McLoughlin "tap|" 2329a7c36ee4SCorey Bryant "bridge|" 2330a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 2331a1ea458fSMark McLoughlin "vde|" 2332a1ea458fSMark McLoughlin#endif 233358952137SVincenzo Maffione#ifdef CONFIG_NETMAP 233458952137SVincenzo Maffione "netmap|" 233558952137SVincenzo Maffione#endif 2336af1a5c3eSThomas Huth "socket][,option][,option][,...]\n" 23376a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 23386a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 23395824d651Sblueswir1STEXI 2340abbbb035SThomas Huth@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 2341abbbb035SThomas Huth@findex -nic 2342abbbb035SThomas HuthThis option is a shortcut for configuring both the on-board (default) guest 2343abbbb035SThomas HuthNIC hardware and the host network backend in one go. The host backend options 2344abbbb035SThomas Huthare the same as with the corresponding @option{-netdev} options below. 2345abbbb035SThomas HuthThe guest NIC model can be set with @option{model=@var{modelname}}. 2346abbbb035SThomas HuthUse @option{model=help} to list the available device types. 2347abbbb035SThomas HuthThe hardware MAC address can be set with @option{mac=@var{macaddr}}. 2348abbbb035SThomas Huth 2349abbbb035SThomas HuthThe following two example do exactly the same, to show how @option{-nic} can 2350abbbb035SThomas Huthbe used to shorten the command line length (note that the e1000 is the default 2351abbbb035SThomas Huthon i386, so the @option{model=e1000} parameter could even be omitted here, too): 2352abbbb035SThomas Huth@example 2353664785acSThomas Huth@value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 2354664785acSThomas Huth@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 2355abbbb035SThomas Huth@end example 2356abbbb035SThomas Huth 2357abbbb035SThomas Huth@item -nic none 2358abbbb035SThomas HuthIndicate that no network devices should be configured. It is used to override 2359abbbb035SThomas Huththe default configuration (default NIC with ``user'' host network backend) 2360abbbb035SThomas Huthwhich is activated if no other networking options are provided. 23615824d651Sblueswir1 236208d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 2363b8f490ebSMarkus Armbruster@findex -netdev 2364abbbb035SThomas HuthConfigure user mode host network backend which requires no administrator 2365ad196a9dSJan Kiszkaprivilege to run. Valid options are: 23665824d651Sblueswir1 2367b3f046c2SKevin Wolf@table @option 236808d12022SStefan Hajnoczi@item id=@var{id} 2369ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 2370ad196a9dSJan Kiszka 2371abbbb035SThomas Huth@item ipv4=on|off and ipv6=on|off 2372abbbb035SThomas HuthSpecify that either IPv4 or IPv6 must be enabled. If neither is specified 2373abbbb035SThomas Huthboth protocols are enabled. 23740b11c036SSamuel Thibault 2375c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 2376c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 2377c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 2378b0b36e5dSBrad Hards10.0.2.0/24. 2379c92ef6a2SJan Kiszka 2380c92ef6a2SJan Kiszka@item host=@var{addr} 2381c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 2382c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 2383ad196a9dSJan Kiszka 2384d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 2385d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 2386d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 2387d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 2388d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 23897aac531eSYann Bordenave 2390d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 23917aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 23927aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 23937aac531eSYann Bordenave 2394c54ed5bcSJan Kiszka@item restrict=on|off 2395caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 2396ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 2397caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 2398ad196a9dSJan Kiszka 2399ad196a9dSJan Kiszka@item hostname=@var{name} 240063d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 2401ad196a9dSJan Kiszka 2402c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 2403c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 2404b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2405c92ef6a2SJan Kiszka 2406c92ef6a2SJan Kiszka@item dns=@var{addr} 2407c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 2408c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 2409c92ef6a2SJan Kiszkai.e. x.x.x.3. 2410c92ef6a2SJan Kiszka 2411d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 24127aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 24137aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 24147aac531eSYann Bordenavenetwork, i.e. xxxx::3. 24157aac531eSYann Bordenave 241663d2960bSKlaus Stengel@item dnssearch=@var{domain} 241763d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 241863d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 241963d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 242063d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 242163d2960bSKlaus Stengelcan not be resolved. 242263d2960bSKlaus Stengel 242363d2960bSKlaus StengelExample: 242463d2960bSKlaus Stengel@example 2425664785acSThomas Huth@value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 242663d2960bSKlaus Stengel@end example 242763d2960bSKlaus Stengel 2428f18d1375SBenjamin Drung@item domainname=@var{domain} 2429f18d1375SBenjamin DrungSpecifies the client domain name reported by the built-in DHCP server. 2430f18d1375SBenjamin Drung 2431ad196a9dSJan Kiszka@item tftp=@var{dir} 2432ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 2433ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 2434ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 2435c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 2436ad196a9dSJan Kiszka 24370fca92b9SFam Zheng@item tftp-server-name=@var{name} 24380fca92b9SFam ZhengIn BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option 24390fca92b9SFam Zheng66). This can be used to advise the guest to load boot files or configurations 24400fca92b9SFam Zhengfrom a different server than the host address. 24410fca92b9SFam Zheng 2442ad196a9dSJan Kiszka@item bootfile=@var{file} 2443ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 2444ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 2445ad196a9dSJan Kiszkaa guest from a local directory. 2446ad196a9dSJan Kiszka 2447ad196a9dSJan KiszkaExample (using pxelinux): 2448ad196a9dSJan Kiszka@example 2449664785acSThomas Huth@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \ 2450abbbb035SThomas Huth -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2451ad196a9dSJan Kiszka@end example 2452ad196a9dSJan Kiszka 2453c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 2454ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 2455ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 2456c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 2457c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 2458ad196a9dSJan Kiszka 2459ad196a9dSJan KiszkaIn the guest Windows OS, the line: 2460ad196a9dSJan Kiszka@example 2461ad196a9dSJan Kiszka10.0.2.4 smbserver 2462ad196a9dSJan Kiszka@end example 2463ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2464ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2465ad196a9dSJan Kiszka 2466ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2467ad196a9dSJan Kiszka 2468e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 2469ad196a9dSJan Kiszka 24703c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2471c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 2472c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 2473c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 24743c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 24753c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 2476c92ef6a2SJan Kiszkaused. This option can be given multiple times. 2477ad196a9dSJan Kiszka 2478ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 2479ad196a9dSJan Kiszkascreen 0, use the following: 2480ad196a9dSJan Kiszka 2481ad196a9dSJan Kiszka@example 2482ad196a9dSJan Kiszka# on the host 2483664785acSThomas Huth@value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 2484ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 2485ad196a9dSJan Kiszkaxterm -display :1 2486ad196a9dSJan Kiszka@end example 2487ad196a9dSJan Kiszka 2488ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 2489ad196a9dSJan Kiszkathe guest, use the following: 2490ad196a9dSJan Kiszka 2491ad196a9dSJan Kiszka@example 2492ad196a9dSJan Kiszka# on the host 2493664785acSThomas Huth@value{qemu_system} -nic user,hostfwd=tcp::5555-:23 2494ad196a9dSJan Kiszkatelnet localhost 5555 2495ad196a9dSJan Kiszka@end example 2496ad196a9dSJan Kiszka 2497ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 2498ad196a9dSJan Kiszkaconnect to the guest telnet server. 2499ad196a9dSJan Kiszka 2500c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2501f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 25023c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 2503b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 2504b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 2505b412eb61SAlexander Graf 250643ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 2507b412eb61SAlexander Graflifetime, like in the following example: 2508b412eb61SAlexander Graf 2509b412eb61SAlexander Graf@example 2510b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2511b412eb61SAlexander Graf# the guest accesses it 2512664785acSThomas Huth@value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 2513b412eb61SAlexander Graf@end example 2514b412eb61SAlexander Graf 2515b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 251643ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 2517b412eb61SAlexander Graf 2518b412eb61SAlexander Graf@example 2519b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2520b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 2521664785acSThomas Huth@value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2522b412eb61SAlexander Graf@end example 2523ad196a9dSJan Kiszka 2524ad196a9dSJan Kiszka@end table 2525ad196a9dSJan Kiszka 2526584613eaSAlexey 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}] 2527abbbb035SThomas HuthConfigure a host TAP network backend with ID @var{id}. 2528a7c36ee4SCorey Bryant 2529a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 25305824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2531a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 2532a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 2533a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2534a7c36ee4SCorey Bryantto disable script execution. 2535a7c36ee4SCorey Bryant 2536a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 2537584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 2538584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 2539584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 2540a7c36ee4SCorey Bryant 2541a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 2542a7c36ee4SCorey Bryantopened host TAP interface. 2543a7c36ee4SCorey Bryant 2544a7c36ee4SCorey BryantExamples: 25455824d651Sblueswir1 25465824d651Sblueswir1@example 2547a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 2548664785acSThomas Huth@value{qemu_system} linux.img -nic tap 25495824d651Sblueswir1@end example 25505824d651Sblueswir1 25515824d651Sblueswir1@example 2552a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 2553a7c36ee4SCorey Bryant#to a TAP device 2554664785acSThomas Huth@value{qemu_system} linux.img \ 255574f78b99SThomas Huth -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 255674f78b99SThomas Huth -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 25575824d651Sblueswir1@end example 25585824d651Sblueswir1 2559a7c36ee4SCorey Bryant@example 2560a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2561a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2562664785acSThomas Huth@value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \ 2563abbbb035SThomas Huth -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 2564a7c36ee4SCorey Bryant@end example 2565a7c36ee4SCorey Bryant 256608d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2567a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 2568a7c36ee4SCorey Bryant 2569a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 2570a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 2571420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 2572a7c36ee4SCorey Bryantdevice is @file{br0}. 2573a7c36ee4SCorey Bryant 2574a7c36ee4SCorey BryantExamples: 2575a7c36ee4SCorey Bryant 2576a7c36ee4SCorey Bryant@example 2577a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2578a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2579664785acSThomas Huth@value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 2580a7c36ee4SCorey Bryant@end example 2581a7c36ee4SCorey Bryant 2582a7c36ee4SCorey Bryant@example 2583a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2584a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 2585664785acSThomas Huth@value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 2586a7c36ee4SCorey Bryant@end example 2587a7c36ee4SCorey Bryant 258808d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 25895824d651Sblueswir1 2590abbbb035SThomas HuthThis host network backend can be used to connect the guest's network to 2591abbbb035SThomas Huthanother QEMU virtual machine using a TCP socket connection. If @option{listen} 2592abbbb035SThomas Huthis specified, QEMU waits for incoming connections on @var{port} 25935824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 25945824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 25955824d651Sblueswir1specifies an already opened TCP socket. 25965824d651Sblueswir1 25975824d651Sblueswir1Example: 25985824d651Sblueswir1@example 25995824d651Sblueswir1# launch a first QEMU instance 2600664785acSThomas Huth@value{qemu_system} linux.img \ 2601abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2602abbbb035SThomas Huth -netdev socket,id=n1,listen=:1234 2603abbbb035SThomas Huth# connect the network of this instance to the network of the first instance 2604664785acSThomas Huth@value{qemu_system} linux.img \ 2605abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2606abbbb035SThomas Huth -netdev socket,id=n2,connect=127.0.0.1:1234 26075824d651Sblueswir1@end example 26085824d651Sblueswir1 260908d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 26105824d651Sblueswir1 2611abbbb035SThomas HuthConfigure a socket host network backend to share the guest's network traffic 2612abbbb035SThomas Huthwith another QEMU virtual machines using a UDP multicast socket, effectively 2613abbbb035SThomas Huthmaking a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 26145824d651Sblueswir1NOTES: 26155824d651Sblueswir1@enumerate 26165824d651Sblueswir1@item 26175824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 26185824d651Sblueswir1correct multicast setup for these hosts). 26195824d651Sblueswir1@item 26205824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 26215824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 26225824d651Sblueswir1@item 26235824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 26245824d651Sblueswir1@end enumerate 26255824d651Sblueswir1 26265824d651Sblueswir1Example: 26275824d651Sblueswir1@example 26285824d651Sblueswir1# launch one QEMU instance 2629664785acSThomas Huth@value{qemu_system} linux.img \ 2630abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2631abbbb035SThomas Huth -netdev socket,id=n1,mcast=230.0.0.1:1234 26325824d651Sblueswir1# launch another QEMU instance on same "bus" 2633664785acSThomas Huth@value{qemu_system} linux.img \ 2634abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2635abbbb035SThomas Huth -netdev socket,id=n2,mcast=230.0.0.1:1234 26365824d651Sblueswir1# launch yet another QEMU instance on same "bus" 2637664785acSThomas Huth@value{qemu_system} linux.img \ 263837a4442aSThomas Huth -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 2639abbbb035SThomas Huth -netdev socket,id=n3,mcast=230.0.0.1:1234 26405824d651Sblueswir1@end example 26415824d651Sblueswir1 26425824d651Sblueswir1Example (User Mode Linux compat.): 26435824d651Sblueswir1@example 2644abbbb035SThomas Huth# launch QEMU instance (note mcast address selected is UML's default) 2645664785acSThomas Huth@value{qemu_system} linux.img \ 2646abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2647abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102 26485824d651Sblueswir1# launch UML 26495824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 26505824d651Sblueswir1@end example 26515824d651Sblueswir1 26523a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 26533a75e74cSMike Ryan@example 2654664785acSThomas Huth@value{qemu_system} linux.img \ 2655abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2656abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 26573a75e74cSMike Ryan@end example 26583a75e74cSMike Ryan 26593fb69aa1SAnton 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}] 2660abbbb035SThomas HuthConfigure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a 2661abbbb035SThomas Huthpopular protocol to transport Ethernet (and other Layer 2) data frames between 26623fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 26633fb69aa1SAnton Ivanov(from version 3.3 onwards). 26643fb69aa1SAnton Ivanov 26653fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 26663fb69aa1SAnton Ivanov 26671e9a7379SMarkus Armbruster@table @option 26683fb69aa1SAnton Ivanov@item src=@var{srcaddr} 26693fb69aa1SAnton Ivanov source address (mandatory) 26703fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 26713fb69aa1SAnton Ivanov destination address (mandatory) 26723fb69aa1SAnton Ivanov@item udp 26733fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 26743fb69aa1SAnton Ivanov@item srcport=@var{srcport} 26753fb69aa1SAnton Ivanov source udp port. 26763fb69aa1SAnton Ivanov@item dstport=@var{dstport} 26773fb69aa1SAnton Ivanov destination udp port. 26783fb69aa1SAnton Ivanov@item ipv6 26793fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 26803fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2681f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 26823fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 26833fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 26843fb69aa1SAnton Ivanovbit. 26853fb69aa1SAnton Ivanov@item cookie64 26863fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 26873fb69aa1SAnton Ivanov@item counter=off 26883fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 26893fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 26903fb69aa1SAnton Ivanov@item pincounter=on 26913fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 26923fb69aa1SAnton Ivanovnetworks which have packet reorder. 26933fb69aa1SAnton Ivanov@item offset=@var{offset} 26943fb69aa1SAnton Ivanov Add an extra offset between header and data 26951e9a7379SMarkus Armbruster@end table 26963fb69aa1SAnton Ivanov 26973fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 26983fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 26993fb69aa1SAnton Ivanov@example 27003fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 27013fb69aa1SAnton Ivanov# on 1.2.3.4 27023fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 27033fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 27043fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 27053fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 27063fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 27073fb69aa1SAnton Ivanovifconfig vmtunnel0 up 27083fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 27093fb69aa1SAnton Ivanov 27103fb69aa1SAnton Ivanov 27113fb69aa1SAnton Ivanov# on 4.3.2.1 27123fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 27133fb69aa1SAnton Ivanov 2714664785acSThomas Huth@value{qemu_system} linux.img -device e1000,netdev=n1 \ 2715abbbb035SThomas 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 27163fb69aa1SAnton Ivanov 27173fb69aa1SAnton Ivanov@end example 27183fb69aa1SAnton Ivanov 271908d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2720abbbb035SThomas HuthConfigure VDE backend to connect to PORT @var{n} of a vde switch running on host and 27215824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 27225824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2723c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 27245824d651Sblueswir1with vde support enabled. 27255824d651Sblueswir1 27265824d651Sblueswir1Example: 27275824d651Sblueswir1@example 27285824d651Sblueswir1# launch vde switch 27295824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 27305824d651Sblueswir1# launch QEMU instance 2731664785acSThomas Huth@value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch 27325824d651Sblueswir1@end example 27335824d651Sblueswir1 2734b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 273503ce5744SNikolay Nikolaev 273603ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 273703ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 273803ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 273903ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2740b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2741b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 274203ce5744SNikolay Nikolaev 274303ce5744SNikolay NikolaevExample: 274403ce5744SNikolay Nikolaev@example 274503ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 274603ce5744SNikolay Nikolaev -numa node,memdev=mem \ 274779cad2faSVincenzo Maffione -chardev socket,id=chr0,path=/path/to/socket \ 274803ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 274903ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 275003ce5744SNikolay Nikolaev@end example 275103ce5744SNikolay Nikolaev 2752abbbb035SThomas Huth@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 275378cd6f7bSThomas Huth 2754abbbb035SThomas HuthCreate a hub port on the emulated hub with ID @var{hubid}. 275578cd6f7bSThomas Huth 2756abbbb035SThomas HuthThe hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 2757af1a5c3eSThomas Huthsingle netdev. Alternatively, you can also connect the hubport to another 2758af1a5c3eSThomas Huthnetdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 2759abbbb035SThomas Huth 2760af1a5c3eSThomas Huth@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 2761abbbb035SThomas Huth@findex -net 2762abbbb035SThomas HuthLegacy option to configure or create an on-board (or machine default) Network 2763af1a5c3eSThomas HuthInterface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 2764af1a5c3eSThomas Huththe default hub), or to the netdev @var{nd}. 2765abbbb035SThomas HuthThe NIC is an e1000 by default on the PC target. Optionally, the MAC address 2766abbbb035SThomas Huthcan be changed to @var{mac}, the device address set to @var{addr} (PCI cards 2767abbbb035SThomas Huthonly), and a @var{name} can be assigned for use in monitor commands. 2768abbbb035SThomas HuthOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2769abbbb035SThomas Huththat the card should have; this option currently only affects virtio cards; set 2770abbbb035SThomas Huth@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2771abbbb035SThomas HuthNIC is created. QEMU can emulate several different models of network card. 2772abbbb035SThomas HuthUse @code{-net nic,model=help} for a list of available devices for your target. 2773abbbb035SThomas Huth 2774af1a5c3eSThomas Huth@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 2775abbbb035SThomas HuthConfigure a host network backend (with the options corresponding to the same 2776af1a5c3eSThomas Huth@option{-netdev} option) and connect it to the emulated hub 0 (the default 2777af1a5c3eSThomas Huthhub). Use @var{name} to specify the name of the hub port. 27785824d651Sblueswir1ETEXI 27795824d651Sblueswir1 2780c70a01e4SMarkus ArmbrusterSTEXI 2781c70a01e4SMarkus Armbruster@end table 2782c70a01e4SMarkus ArmbrusterETEXI 27837273a2dbSMatthew BoothDEFHEADING() 27847273a2dbSMatthew Booth 2785de6b4f90SMarkus ArmbrusterDEFHEADING(Character device options:) 27867273a2dbSMatthew Booth 27877273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2788517b3d40SLin Ma "-chardev help\n" 2789d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 27905dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2791981b06e7SJulia Suvorova " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n" 2792fd4a5fd4SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n" 2793981b06e7SJulia Suvorova "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n" 2794d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 27957273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 279697331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2797d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2798d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 27997273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2800d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2801d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2802d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2803d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28047273a2dbSMatthew Booth#ifdef _WIN32 2805d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2806d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28077273a2dbSMatthew Booth#else 2808d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2809d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 28107273a2dbSMatthew Booth#endif 28117273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2812d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28137273a2dbSMatthew Booth#endif 28147273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 28157273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2816d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2817d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28187273a2dbSMatthew Booth#endif 28197273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2820d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2821d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28227273a2dbSMatthew Booth#endif 2823cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2824d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2825d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2826cbcc6336SAlon Levy#endif 2827ad96090aSBlue Swirl , QEMU_ARCH_ALL 28287273a2dbSMatthew Booth) 28297273a2dbSMatthew Booth 28307273a2dbSMatthew BoothSTEXI 2831dddba068SMarkus Armbruster 2832dddba068SMarkus ArmbrusterThe general form of a character device option is: 2833dddba068SMarkus Armbruster@table @option 283497331287SJan Kiszka@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 28356616b2adSStefan Weil@findex -chardev 28367273a2dbSMatthew BoothBackend is one of: 28377273a2dbSMatthew Booth@option{null}, 28387273a2dbSMatthew Booth@option{socket}, 28397273a2dbSMatthew Booth@option{udp}, 28407273a2dbSMatthew Booth@option{msmouse}, 28417273a2dbSMatthew Booth@option{vc}, 28424f57378fSMarkus Armbruster@option{ringbuf}, 28437273a2dbSMatthew Booth@option{file}, 28447273a2dbSMatthew Booth@option{pipe}, 28457273a2dbSMatthew Booth@option{console}, 28467273a2dbSMatthew Booth@option{serial}, 28477273a2dbSMatthew Booth@option{pty}, 28487273a2dbSMatthew Booth@option{stdio}, 28497273a2dbSMatthew Booth@option{braille}, 28507273a2dbSMatthew Booth@option{tty}, 285188a946d3SGerd Hoffmann@option{parallel}, 2852cbcc6336SAlon Levy@option{parport}, 285316fdc56aSThomas Huth@option{spicevmc}, 28545a49d3e9SMarc-André Lureau@option{spiceport}. 28557273a2dbSMatthew BoothThe specific backend will determine the applicable options. 28567273a2dbSMatthew Booth 2857dddba068SMarkus ArmbrusterUse @code{-chardev help} to print all available chardev backend types. 2858517b3d40SLin Ma 28597273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 28607273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 28617273a2dbSMatthew Booth 286297331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2863a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2864a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2865a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2866a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2867a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2868a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2869a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2870a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2871a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2872a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2873a40db1b3SPeter Maydell 2874a40db1b3SPeter Maydell@example 2875a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2876bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2877a40db1b3SPeter Maydell-serial chardev:char0 \ 2878a40db1b3SPeter Maydell-serial chardev:char0 2879a40db1b3SPeter Maydell@end example 2880a40db1b3SPeter Maydell 2881a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2882a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2883a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2884a40db1b3SPeter Maydell 2885a40db1b3SPeter Maydell@example 2886a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2887bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2888a40db1b3SPeter Maydell-parallel chardev:char0 \ 2889a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2890a40db1b3SPeter Maydell-serial chardev:char1 \ 2891a40db1b3SPeter Maydell-serial chardev:char1 2892a40db1b3SPeter Maydell@end example 2893a40db1b3SPeter Maydell 2894a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2895a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2896a40db1b3SPeter Maydellmultiplexer}. 2897a40db1b3SPeter Maydell 2898a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2899a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2900a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2901a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2902a40db1b3SPeter Maydellstdio. 2903a40db1b3SPeter Maydell 2904a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2905a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 290697331287SJan Kiszka 2907d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2908d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2909d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2910d0d7708bSDaniel P. Berrangeopened. 2911d0d7708bSDaniel P. Berrange 2912dddba068SMarkus Armbruster@end table 29137273a2dbSMatthew Booth 2914dddba068SMarkus ArmbrusterThe available backends are: 2915dddba068SMarkus Armbruster 2916dddba068SMarkus Armbruster@table @option 29177273a2dbSMatthew Booth@item -chardev null,id=@var{id} 29187273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 29197273a2dbSMatthew Boothreceives. The null backend does not take any options. 29207273a2dbSMatthew Booth 2921fd4a5fd4SDaniel 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}] 29227273a2dbSMatthew Booth 29237273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 29247273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 29257273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 29267273a2dbSMatthew Booth 29277273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 29287273a2dbSMatthew Booth 29297273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 29307273a2dbSMatthew Boothconnect to a listening socket. 29317273a2dbSMatthew Booth 29327273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 29337273a2dbSMatthew Boothescape sequences. 29347273a2dbSMatthew Booth 2935981b06e7SJulia Suvorova@option{websocket} specifies that the socket uses WebSocket protocol for 2936981b06e7SJulia Suvorovacommunication. 2937981b06e7SJulia Suvorova 29385dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 29395dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 29405dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 29415dd1f02bSCorey Minyard 2942a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2943a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2944a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2945a8fb5427SDaniel P. Berrangeargument. 2946a8fb5427SDaniel P. Berrange 2947fd4a5fd4SDaniel P. Berrange@option{tls-auth} provides the ID of the QAuthZ authorization object against 2948fd4a5fd4SDaniel P. Berrangewhich the client's x509 distinguished name will be validated. This object is 2949fd4a5fd4SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the fly 2950fd4a5fd4SDaniel P. Berrangewhile the chardev server is active. If missing, it will default to denying 2951fd4a5fd4SDaniel P. Berrangeaccess. 2952fd4a5fd4SDaniel P. Berrange 29537273a2dbSMatthew BoothTCP and unix socket options are given below: 29547273a2dbSMatthew Booth 29557273a2dbSMatthew Booth@table @option 29567273a2dbSMatthew Booth 29578d533561SAurelien Jarno@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 29587273a2dbSMatthew Booth 29597273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 29607273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 29617273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 29627273a2dbSMatthew Booth 29637273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 29647273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 29657273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 29667273a2dbSMatthew Booth@option{port} is required. 29677273a2dbSMatthew Booth 29687273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 29697273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 29707273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 29717273a2dbSMatthew Boothas a port number. 29727273a2dbSMatthew Booth 29737273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 29747273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 29757273a2dbSMatthew Booth 29767273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 29777273a2dbSMatthew Booth 29787273a2dbSMatthew Booth@item unix options: path=@var{path} 29797273a2dbSMatthew Booth 29807273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 29817273a2dbSMatthew Boothrequired. 29827273a2dbSMatthew Booth 29837273a2dbSMatthew Booth@end table 29847273a2dbSMatthew Booth 29857273a2dbSMatthew Booth@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 29867273a2dbSMatthew Booth 29877273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 29887273a2dbSMatthew Booth 29897273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 29907273a2dbSMatthew Boothdefaults to @code{localhost}. 29917273a2dbSMatthew Booth 29927273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 29937273a2dbSMatthew Boothis required. 29947273a2dbSMatthew Booth 29957273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 29967273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 29977273a2dbSMatthew Booth 29987273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 29997273a2dbSMatthew Boothavailable local port will be used. 30007273a2dbSMatthew Booth 30017273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 30027273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 30037273a2dbSMatthew Booth 30047273a2dbSMatthew Booth@item -chardev msmouse,id=@var{id} 30057273a2dbSMatthew Booth 30067273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 30077273a2dbSMatthew Boothtake any options. 30087273a2dbSMatthew Booth 30097273a2dbSMatthew Booth@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 30107273a2dbSMatthew Booth 30117273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 30127273a2dbSMatthew Boothsize. 30137273a2dbSMatthew Booth 30147273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 30157273a2dbSMatthew Booththe console, in pixels. 30167273a2dbSMatthew Booth 30177273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 30187273a2dbSMatthew Boothconsole with the given dimensions. 30197273a2dbSMatthew Booth 30204f57378fSMarkus Armbruster@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 302151767e7cSLei Li 30223949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 3023e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 302451767e7cSLei Li 30257273a2dbSMatthew Booth@item -chardev file,id=@var{id},path=@var{path} 30267273a2dbSMatthew Booth 30277273a2dbSMatthew BoothLog all traffic received from the guest to a file. 30287273a2dbSMatthew Booth 30297273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 30307273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 30317273a2dbSMatthew Boothis required. 30327273a2dbSMatthew Booth 30337273a2dbSMatthew Booth@item -chardev pipe,id=@var{id},path=@var{path} 30347273a2dbSMatthew Booth 30357273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 30367273a2dbSMatthew BoothWindows hosts and other hosts: 30377273a2dbSMatthew Booth 30387273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 30397273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 30407273a2dbSMatthew Booth 30417273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 30427273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 30437273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 30447273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 30457273a2dbSMatthew Boothbe present. 30467273a2dbSMatthew Booth 30477273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 30487273a2dbSMatthew Boothrequired. 30497273a2dbSMatthew Booth 30507273a2dbSMatthew Booth@item -chardev console,id=@var{id} 30517273a2dbSMatthew Booth 30527273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 30537273a2dbSMatthew Boothtake any options. 30547273a2dbSMatthew Booth 30557273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 30567273a2dbSMatthew Booth 30577273a2dbSMatthew Booth@item -chardev serial,id=@var{id},path=@option{path} 30587273a2dbSMatthew Booth 30597273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 30607273a2dbSMatthew Booth 3061d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 3062d59044efSGerd Hoffmannnot only serial lines. 30637273a2dbSMatthew Booth 30647273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 30657273a2dbSMatthew Booth 30667273a2dbSMatthew Booth@item -chardev pty,id=@var{id} 30677273a2dbSMatthew Booth 30687273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 30697273a2dbSMatthew Boothnot take any options. 30707273a2dbSMatthew Booth 30717273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 30727273a2dbSMatthew Booth 3073b7fdb3abSAurelien Jarno@item -chardev stdio,id=@var{id}[,signal=on|off] 3074b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 3075b7fdb3abSAurelien Jarno 3076b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 3077b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 3078b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 3079b7fdb3abSAurelien Jarno 30807273a2dbSMatthew Booth@item -chardev braille,id=@var{id} 30817273a2dbSMatthew Booth 30827273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 30837273a2dbSMatthew Booth 30847273a2dbSMatthew Booth@item -chardev tty,id=@var{id},path=@var{path} 30857273a2dbSMatthew Booth 30867273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 3087d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 30887273a2dbSMatthew Booth 30897273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 30907273a2dbSMatthew Booth 309188a946d3SGerd Hoffmann@item -chardev parallel,id=@var{id},path=@var{path} 3092f9cfd655SMarkus Armbruster@itemx -chardev parport,id=@var{id},path=@var{path} 30937273a2dbSMatthew Booth 309488a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 30957273a2dbSMatthew Booth 30967273a2dbSMatthew BoothConnect to a local parallel port. 30977273a2dbSMatthew Booth 30987273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 30997273a2dbSMatthew Boothrequired. 31007273a2dbSMatthew Booth 3101cbcc6336SAlon Levy@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 3102cbcc6336SAlon Levy 31033a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 31043a846906SStefan Hajnoczi 3105cbcc6336SAlon Levy@option{debug} debug level for spicevmc 3106cbcc6336SAlon Levy 3107cbcc6336SAlon Levy@option{name} name of spice channel to connect to 3108cbcc6336SAlon Levy 3109cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 3110cbcc6336SAlon Levy 31115a49d3e9SMarc-André Lureau@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 31125a49d3e9SMarc-André Lureau 31135a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 31145a49d3e9SMarc-André Lureau 31155a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 31165a49d3e9SMarc-André Lureau 31175a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 31185a49d3e9SMarc-André Lureau 31195a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 31205a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 31217273a2dbSMatthew BoothETEXI 31227273a2dbSMatthew Booth 3123c70a01e4SMarkus ArmbrusterSTEXI 3124c70a01e4SMarkus Armbruster@end table 3125c70a01e4SMarkus ArmbrusterETEXI 31267273a2dbSMatthew BoothDEFHEADING() 31277273a2dbSMatthew Booth 3128de6b4f90SMarkus ArmbrusterDEFHEADING(Bluetooth(R) options:) 3129c70a01e4SMarkus ArmbrusterSTEXI 3130c70a01e4SMarkus Armbruster@table @option 3131c70a01e4SMarkus ArmbrusterETEXI 31327273a2dbSMatthew Booth 31335824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 31345824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 31355824d651Sblueswir1 "-bt hci,host[:id]\n" \ 31365824d651Sblueswir1 " use host's HCI with the given name\n" \ 31375824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 31385824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 31395824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 31405824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 31415824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 3142ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 3143ad96090aSBlue Swirl QEMU_ARCH_ALL) 31445824d651Sblueswir1STEXI 31455824d651Sblueswir1@item -bt hci[...] 31466616b2adSStefan Weil@findex -bt 31475824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 31485824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 31495824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 31505824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 31515824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 31525824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 31535824d651Sblueswir1machines have none. 31545824d651Sblueswir1 3155c0188e69SThomas HuthNote: This option and the whole bluetooth subsystem is considered as deprecated. 3156c0188e69SThomas HuthIf you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where 3157c0188e69SThomas Huthyou describe your usecase. 3158c0188e69SThomas Huth 31595824d651Sblueswir1@anchor{bt-hcis} 31605824d651Sblueswir1The following three types are recognized: 31615824d651Sblueswir1 3162b3f046c2SKevin Wolf@table @option 31635824d651Sblueswir1@item -bt hci,null 31645824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 31655824d651Sblueswir1and will not respond to any HCI commands or emit events. 31665824d651Sblueswir1 31675824d651Sblueswir1@item -bt hci,host[:@var{id}] 31685824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 31695824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 31705824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 31715824d651Sblueswir1capable systems like Linux. 31725824d651Sblueswir1 31735824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 31745824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 31755824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 31765824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 31775824d651Sblueswir1with other devices in the same network (scatternet). 31785824d651Sblueswir1@end table 31795824d651Sblueswir1 31805824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 31815824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 31825824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 31835824d651Sblueswir1allows the host and target machines to participate in a common scatternet 31845824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 31855824d651Sblueswir1be used as following: 31865824d651Sblueswir1 31875824d651Sblueswir1@example 3188664785acSThomas Huth@value{qemu_system} [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 31895824d651Sblueswir1@end example 31905824d651Sblueswir1 31915824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 31925824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 31935824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 31945824d651Sblueswir1currently: 31955824d651Sblueswir1 3196b3f046c2SKevin Wolf@table @option 31975824d651Sblueswir1@item keyboard 31985824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 31995824d651Sblueswir1@end table 32005824d651Sblueswir1ETEXI 32015824d651Sblueswir1 3202c70a01e4SMarkus ArmbrusterSTEXI 3203c70a01e4SMarkus Armbruster@end table 3204c70a01e4SMarkus ArmbrusterETEXI 32055824d651Sblueswir1DEFHEADING() 32065824d651Sblueswir1 3207d1a0cf73SStefan Berger#ifdef CONFIG_TPM 3208de6b4f90SMarkus ArmbrusterDEFHEADING(TPM device options:) 3209d1a0cf73SStefan Berger 3210d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 321192dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 321292dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 321392dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 3214f4ede81eSAmarnath Valluri " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 3215f4ede81eSAmarnath Valluri "-tpmdev emulator,id=id,chardev=dev\n" 3216f4ede81eSAmarnath Valluri " configure the TPM device using chardev backend\n", 3217d1a0cf73SStefan Berger QEMU_ARCH_ALL) 3218d1a0cf73SStefan BergerSTEXI 3219d1a0cf73SStefan Berger 3220d1a0cf73SStefan BergerThe general form of a TPM device option is: 3221d1a0cf73SStefan Berger@table @option 3222d1a0cf73SStefan Berger 3223d1a0cf73SStefan Berger@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 3224d1a0cf73SStefan Berger@findex -tpmdev 3225d1a0cf73SStefan Berger 3226d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 322728c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 322828c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 3229d1a0cf73SStefan Berger 32302252aaf0SMarkus ArmbrusterUse @code{-tpmdev help} to print all available TPM backend types. 3231d1a0cf73SStefan Berger 32322252aaf0SMarkus Armbruster@end table 32332252aaf0SMarkus Armbruster 32342252aaf0SMarkus ArmbrusterThe available backends are: 32352252aaf0SMarkus Armbruster 32362252aaf0SMarkus Armbruster@table @option 3237d1a0cf73SStefan Berger 323892dcc234SStefan Berger@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 32394549a8b7SStefan Berger 32404549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 32414549a8b7SStefan Bergerdriver. 32424549a8b7SStefan Berger 32434549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 32444549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 32454549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 32464549a8b7SStefan Berger 324792dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 324892dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 324992dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 325092dcc234SStefan Bergersysfs entry to use. 325192dcc234SStefan Berger 32524549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 32534549a8b7SStefan Berger 32544549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 32554549a8b7SStefan Bergerused by any other application on the host. 32564549a8b7SStefan Berger 32574549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 32584549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 32594549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 32604549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 32614549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 32624549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 32634549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 32644549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 32654549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 32664549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 32674549a8b7SStefan Berger 32684549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 32694549a8b7SStefan Berger@example 32704549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 32714549a8b7SStefan Berger@end example 32724549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 32734549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 32744549a8b7SStefan Berger 3275f4ede81eSAmarnath Valluri@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 3276f4ede81eSAmarnath Valluri 3277f4ede81eSAmarnath Valluri(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 3278f4ede81eSAmarnath Vallurichardev backend. 3279f4ede81eSAmarnath Valluri 3280f4ede81eSAmarnath Valluri@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 3281f4ede81eSAmarnath Valluri 3282f4ede81eSAmarnath ValluriTo create a TPM emulator backend device with chardev socket backend: 3283f4ede81eSAmarnath Valluri@example 3284f4ede81eSAmarnath Valluri 3285f4ede81eSAmarnath Valluri-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 3286f4ede81eSAmarnath Valluri 3287f4ede81eSAmarnath Valluri@end example 3288f4ede81eSAmarnath Valluri 3289d1a0cf73SStefan BergerETEXI 3290d1a0cf73SStefan Berger 32912252aaf0SMarkus ArmbrusterSTEXI 32922252aaf0SMarkus Armbruster@end table 32932252aaf0SMarkus ArmbrusterETEXI 3294d1a0cf73SStefan BergerDEFHEADING() 3295d1a0cf73SStefan Berger 3296d1a0cf73SStefan Berger#endif 3297d1a0cf73SStefan Berger 3298de6b4f90SMarkus ArmbrusterDEFHEADING(Linux/Multiboot boot specific:) 32995824d651Sblueswir1STEXI 33007677f05dSAlexander Graf 33017677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 33027677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 33035824d651Sblueswir1for easier testing of various kernels. 33045824d651Sblueswir1 33055824d651Sblueswir1@table @option 33065824d651Sblueswir1ETEXI 33075824d651Sblueswir1 33085824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 3309ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 33105824d651Sblueswir1STEXI 33115824d651Sblueswir1@item -kernel @var{bzImage} 33126616b2adSStefan Weil@findex -kernel 33137677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 33147677f05dSAlexander Grafor in multiboot format. 33155824d651Sblueswir1ETEXI 33165824d651Sblueswir1 33175824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 3318ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 33195824d651Sblueswir1STEXI 33205824d651Sblueswir1@item -append @var{cmdline} 33216616b2adSStefan Weil@findex -append 33225824d651Sblueswir1Use @var{cmdline} as kernel command line 33235824d651Sblueswir1ETEXI 33245824d651Sblueswir1 33255824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 3326ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 33275824d651Sblueswir1STEXI 33285824d651Sblueswir1@item -initrd @var{file} 33296616b2adSStefan Weil@findex -initrd 33305824d651Sblueswir1Use @var{file} as initial ram disk. 33317677f05dSAlexander Graf 33327677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 33337677f05dSAlexander Graf 33347677f05dSAlexander GrafThis syntax is only available with multiboot. 33357677f05dSAlexander Graf 33367677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 33377677f05dSAlexander Graffirst module. 33385824d651Sblueswir1ETEXI 33395824d651Sblueswir1 3340412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 3341379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 3342412beee6SGrant LikelySTEXI 3343412beee6SGrant Likely@item -dtb @var{file} 3344412beee6SGrant Likely@findex -dtb 3345412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 3346412beee6SGrant Likelyon boot. 3347412beee6SGrant LikelyETEXI 3348412beee6SGrant Likely 33495824d651Sblueswir1STEXI 33505824d651Sblueswir1@end table 33515824d651Sblueswir1ETEXI 33525824d651Sblueswir1DEFHEADING() 33535824d651Sblueswir1 3354de6b4f90SMarkus ArmbrusterDEFHEADING(Debug/Expert options:) 33555824d651Sblueswir1STEXI 33565824d651Sblueswir1@table @option 33575824d651Sblueswir1ETEXI 33585824d651Sblueswir1 335981b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 336081b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 336163d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 33626407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 336363d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 336481b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 336581b2b810SGabriel L. SomloSTEXI 336663d3145aSMarkus Armbruster 336781b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 336881b2b810SGabriel L. Somlo@findex -fw_cfg 336963d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 33706407d76eSGabriel L. Somlo 33716407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 337263d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 337363d3145aSMarkus Armbruster 337463d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 337563d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 337663d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 337763d3145aSMarkus Armbruster 337863d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 337963d3145aSMarkus Armbruster 338063d3145aSMarkus ArmbrusterExample: 338163d3145aSMarkus Armbruster@example 338263d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 338363d3145aSMarkus Armbruster@end example 338463d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 338563d3145aSMarkus Armbrusterfrom ./my_blob.bin. 338663d3145aSMarkus Armbruster 338781b2b810SGabriel L. SomloETEXI 338881b2b810SGabriel L. Somlo 33895824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3390ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 3391ad96090aSBlue Swirl QEMU_ARCH_ALL) 33925824d651Sblueswir1STEXI 33935824d651Sblueswir1@item -serial @var{dev} 33946616b2adSStefan Weil@findex -serial 33955824d651Sblueswir1Redirect the virtual serial port to host character device 33965824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 33975824d651Sblueswir1@code{stdio} in non graphical mode. 33985824d651Sblueswir1 33995824d651Sblueswir1This option can be used several times to simulate up to 4 serial 34005824d651Sblueswir1ports. 34015824d651Sblueswir1 34025824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 34035824d651Sblueswir1 34045824d651Sblueswir1Available character devices are: 3405b3f046c2SKevin Wolf@table @option 34064e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 34075824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 34085824d651Sblueswir1@example 34095824d651Sblueswir1vc:800x600 34105824d651Sblueswir1@end example 34115824d651Sblueswir1It is also possible to specify width or height in characters: 34125824d651Sblueswir1@example 34135824d651Sblueswir1vc:80Cx24C 34145824d651Sblueswir1@end example 34155824d651Sblueswir1@item pty 34165824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 34175824d651Sblueswir1@item none 34185824d651Sblueswir1No device is allocated. 34195824d651Sblueswir1@item null 34205824d651Sblueswir1void device 342188e020e5SIngo van Lil@item chardev:@var{id} 342288e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 34235824d651Sblueswir1@item /dev/XXX 34245824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 34255824d651Sblueswir1parameters are set according to the emulated ones. 34265824d651Sblueswir1@item /dev/parport@var{N} 34275824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 34285824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 34295824d651Sblueswir1@item file:@var{filename} 34305824d651Sblueswir1Write output to @var{filename}. No character can be read. 34315824d651Sblueswir1@item stdio 34325824d651Sblueswir1[Unix only] standard input/output 34335824d651Sblueswir1@item pipe:@var{filename} 34345824d651Sblueswir1name pipe @var{filename} 34355824d651Sblueswir1@item COM@var{n} 34365824d651Sblueswir1[Windows only] Use host serial port @var{n} 34375824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 34385824d651Sblueswir1This implements UDP Net Console. 34395824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 34405824d651Sblueswir1they default to @code{0.0.0.0}. 34415824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 34425824d651Sblueswir1 34435824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3444b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3445b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 34465824d651Sblueswir1will appear in the netconsole session. 34475824d651Sblueswir1 34485824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3449b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 34505824d651Sblueswir1source port each time by using something like @code{-serial 3451b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 34525824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 34535824d651Sblueswir1characters via udp. If you have a patched version of netcat which 34545824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3455bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3456b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 34575824d651Sblueswir1@table @code 3458071c9394SStefan Weil@item QEMU Options: 34595824d651Sblueswir1-serial udp::4555@@:4556 34605824d651Sblueswir1@item netcat options: 34615824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 34625824d651Sblueswir1@item telnet options: 34635824d651Sblueswir1localhost 5555 34645824d651Sblueswir1@end table 34655824d651Sblueswir1 34665dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 34675824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 34685824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 34695824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 34705824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 34715824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 34725824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 34735dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 34745dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 34755dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 34765824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 34775824d651Sblueswir1connect to the corresponding character device. 34785824d651Sblueswir1@table @code 34795824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 34805824d651Sblueswir1-serial tcp:192.168.0.2:4444 34815824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 34825824d651Sblueswir1-serial tcp::4444,server 34835824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 34845824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 34855824d651Sblueswir1@end table 34865824d651Sblueswir1 34875824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 34885824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 34895824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 34905824d651Sblueswir1difference is that the port acts like a telnet server or client using 34915824d651Sblueswir1telnet option negotiation. This will also allow you to send the 34925824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 34935824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 34945824d651Sblueswir1type "send break" followed by pressing the enter key. 34955824d651Sblueswir1 3496981b06e7SJulia Suvorova@item websocket:@var{host}:@var{port},server[,nowait][,nodelay] 3497981b06e7SJulia SuvorovaThe WebSocket protocol is used instead of raw tcp socket. The port acts as 3498981b06e7SJulia Suvorovaa WebSocket server. Client mode is not supported. 3499981b06e7SJulia Suvorova 35005dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 35015824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 35025824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 35035824d651Sblueswir1@var{path} is used for connections. 35045824d651Sblueswir1 35055824d651Sblueswir1@item mon:@var{dev_string} 35065824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 35075824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 350802c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 35095824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 35105824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 35115824d651Sblueswir1listening on port 4444 would be: 35125824d651Sblueswir1@table @code 35135824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 35145824d651Sblueswir1@end table 3515be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 351602c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 35175824d651Sblueswir1 35185824d651Sblueswir1@item braille 35195824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 35205824d651Sblueswir1or fake device. 35215824d651Sblueswir1 3522be8b28a9SKevin Wolf@item msmouse 3523be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 35245824d651Sblueswir1@end table 35255824d651Sblueswir1ETEXI 35265824d651Sblueswir1 35275824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3528ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3529ad96090aSBlue Swirl QEMU_ARCH_ALL) 35305824d651Sblueswir1STEXI 35315824d651Sblueswir1@item -parallel @var{dev} 35326616b2adSStefan Weil@findex -parallel 35335824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 35345824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 35355824d651Sblueswir1be used to use hardware devices connected on the corresponding host 35365824d651Sblueswir1parallel port. 35375824d651Sblueswir1 35385824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 35395824d651Sblueswir1ports. 35405824d651Sblueswir1 35415824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 35425824d651Sblueswir1ETEXI 35435824d651Sblueswir1 35445824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3545ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3546ad96090aSBlue Swirl QEMU_ARCH_ALL) 35475824d651Sblueswir1STEXI 35484e307fc8SGerd Hoffmann@item -monitor @var{dev} 35496616b2adSStefan Weil@findex -monitor 35505824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 35515824d651Sblueswir1serial port). 35525824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 35535824d651Sblueswir1non graphical mode. 355470e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 35555824d651Sblueswir1ETEXI 35566ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3557ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3558ad96090aSBlue Swirl QEMU_ARCH_ALL) 355995d5f08bSStefan WeilSTEXI 356095d5f08bSStefan Weil@item -qmp @var{dev} 35616616b2adSStefan Weil@findex -qmp 356295d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 356395d5f08bSStefan WeilETEXI 35644821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 35654821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 35664821cd4cSMax Reitz QEMU_ARCH_ALL) 35674821cd4cSMax ReitzSTEXI 35684821cd4cSMax Reitz@item -qmp-pretty @var{dev} 35694821cd4cSMax Reitz@findex -qmp-pretty 35704821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 35714821cd4cSMax ReitzETEXI 35725824d651Sblueswir1 357322a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3574ef670726SVicente Jimenez Aguilar "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 357522a0e04bSGerd HoffmannSTEXI 3576ef670726SVicente Jimenez Aguilar@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 35776616b2adSStefan Weil@findex -mon 3578ef670726SVicente Jimenez AguilarSetup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 3579ef670726SVicente Jimenez Aguilareasing human reading and debugging. 358022a0e04bSGerd HoffmannETEXI 358122a0e04bSGerd Hoffmann 3582c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3583ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3584ad96090aSBlue Swirl QEMU_ARCH_ALL) 3585c9f398e5SH. Peter AnvinSTEXI 3586c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 35876616b2adSStefan Weil@findex -debugcon 3588c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3589c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3590c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3591c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3592c9f398e5SH. Peter Anvinnon graphical mode. 3593c9f398e5SH. Peter AnvinETEXI 3594c9f398e5SH. Peter Anvin 35955824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3596ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 35975824d651Sblueswir1STEXI 35985824d651Sblueswir1@item -pidfile @var{file} 35996616b2adSStefan Weil@findex -pidfile 36005824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 36015824d651Sblueswir1from a script. 36025824d651Sblueswir1ETEXI 36035824d651Sblueswir1 36041b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3605ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 36061b530a6dSaurel32STEXI 36071b530a6dSaurel32@item -singlestep 36086616b2adSStefan Weil@findex -singlestep 36091b530a6dSaurel32Run the emulation in single step mode. 36101b530a6dSaurel32ETEXI 36111b530a6dSaurel32 3612047f7038SIgor MammedovDEF("preconfig", 0, QEMU_OPTION_preconfig, \ 3613361ac948SMarkus Armbruster "--preconfig pause QEMU before machine is initialized (experimental)\n", 3614047f7038SIgor Mammedov QEMU_ARCH_ALL) 3615047f7038SIgor MammedovSTEXI 3616047f7038SIgor Mammedov@item --preconfig 3617047f7038SIgor Mammedov@findex --preconfig 3618047f7038SIgor MammedovPause QEMU for interactive configuration before the machine is created, 3619047f7038SIgor Mammedovwhich allows querying and configuring properties that will affect 3620361ac948SMarkus Armbrustermachine initialization. Use QMP command 'x-exit-preconfig' to exit 3621361ac948SMarkus Armbrusterthe preconfig state and move to the next state (i.e. run guest if -S 3622361ac948SMarkus Armbrusterisn't used or pause the second time if -S is used). This option is 3623361ac948SMarkus Armbrusterexperimental. 3624047f7038SIgor MammedovETEXI 3625047f7038SIgor Mammedov 36265824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3627ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3628ad96090aSBlue Swirl QEMU_ARCH_ALL) 36295824d651Sblueswir1STEXI 36305824d651Sblueswir1@item -S 36316616b2adSStefan Weil@findex -S 36325824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 36335824d651Sblueswir1ETEXI 36345824d651Sblueswir1 3635888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3636888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3637888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3638888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3639888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3640888a6bc6SSatoru MoriyaSTEXI 3641888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3642888a6bc6SSatoru Moriya@findex -realtime 3643888a6bc6SSatoru MoriyaRun qemu with realtime features. 3644888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3645888a6bc6SSatoru Moriya(enabled by default). 3646888a6bc6SSatoru MoriyaETEXI 3647888a6bc6SSatoru Moriya 36486f131f13SMichael S. TsirkinDEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, 3649dfaa7d50SBALATON Zoltan "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" 36506f131f13SMichael S. Tsirkin " run qemu with overcommit hints\n" 36516f131f13SMichael S. Tsirkin " mem-lock=on|off controls memory lock support (default: off)\n" 36526f131f13SMichael S. Tsirkin " cpu-pm=on|off controls cpu power management (default: off)\n", 36536f131f13SMichael S. Tsirkin QEMU_ARCH_ALL) 36546f131f13SMichael S. TsirkinSTEXI 36556f131f13SMichael S. Tsirkin@item -overcommit mem-lock=on|off 36566f131f13SMichael S. Tsirkin@item -overcommit cpu-pm=on|off 36576f131f13SMichael S. Tsirkin@findex -overcommit 36586f131f13SMichael S. TsirkinRun qemu with hints about host resource overcommit. The default is 36596f131f13SMichael S. Tsirkinto assume that host overcommits all resources. 36606f131f13SMichael S. Tsirkin 36616f131f13SMichael S. TsirkinLocking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled 36626f131f13SMichael S. Tsirkinby default). This works when host memory is not overcommitted and reduces the 36636f131f13SMichael S. Tsirkinworst-case latency for guest. This is equivalent to @option{realtime}. 36646f131f13SMichael S. Tsirkin 36656f131f13SMichael S. TsirkinGuest ability to manage power state of host cpus (increasing latency for other 36666f131f13SMichael S. Tsirkinprocesses on the same host cpu, but decreasing latency for guest) can be 36676f131f13SMichael S. Tsirkinenabled via @option{cpu-pm=on} (disabled by default). This works best when 36686f131f13SMichael S. Tsirkinhost CPU is not overcommitted. When used, host estimates of CPU cycle and power 36696f131f13SMichael S. Tsirkinutilization will be incorrect, not taking into account guest idle time. 36706f131f13SMichael S. TsirkinETEXI 36716f131f13SMichael S. Tsirkin 367259030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3673ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 36745824d651Sblueswir1STEXI 367559030a8cSaliguori@item -gdb @var{dev} 36766616b2adSStefan Weil@findex -gdb 367759030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 367859030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3679b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 368059030a8cSaliguoriwithin gdb and establish the connection via a pipe: 368159030a8cSaliguori@example 3682664785acSThomas Huth(gdb) target remote | exec @value{qemu_system} -gdb stdio ... 368359030a8cSaliguori@end example 36845824d651Sblueswir1ETEXI 36855824d651Sblueswir1 368659030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3687ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3688ad96090aSBlue Swirl QEMU_ARCH_ALL) 36895824d651Sblueswir1STEXI 369059030a8cSaliguori@item -s 36916616b2adSStefan Weil@findex -s 369259030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 369359030a8cSaliguori(@pxref{gdb_usage}). 36945824d651Sblueswir1ETEXI 36955824d651Sblueswir1 36965824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3697989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3698ad96090aSBlue Swirl QEMU_ARCH_ALL) 36995824d651Sblueswir1STEXI 3700989b697dSPeter Maydell@item -d @var{item1}[,...] 37016616b2adSStefan Weil@findex -d 3702989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 37035824d651Sblueswir1ETEXI 37045824d651Sblueswir1 3705c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3706989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3707c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3708c235d738SMatthew FernandezSTEXI 37098bd383b4SStefan Weil@item -D @var{logfile} 3710c235d738SMatthew Fernandez@findex -D 3711989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3712c235d738SMatthew FernandezETEXI 3713c235d738SMatthew Fernandez 37143514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 37153514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 37163514552eSAlex Bennée QEMU_ARCH_ALL) 37173514552eSAlex BennéeSTEXI 37183514552eSAlex Bennée@item -dfilter @var{range1}[,...] 37193514552eSAlex Bennée@findex -dfilter 37203514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 37213514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 37223514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 37233514552eSAlex Bennéeaddresses and sizes required. For example: 37243514552eSAlex Bennée@example 37253514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 37263514552eSAlex Bennée@end example 37273514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 37283514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 37293514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 37303514552eSAlex BennéeETEXI 37313514552eSAlex Bennée 37329c09a251SRichard HendersonDEF("seed", HAS_ARG, QEMU_OPTION_seed, \ 37339c09a251SRichard Henderson "-seed number seed the pseudo-random number generator\n", 37349c09a251SRichard Henderson QEMU_ARCH_ALL) 37359c09a251SRichard HendersonSTEXI 37369c09a251SRichard Henderson@item -seed @var{number} 37379c09a251SRichard Henderson@findex -seed 37389c09a251SRichard HendersonForce the guest to use a deterministic pseudo-random number generator, seeded 37399c09a251SRichard Hendersonwith @var{number}. This does not affect crypto routines within the host. 37409c09a251SRichard HendersonETEXI 37419c09a251SRichard Henderson 37425824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3743ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3744ad96090aSBlue Swirl QEMU_ARCH_ALL) 37455824d651Sblueswir1STEXI 37465824d651Sblueswir1@item -L @var{path} 37476616b2adSStefan Weil@findex -L 37485824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 374937146e7eSRichard W.M. Jones 375037146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 37515824d651Sblueswir1ETEXI 37525824d651Sblueswir1 37535824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3754ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 37555824d651Sblueswir1STEXI 37565824d651Sblueswir1@item -bios @var{file} 37576616b2adSStefan Weil@findex -bios 37585824d651Sblueswir1Set the filename for the BIOS. 37595824d651Sblueswir1ETEXI 37605824d651Sblueswir1 37615824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3762ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 37635824d651Sblueswir1STEXI 37645824d651Sblueswir1@item -enable-kvm 37656616b2adSStefan Weil@findex -enable-kvm 37665824d651Sblueswir1Enable KVM full virtualization support. This option is only available 37675824d651Sblueswir1if KVM support is enabled when compiling. 37685824d651Sblueswir1ETEXI 37695824d651Sblueswir1 3770e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3771ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3772e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3773e37630caSaliguori "-xen-attach attach to existing xen domain\n" 37741077bcacSAnthony PERARD " libxl will use this when starting QEMU\n", 3775ad96090aSBlue Swirl QEMU_ARCH_ALL) 37761c599472SPaul DurrantDEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 37771c599472SPaul Durrant "-xen-domid-restrict restrict set of available xen operations\n" 37781c599472SPaul Durrant " to specified domain id. (Does not affect\n" 37791c599472SPaul Durrant " xenpv machine type).\n", 37801c599472SPaul Durrant QEMU_ARCH_ALL) 378195d5f08bSStefan WeilSTEXI 378295d5f08bSStefan Weil@item -xen-domid @var{id} 37836616b2adSStefan Weil@findex -xen-domid 378495d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 378595d5f08bSStefan Weil@item -xen-attach 37866616b2adSStefan Weil@findex -xen-attach 378795d5f08bSStefan WeilAttach to existing xen domain. 37881077bcacSAnthony PERARDlibxl will use this when starting QEMU (XEN only). 37891c599472SPaul Durrant@findex -xen-domid-restrict 37901c599472SPaul DurrantRestrict set of available xen operations to specified domain id (XEN only). 379195d5f08bSStefan WeilETEXI 3792e37630caSaliguori 37935824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3794ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 37955824d651Sblueswir1STEXI 37965824d651Sblueswir1@item -no-reboot 37976616b2adSStefan Weil@findex -no-reboot 37985824d651Sblueswir1Exit instead of rebooting. 37995824d651Sblueswir1ETEXI 38005824d651Sblueswir1 38015824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3802ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 38035824d651Sblueswir1STEXI 38045824d651Sblueswir1@item -no-shutdown 38056616b2adSStefan Weil@findex -no-shutdown 38065824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 38075824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 38085824d651Sblueswir1disk image. 38095824d651Sblueswir1ETEXI 38105824d651Sblueswir1 38115824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 38125824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3813ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3814ad96090aSBlue Swirl QEMU_ARCH_ALL) 38155824d651Sblueswir1STEXI 38165824d651Sblueswir1@item -loadvm @var{file} 38176616b2adSStefan Weil@findex -loadvm 38185824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 38195824d651Sblueswir1ETEXI 38205824d651Sblueswir1 38215824d651Sblueswir1#ifndef _WIN32 38225824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3823ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 38245824d651Sblueswir1#endif 38255824d651Sblueswir1STEXI 38265824d651Sblueswir1@item -daemonize 38276616b2adSStefan Weil@findex -daemonize 38285824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 38295824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 38305824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 38315824d651Sblueswir1to cope with initialization race conditions. 38325824d651Sblueswir1ETEXI 38335824d651Sblueswir1 38345824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3835ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3836ad96090aSBlue Swirl QEMU_ARCH_ALL) 38375824d651Sblueswir1STEXI 38385824d651Sblueswir1@item -option-rom @var{file} 38396616b2adSStefan Weil@findex -option-rom 38405824d651Sblueswir1Load the contents of @var{file} as an option ROM. 38415824d651Sblueswir1This option is useful to load things like EtherBoot. 38425824d651Sblueswir1ETEXI 38435824d651Sblueswir1 38441ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 3845238d1240SArtem Pisarenko "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3846ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3847ad96090aSBlue Swirl QEMU_ARCH_ALL) 38481ed2fc1fSJan Kiszka 38495824d651Sblueswir1STEXI 38505824d651Sblueswir1 3851238d1240SArtem Pisarenko@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew] 38526616b2adSStefan Weil@findex -rtc 38531ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 38541ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 3855238d1240SArtem PisarenkoMS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the 38561ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 38571ed2fc1fSJan Kiszka 38589d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 38596875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 38606875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 386178808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 3862238d1240SArtem Pisarenkoto @code{rt} instead, which provides a host monotonic clock if host support it. 3863238d1240SArtem PisarenkoTo even prevent the RTC from progressing during suspension, you can set @option{clock} 3864238d1240SArtem Pisarenkoto @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in 3865238d1240SArtem Pisarenkoicount mode in order to preserve determinism; however, note that in icount mode 3866238d1240SArtem Pisarenkothe speed of the virtual clock is variable and can in general differ from the 3867238d1240SArtem Pisarenkohost clock. 38686875204cSJan Kiszka 38691ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 38701ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 38711ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 38721ed2fc1fSJan Kiszkare-inject them. 38735824d651Sblueswir1ETEXI 38745824d651Sblueswir1 38755824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 38769c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3877bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3878f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3879f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 38805824d651Sblueswir1STEXI 38819c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 38826616b2adSStefan Weil@findex -icount 38835824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 38844e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 38855824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 38865824d651Sblueswir1time within a few seconds of real time. 38875824d651Sblueswir1 3888f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3889778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3890778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3891f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3892f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3893f1f4b57eSVictor CLEMENTthe guest point of view. 3894f1f4b57eSVictor CLEMENT 38955824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 38965824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 38975824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 38985824d651Sblueswir1executed often has little or no correlation with actual performance. 3899a8bfac37SSebastian Tanase 3900b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3901a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3902a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3903a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 390482597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3905a8bfac37SSebastian Tanaseto inform about the delay. 3906a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3907a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3908a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3909a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 39104c27b859SPavel Dovgalyuk 39114c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 39124c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 39134c27b859SPavel Dovgalyukread from this file in replay mode. 39149c2037d0SPavel Dovgalyuk 39159c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 39169c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 39179c2037d0SPavel Dovgalyukto load the initial VM state. 39185824d651Sblueswir1ETEXI 39195824d651Sblueswir1 39209dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3921d7933ef3SXu Wang "-watchdog model\n" \ 3922ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3923ad96090aSBlue Swirl QEMU_ARCH_ALL) 39249dd986ccSRichard W.M. JonesSTEXI 39259dd986ccSRichard W.M. Jones@item -watchdog @var{model} 39266616b2adSStefan Weil@findex -watchdog 39279dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 39289dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3929d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3930d7933ef3SXu Wangwhich your guest has drivers. 39319dd986ccSRichard W.M. Jones 3932d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3933d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 39349dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3935d7933ef3SXu Wang 3936d7933ef3SXu WangThe following models may be available: 3937d7933ef3SXu Wang@table @option 3938d7933ef3SXu Wang@item ib700 3939d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3940d7933ef3SXu Wang@item i6300esb 3941d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3942d7933ef3SXu Wangdual-timer watchdog. 3943188f24c2SXu Wang@item diag288 3944188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3945188f24c2SXu Wang(currently KVM only). 3946d7933ef3SXu Wang@end table 39479dd986ccSRichard W.M. JonesETEXI 39489dd986ccSRichard W.M. Jones 39499dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 39507ad9270eSMarkus Armbruster "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 3951ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3952ad96090aSBlue Swirl QEMU_ARCH_ALL) 39539dd986ccSRichard W.M. JonesSTEXI 39549dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3955b8f490ebSMarkus Armbruster@findex -watchdog-action 39569dd986ccSRichard W.M. Jones 39579dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 39589dd986ccSRichard W.M. Jonesexpires. 39599dd986ccSRichard W.M. JonesThe default is 39609dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 39619dd986ccSRichard W.M. JonesOther possible actions are: 39629dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 39639dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 39647ad9270eSMarkus Armbruster@code{inject-nmi} (inject a NMI into the guest), 39659dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 39669dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 39679dd986ccSRichard W.M. Jones@code{none} (do nothing). 39689dd986ccSRichard W.M. Jones 39699dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 39709dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 39719dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 39729dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 39739dd986ccSRichard W.M. Jones 39749dd986ccSRichard W.M. JonesExamples: 39759dd986ccSRichard W.M. Jones 39769dd986ccSRichard W.M. Jones@table @code 39779dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3978f9cfd655SMarkus Armbruster@itemx -watchdog ib700 39799dd986ccSRichard W.M. Jones@end table 39809dd986ccSRichard W.M. JonesETEXI 39819dd986ccSRichard W.M. Jones 39825824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3983ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3984ad96090aSBlue Swirl QEMU_ARCH_ALL) 39855824d651Sblueswir1STEXI 39865824d651Sblueswir1 39874e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 39886616b2adSStefan Weil@findex -echr 39895824d651Sblueswir1Change the escape character used for switching to the monitor when using 39905824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 39915824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 39925824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 39935824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 39945824d651Sblueswir1instance you could use the either of the following to change the escape 39955824d651Sblueswir1character to Control-t. 39965824d651Sblueswir1@table @code 39975824d651Sblueswir1@item -echr 0x14 3998f9cfd655SMarkus Armbruster@itemx -echr 20 39995824d651Sblueswir1@end table 40005824d651Sblueswir1ETEXI 40015824d651Sblueswir1 40025824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 4003ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 40045824d651Sblueswir1STEXI 400595d5f08bSStefan Weil@item -show-cursor 40066616b2adSStefan Weil@findex -show-cursor 400795d5f08bSStefan WeilShow cursor. 40085824d651Sblueswir1ETEXI 40095824d651Sblueswir1 40105824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 4011ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 40125824d651Sblueswir1STEXI 401395d5f08bSStefan Weil@item -tb-size @var{n} 40146616b2adSStefan Weil@findex -tb-size 401595d5f08bSStefan WeilSet TB size. 40165824d651Sblueswir1ETEXI 40175824d651Sblueswir1 40185824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 40197c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 40207c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 40217c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 40227c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 40237c601803SMichael Tokarev " specified protocol and socket address\n" \ 40247c601803SMichael Tokarev "-incoming fd:fd\n" \ 40257c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 40267c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 40271597051bSDr. David Alan Gilbert " or from given external command\n" \ 40281597051bSDr. David Alan Gilbert "-incoming defer\n" \ 40291597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 4030ad96090aSBlue Swirl QEMU_ARCH_ALL) 40315824d651Sblueswir1STEXI 40327c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 4033f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 40346616b2adSStefan Weil@findex -incoming 40357c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 40367c601803SMichael Tokarev 40377c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 40387c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 40397c601803SMichael Tokarev 40407c601803SMichael Tokarev@item -incoming fd:@var{fd} 40417c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 40427c601803SMichael Tokarev 40437c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 40447c601803SMichael TokarevAccept incoming migration as an output from specified external command. 40451597051bSDr. David Alan Gilbert 40461597051bSDr. David Alan Gilbert@item -incoming defer 40471597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 40481597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 40491597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 40505824d651Sblueswir1ETEXI 40515824d651Sblueswir1 4052d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 4053d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 4054d15c05fcSAshijeet AcharyaSTEXI 4055d15c05fcSAshijeet Acharya@item -only-migratable 4056d15c05fcSAshijeet Acharya@findex -only-migratable 4057d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 4058d15c05fcSAshijeet Acharyaunmigratable state. 4059d15c05fcSAshijeet AcharyaETEXI 4060d15c05fcSAshijeet Acharya 4061d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 4062ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 4063d8c208ddSGerd HoffmannSTEXI 40643dbf2c7fSStefan Weil@item -nodefaults 40656616b2adSStefan Weil@findex -nodefaults 406666c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 406766c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 406866c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 406966c19bf1SMichal Novotnydefault devices. 4070d8c208ddSGerd HoffmannETEXI 4071d8c208ddSGerd Hoffmann 40725824d651Sblueswir1#ifndef _WIN32 40735824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 4074ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 4075ad96090aSBlue Swirl QEMU_ARCH_ALL) 40765824d651Sblueswir1#endif 40775824d651Sblueswir1STEXI 40784e257e5eSKevin Wolf@item -chroot @var{dir} 40796616b2adSStefan Weil@findex -chroot 40805824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 40815824d651Sblueswir1directory. Especially useful in combination with -runas. 40825824d651Sblueswir1ETEXI 40835824d651Sblueswir1 40845824d651Sblueswir1#ifndef _WIN32 40855824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 40862c42f1e8SIan Jackson "-runas user change to user id user just before starting the VM\n" \ 40872c42f1e8SIan Jackson " user can be numeric uid:gid instead\n", 4088ad96090aSBlue Swirl QEMU_ARCH_ALL) 40895824d651Sblueswir1#endif 40905824d651Sblueswir1STEXI 40914e257e5eSKevin Wolf@item -runas @var{user} 40926616b2adSStefan Weil@findex -runas 40935824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 40945824d651Sblueswir1to the specified user. 40955824d651Sblueswir1ETEXI 40965824d651Sblueswir1 40975824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 40985824d651Sblueswir1 "-prom-env variable=value\n" 4099ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 4100ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 410195d5f08bSStefan WeilSTEXI 410295d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 41036616b2adSStefan Weil@findex -prom-env 410495d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 410595d5f08bSStefan WeilETEXI 41065824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 4107f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 41083b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 4109413a99a9SSandra Loosemore QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 411095d5f08bSStefan WeilSTEXI 411195d5f08bSStefan Weil@item -semihosting 41126616b2adSStefan Weil@findex -semihosting 4113413a99a9SSandra LoosemoreEnable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only). 4114a38bb079SLiviu IonescuETEXI 4115a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 41164e7f9032SAlex Bennée "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \ 4117a59d31a1SLeon Alrae " semihosting configuration\n", 41183b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 4119413a99a9SSandra LoosemoreQEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 4120a38bb079SLiviu IonescuSTEXI 41214e7f9032SAlex Bennée@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]] 4122a38bb079SLiviu Ionescu@findex -semihosting-config 4123413a99a9SSandra LoosemoreEnable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only). 4124a59d31a1SLeon Alrae@table @option 4125a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 4126a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 4127a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 4128a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 41294e7f9032SAlex Bennée@item chardev=@var{str1} 41304e7f9032SAlex BennéeSend the output to a chardev backend output for native or auto output when not in gdb 4131a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 4132a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 4133a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 4134a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 4135a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 4136a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 4137a59d31a1SLeon Alrae@end table 413895d5f08bSStefan WeilETEXI 41395824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 4140ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 414195d5f08bSStefan WeilSTEXI 414295d5f08bSStefan Weil@item -old-param 41436616b2adSStefan Weil@findex -old-param (ARM) 414495d5f08bSStefan WeilOld param mode (ARM only). 414595d5f08bSStefan WeilETEXI 414695d5f08bSStefan Weil 41477d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 414873a1e647SEduardo Otubo "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 414924f8cdc5SEduardo Otubo " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 41502b716fa6SEduardo Otubo " Enable seccomp mode 2 system call filter (default 'off').\n" \ 41512b716fa6SEduardo Otubo " use 'obsolete' to allow obsolete system calls that are provided\n" \ 41522b716fa6SEduardo Otubo " by the kernel, but typically no longer used by modern\n" \ 415373a1e647SEduardo Otubo " C library implementations.\n" \ 415473a1e647SEduardo Otubo " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 415573a1e647SEduardo Otubo " its privileges by blacklisting all set*uid|gid system calls.\n" \ 415673a1e647SEduardo Otubo " The value 'children' will deny set*uid|gid system calls for\n" \ 4157995a226fSEduardo Otubo " main QEMU process but will allow forks and execves to run unprivileged\n" \ 4158995a226fSEduardo Otubo " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 415924f8cdc5SEduardo Otubo " blacklisting *fork and execve\n" \ 416024f8cdc5SEduardo Otubo " use 'resourcecontrol' to disable process affinity and schedular priority\n", 41617d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 41627d76ad4fSEduardo OtuboSTEXI 416324f8cdc5SEduardo Otubo@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 41647d76ad4fSEduardo Otubo@findex -sandbox 41657d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 41667d76ad4fSEduardo Otubodisable it. The default is 'off'. 41672b716fa6SEduardo Otubo@table @option 41682b716fa6SEduardo Otubo@item obsolete=@var{string} 41692b716fa6SEduardo OtuboEnable Obsolete system calls 417073a1e647SEduardo Otubo@item elevateprivileges=@var{string} 417173a1e647SEduardo OtuboDisable set*uid|gid system calls 4172995a226fSEduardo Otubo@item spawn=@var{string} 4173995a226fSEduardo OtuboDisable *fork and execve 417424f8cdc5SEduardo Otubo@item resourcecontrol=@var{string} 417524f8cdc5SEduardo OtuboDisable process affinity and schedular priority 41762b716fa6SEduardo Otubo@end table 41777d76ad4fSEduardo OtuboETEXI 41787d76ad4fSEduardo Otubo 4179715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 4180ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 41813dbf2c7fSStefan WeilSTEXI 41823dbf2c7fSStefan Weil@item -readconfig @var{file} 41836616b2adSStefan Weil@findex -readconfig 4184ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 4185ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 4186ed24cfacSMichal Novotnycharacter limit. 41873dbf2c7fSStefan WeilETEXI 4188715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 4189715a664aSGerd Hoffmann "-writeconfig <file>\n" 4190ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 41913dbf2c7fSStefan WeilSTEXI 41923dbf2c7fSStefan Weil@item -writeconfig @var{file} 41936616b2adSStefan Weil@findex -writeconfig 4194ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 4195ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 4196ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 41973dbf2c7fSStefan WeilETEXI 41982feac451SThomas Huth 4199f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 4200f29a5614SEduardo Habkost "-no-user-config\n" 42013478eae9SEduardo Habkost " do not load default user-provided config files at startup\n", 4202f29a5614SEduardo Habkost QEMU_ARCH_ALL) 4203f29a5614SEduardo HabkostSTEXI 4204f29a5614SEduardo Habkost@item -no-user-config 4205f29a5614SEduardo Habkost@findex -no-user-config 4206f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 42073478eae9SEduardo Habkostconfig files on @var{sysconfdir}. 4208292444cbSAnthony LiguoriETEXI 42092feac451SThomas Huth 4210ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 421110578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 421223d15e86SLluís " specify tracing options\n", 4213ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 4214ab6540d5SPrerna SaxenaSTEXI 421523d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 421623d15e86SLluísHXCOMM HX does not support conditional compilation of text. 4217e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 4218ab6540d5SPrerna Saxena@findex -trace 4219eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 4220ab6540d5SPrerna SaxenaETEXI 422142229a75SLluís VilanovaDEF("plugin", HAS_ARG, QEMU_OPTION_plugin, 422242229a75SLluís Vilanova "-plugin [file=]<file>[,arg=<string>]\n" 422342229a75SLluís Vilanova " load a plugin\n", 422442229a75SLluís Vilanova QEMU_ARCH_ALL) 422542229a75SLluís VilanovaSTEXI 422642229a75SLluís Vilanova@item -plugin file=@var{file}[,arg=@var{string}] 422742229a75SLluís Vilanova@findex -plugin 422842229a75SLluís Vilanova 422942229a75SLluís VilanovaLoad a plugin. 423042229a75SLluís Vilanova 423142229a75SLluís Vilanova@table @option 423242229a75SLluís Vilanova@item file=@var{file} 423342229a75SLluís VilanovaLoad the given plugin from a shared library file. 423442229a75SLluís Vilanova@item arg=@var{string} 423542229a75SLluís VilanovaArgument string passed to the plugin. (Can be given multiple times.) 423642229a75SLluís Vilanova@end table 423742229a75SLluís VilanovaETEXI 42383dbf2c7fSStefan Weil 423931e70d6cSMarkus ArmbrusterHXCOMM Internal use 424031e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 424131e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 4242c7f0f3b1SAnthony Liguori 42430f66998fSPaul Moore#ifdef __linux__ 42440f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 42450f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 42460f66998fSPaul Moore QEMU_ARCH_ALL) 42470f66998fSPaul Moore#endif 42480f66998fSPaul MooreSTEXI 42490f66998fSPaul Moore@item -enable-fips 42500f66998fSPaul Moore@findex -enable-fips 42510f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 42520f66998fSPaul MooreETEXI 42530f66998fSPaul Moore 4254976e8c54SThomas HuthHXCOMM Deprecated by -accel tcg 4255c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 4256a0dac021SJan Kiszka 42575e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 42585e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 42595e2ac519SSeiji Aguchi " change the format of messages\n" 42605e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 42615e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 42625e2ac519SSeiji AguchiSTEXI 42635e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 42645e2ac519SSeiji Aguchi@findex -msg 42655e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 42665e2ac519SSeiji AguchiETEXI 42675e2ac519SSeiji Aguchi 4268abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 4269abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 4270abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 4271abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 4272abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 42732382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 4274abfd9ce3SAmit Shah QEMU_ARCH_ALL) 4275abfd9ce3SAmit ShahSTEXI 4276abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 4277abfd9ce3SAmit Shah@findex -dump-vmstate 4278abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 4279abfd9ce3SAmit Shahin @var{file} 4280abfd9ce3SAmit ShahETEXI 4281abfd9ce3SAmit Shah 428212df189dSEmilio G. CotaDEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, 428312df189dSEmilio G. Cota "-enable-sync-profile\n" 428412df189dSEmilio G. Cota " enable synchronization profiling\n", 428512df189dSEmilio G. Cota QEMU_ARCH_ALL) 428612df189dSEmilio G. CotaSTEXI 428712df189dSEmilio G. Cota@item -enable-sync-profile 428812df189dSEmilio G. Cota@findex -enable-sync-profile 428912df189dSEmilio G. CotaEnable synchronization profiling. 429012df189dSEmilio G. CotaETEXI 429112df189dSEmilio G. Cota 429243f187a5SPaolo BonziniSTEXI 429343f187a5SPaolo Bonzini@end table 429443f187a5SPaolo BonziniETEXI 429543f187a5SPaolo BonziniDEFHEADING() 4296de6b4f90SMarkus Armbruster 4297de6b4f90SMarkus ArmbrusterDEFHEADING(Generic object creation:) 429843f187a5SPaolo BonziniSTEXI 429943f187a5SPaolo Bonzini@table @option 430043f187a5SPaolo BonziniETEXI 4301b9174d4fSDaniel P. Berrange 4302b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 4303b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 4304b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 4305b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 4306b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 4307b9174d4fSDaniel P. Berrange " '/objects' path.\n", 4308b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 4309b9174d4fSDaniel P. BerrangeSTEXI 4310b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 4311b9174d4fSDaniel P. Berrange@findex -object 4312b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 4313b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 4314b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 4315b9174d4fSDaniel P. Berrange'/objects' path. 4316b9174d4fSDaniel P. Berrange 4317b9174d4fSDaniel P. Berrange@table @option 4318b9174d4fSDaniel P. Berrange 431998376843SHaozhong 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} 4320b9174d4fSDaniel P. Berrange 4321b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 4322c7cddce1SStefan Hajnoczithe guest RAM with huge pages. 4323c7cddce1SStefan Hajnoczi 4324c7cddce1SStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 4325c7cddce1SStefan Hajnoczimemory region when configuring the @option{-numa} argument. 4326c7cddce1SStefan Hajnoczi 4327c7cddce1SStefan HajnocziThe @option{size} option provides the size of the memory region, and accepts 4328c7cddce1SStefan Hajnoczicommon suffixes, eg @option{500M}. 4329c7cddce1SStefan Hajnoczi 4330c7cddce1SStefan HajnocziThe @option{mem-path} provides the path to either a shared memory or huge page 4331c7cddce1SStefan Hajnoczifilesystem mount. 4332c7cddce1SStefan Hajnoczi 4333b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 4334b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 4335b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 4336c7cddce1SStefan Hajnoczi 433706329cceSMarcel ApfelbaumThe @option{share} is also required for pvrdma devices due to 433806329cceSMarcel Apfelbaumlimitations in the RDMA API provided by Linux. 433906329cceSMarcel Apfelbaum 434006329cceSMarcel ApfelbaumSetting share=on might affect the ability to configure NUMA 434106329cceSMarcel Apfelbaumbindings for the memory backend under some circumstances, see 434206329cceSMarcel ApfelbaumDocumentation/vm/numa_memory_policy.txt on the Linux kernel 434306329cceSMarcel Apfelbaumsource tree for additional details. 434406329cceSMarcel Apfelbaum 434511ae6ed8SEduardo HabkostSetting the @option{discard-data} boolean option to @var{on} 434611ae6ed8SEduardo Habkostindicates that file contents can be destroyed when QEMU exits, 434711ae6ed8SEduardo Habkostto avoid unnecessarily flushing data to the backing file. Note 434811ae6ed8SEduardo Habkostthat @option{discard-data} is only an optimization, and QEMU 434911ae6ed8SEduardo Habkostmight not discard file contents if it aborts unexpectedly or is 435011ae6ed8SEduardo Habkostterminated using SIGKILL. 4351b9174d4fSDaniel P. Berrange 4352c7cddce1SStefan HajnocziThe @option{merge} boolean option enables memory merge, also known as 4353c7cddce1SStefan HajnocziMADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 4354c7cddce1SStefan Hajnoczimemory deduplication. 4355c7cddce1SStefan Hajnoczi 4356c7cddce1SStefan HajnocziSetting the @option{dump} boolean option to @var{off} excludes the memory from 4357c7cddce1SStefan Hajnoczicore dumps. This feature is also known as MADV_DONTDUMP. 4358c7cddce1SStefan Hajnoczi 4359c7cddce1SStefan HajnocziThe @option{prealloc} boolean option enables memory preallocation. 4360c7cddce1SStefan Hajnoczi 4361c7cddce1SStefan HajnocziThe @option{host-nodes} option binds the memory range to a list of NUMA host 4362c7cddce1SStefan Hajnoczinodes. 4363c7cddce1SStefan Hajnoczi 4364c7cddce1SStefan HajnocziThe @option{policy} option sets the NUMA policy to one of the following values: 4365c7cddce1SStefan Hajnoczi 4366c7cddce1SStefan Hajnoczi@table @option 4367c7cddce1SStefan Hajnoczi@item @var{default} 4368c7cddce1SStefan Hajnoczidefault host policy 4369c7cddce1SStefan Hajnoczi 4370c7cddce1SStefan Hajnoczi@item @var{preferred} 4371c7cddce1SStefan Hajnocziprefer the given host node list for allocation 4372c7cddce1SStefan Hajnoczi 4373c7cddce1SStefan Hajnoczi@item @var{bind} 4374c7cddce1SStefan Hajnoczirestrict memory allocation to the given host node list 4375c7cddce1SStefan Hajnoczi 4376c7cddce1SStefan Hajnoczi@item @var{interleave} 4377c7cddce1SStefan Hajnocziinterleave memory allocations across the given host node list 4378c7cddce1SStefan Hajnoczi@end table 4379c7cddce1SStefan Hajnoczi 438098376843SHaozhong ZhangThe @option{align} option specifies the base address alignment when 438198376843SHaozhong ZhangQEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 438298376843SHaozhong Zhang@option{2M}. Some backend store specified by @option{mem-path} 438398376843SHaozhong Zhangrequires an alignment different than the default one used by QEMU, eg 438498376843SHaozhong Zhangthe device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 438598376843SHaozhong Zhangsuch cases, users can specify the required alignment via this option. 438698376843SHaozhong Zhang 4387a4de8552SJunyan HeThe @option{pmem} option specifies whether the backing file specified 4388a4de8552SJunyan Heby @option{mem-path} is in host persistent memory that can be accessed 4389a4de8552SJunyan Heusing the SNIA NVM programming model (e.g. Intel NVDIMM). 4390a4de8552SJunyan HeIf @option{pmem} is set to 'on', QEMU will take necessary operations to 4391a4de8552SJunyan Heguarantee the persistence of its own writes to @option{mem-path} 4392a4de8552SJunyan He(e.g. in vNVDIMM label emulation and live migration). 4393119906afSZhang YiAlso, we will map the backend-file with MAP_SYNC flag, which ensures the 4394119906afSZhang Yifile metadata is in sync for @option{mem-path} in case of host crash 4395119906afSZhang Yior a power failure. MAP_SYNC requires support from both the host kernel 4396119906afSZhang Yi(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted 4397119906afSZhang Yiwith DAX option. 4398a4de8552SJunyan He 439906329cceSMarcel 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} 4400cd19491aSStefan Hajnoczi 4401cd19491aSStefan HajnocziCreates a memory backend object, which can be used to back the guest RAM. 4402cd19491aSStefan HajnocziMemory backend objects offer more control than the @option{-m} option that is 4403cd19491aSStefan Hajnoczitraditionally used to define guest RAM. Please refer to 4404cd19491aSStefan Hajnoczi@option{memory-backend-file} for a description of the options. 4405cd19491aSStefan Hajnoczi 440636ea3979SMarc-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} 4407dbb9e0f4SMarc-André Lureau 4408dbb9e0f4SMarc-André LureauCreates an anonymous memory file backend object, which allows QEMU to 4409dbb9e0f4SMarc-André Lureaushare the memory with an external process (e.g. when using 4410dbb9e0f4SMarc-André Lureauvhost-user). The memory is allocated with memfd and optional 4411dbb9e0f4SMarc-André Lureausealing. (Linux only) 4412dbb9e0f4SMarc-André Lureau 4413dbb9e0f4SMarc-André LureauThe @option{seal} option creates a sealed-file, that will block 4414dbb9e0f4SMarc-André Lureaufurther resizing the memory ('on' by default). 4415dbb9e0f4SMarc-André Lureau 4416dbb9e0f4SMarc-André LureauThe @option{hugetlb} option specify the file to be created resides in 4417dbb9e0f4SMarc-André Lureauthe hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 4418dbb9e0f4SMarc-André Lureauthe @option{hugetlb} option, the @option{hugetlbsize} option specify 4419dbb9e0f4SMarc-André Lureauthe hugetlb page size on systems that support multiple hugetlb page 4420dbb9e0f4SMarc-André Lureausizes (it must be a power of 2 value supported by the system). 4421dbb9e0f4SMarc-André Lureau 4422dbb9e0f4SMarc-André LureauIn some versions of Linux, the @option{hugetlb} option is incompatible 4423dbb9e0f4SMarc-André Lureauwith the @option{seal} option (requires at least Linux 4.16). 4424dbb9e0f4SMarc-André Lureau 4425dbb9e0f4SMarc-André LureauPlease refer to @option{memory-backend-file} for a description of the 4426dbb9e0f4SMarc-André Lureauother options. 4427dbb9e0f4SMarc-André Lureau 442836ea3979SMarc-André LureauThe @option{share} boolean option is @var{on} by default with memfd. 442936ea3979SMarc-André Lureau 44306c4e9d48SLaurent Vivier@item -object rng-builtin,id=@var{id} 44316c4e9d48SLaurent Vivier 44326c4e9d48SLaurent VivierCreates a random number generator backend which obtains entropy from 44336c4e9d48SLaurent VivierQEMU builtin functions. The @option{id} parameter is a unique ID that 44346c4e9d48SLaurent Vivierwill be used to reference this entropy backend from the @option{virtio-rng} 44350198c262SLaurent Vivierdevice. By default, the @option{virtio-rng} device uses this RNG backend. 44366c4e9d48SLaurent Vivier 4437b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4438b9174d4fSDaniel P. Berrange 4439b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4440b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 4441b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 4442b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 4443a2230bd7SKashyap Chamarthyentropy from and if omitted defaults to @option{/dev/urandom}. 4444b9174d4fSDaniel P. Berrange 4445b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4446b9174d4fSDaniel P. Berrange 4447b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4448b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 4449b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 4450b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 4451b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 4452b9174d4fSDaniel P. Berrangeto the RNG daemon. 4453b9174d4fSDaniel P. Berrange 4454e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4455e00adf6cSDaniel P. Berrange 4456e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 4457e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 4458e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 4459e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 4460e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 4461e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 4462e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 4463e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 4464e00adf6cSDaniel P. Berrange 4465e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 4466e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 4467e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 4468e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 4469e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 4470e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 4471e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 4472e00adf6cSDaniel P. Berrangeupfront and saved. 4473e00adf6cSDaniel P. Berrange 4474e1a6dc91SRichard W.M. Jones@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}] 4475e1a6dc91SRichard W.M. Jones 4476e1a6dc91SRichard W.M. JonesCreates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide 4477e1a6dc91SRichard W.M. JonesTLS support on network backends. The @option{id} parameter is a unique 4478e1a6dc91SRichard W.M. JonesID which network backends will use to access the credentials. The 4479e1a6dc91SRichard W.M. Jones@option{endpoint} is either @option{server} or @option{client} depending 4480e1a6dc91SRichard W.M. Joneson whether the QEMU network backend that uses the credentials will be 4481e1a6dc91SRichard W.M. Jonesacting as a client or as a server. For clients only, @option{username} 4482e1a6dc91SRichard W.M. Jonesis the username which will be sent to the server. If omitted 4483e1a6dc91SRichard W.M. Jonesit defaults to ``qemu''. 4484e1a6dc91SRichard W.M. Jones 4485e1a6dc91SRichard W.M. JonesThe @var{dir} parameter tells QEMU where to find the keys file. 4486e1a6dc91SRichard W.M. JonesIt is called ``@var{dir}/keys.psk'' and contains ``username:key'' 4487e1a6dc91SRichard W.M. Jonespairs. This file can most easily be created using the GnuTLS 4488e1a6dc91SRichard W.M. Jones@code{psktool} program. 4489e1a6dc91SRichard W.M. Jones 4490e1a6dc91SRichard W.M. JonesFor server endpoints, @var{dir} may also contain a file 4491e1a6dc91SRichard W.M. Jones@var{dh-params.pem} providing diffie-hellman parameters to use 4492e1a6dc91SRichard W.M. Jonesfor the TLS server. If the file is missing, QEMU will generate 4493e1a6dc91SRichard W.M. Jonesa set of DH parameters at startup. This is a computationally 4494e1a6dc91SRichard W.M. Jonesexpensive operation that consumes random pool entropy, so it is 4495e1a6dc91SRichard W.M. Jonesrecommended that a persistent set of parameters be generated 4496e1a6dc91SRichard W.M. Jonesup front and saved. 4497e1a6dc91SRichard W.M. Jones 449800e5e9dfSChristophe 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} 449985bcbc78SDaniel P. Berrange 450085bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 450185bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 450285bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 450385bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 450485bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 450585bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 450685bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 450785bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 450885bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 450985bcbc78SDaniel P. Berrange 451085bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 451185bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 451285bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 451385bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 451485bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 451585bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 451685bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 451785bcbc78SDaniel P. Berrangeupfront and saved. 451885bcbc78SDaniel P. Berrange 451985bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 452085bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 452185bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 452285bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 452385bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 452485bcbc78SDaniel P. Berrange 45251d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 45261d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 45271d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 45281d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 45291d7b5b4aSDaniel P. Berrangepassword for decryption. 45301d7b5b4aSDaniel P. Berrange 453100e5e9dfSChristophe FergeauThe @var{priority} parameter allows to override the global default 453200e5e9dfSChristophe Fergeaupriority used by gnutls. This can be useful if the system administrator 453300e5e9dfSChristophe Fergeauneeds to use a weaker set of crypto priorities for QEMU without 453400e5e9dfSChristophe Fergeaupotentially forcing the weakness onto all applications. Or conversely 453500e5e9dfSChristophe Fergeauif one wants wants a stronger default for QEMU than for all other 453600e5e9dfSChristophe Fergeauapplications, they can do this through this parameter. Its format is 453700e5e9dfSChristophe Fergeaua gnutls priority string as described at 453800e5e9dfSChristophe Fergeau@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 453900e5e9dfSChristophe Fergeau 4540338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 45417dbb11c8SYang Hongyang 45427dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 45437dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 45447dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 4545338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 4546338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 45477dbb11c8SYang Hongyang 45487dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 45497dbb11c8SYang Hongyang 45507dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 45517dbb11c8SYang Hongyang queue of the netdev (default). 45527dbb11c8SYang Hongyang 45537dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 45547dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 45557dbb11c8SYang Hongyang 45567dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 45577dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 45587dbb11c8SYang Hongyang 4559e2521f0eSZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4560f6d3afb5SZhang Chen 4561e2521f0eSZhang 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. 4562f6d3afb5SZhang Chen 456300d5c240SZhang 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] 4564d46f75b2SZhang Chen 4565d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 456600d5c240SZhang Chen@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 456700d5c240SZhang Chenfilter-redirector will redirect packet with vnet_hdr_len. 4568d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 4569d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 4570d46f75b2SZhang Chenneed to be specified. 4571d46f75b2SZhang Chen 45724b39bdceSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4573e6eee8abSZhang Chen 4574e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 4575e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 4576e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 45774b39bdceSZhang Chenclient.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4578e6eee8abSZhang Chen 4579e6eee8abSZhang Chenusage: 4580e6eee8abSZhang Chencolo secondary: 4581e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4582e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4583e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4584e6eee8abSZhang Chen 4585c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4586d3e0c032SThomas Huth 4587d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 4588d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4589d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 4590d3e0c032SThomas Huthor Wireshark. 4591d3e0c032SThomas Huth 4592cf6af766SZhang 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}] 45937dce4e6fSZhang Chen 45947dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 45957dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 45967dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 45977dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 45985aede7f4SZhang ChenIn order to improve efficiency, we need to put the task of comparison 45995aede7f4SZhang Chenin another thread. If it has the vnet_hdr_support flag, colo compare 46005aede7f4SZhang Chenwill send/recv packet with vnet_hdr_len. 4601cf6af766SZhang ChenIf you want to use Xen COLO, will need the notify_dev to notify Xen 4602cf6af766SZhang Chencolo-frame to do checkpoint. 46037dce4e6fSZhang Chen 46047dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 46057dce4e6fSZhang Chen 46067dce4e6fSZhang Chen@example 46077dce4e6fSZhang Chen 4608cf6af766SZhang ChenKVM COLO 4609cf6af766SZhang Chen 46107dce4e6fSZhang Chenprimary: 46117dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 46127dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 46137dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 46147dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 46157dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 46167dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 46177dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 46187dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 46195aede7f4SZhang Chen-object iothread,id=iothread1 46207dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 46217dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 46227dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 46235aede7f4SZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 46247dce4e6fSZhang Chen 46257dce4e6fSZhang Chensecondary: 46267dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 46277dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 46287dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 46297dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 46307dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 46317dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 46327dce4e6fSZhang Chen 4633cf6af766SZhang Chen 4634cf6af766SZhang ChenXen COLO 4635cf6af766SZhang Chen 4636cf6af766SZhang Chenprimary: 4637cf6af766SZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 4638cf6af766SZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 4639cf6af766SZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 4640cf6af766SZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 4641cf6af766SZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 4642cf6af766SZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 4643cf6af766SZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 4644cf6af766SZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 4645cf6af766SZhang Chen-chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait 4646cf6af766SZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 4647cf6af766SZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 4648cf6af766SZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 4649cf6af766SZhang Chen-object iothread,id=iothread1 4650cf6af766SZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 4651cf6af766SZhang Chen 4652cf6af766SZhang Chensecondary: 4653cf6af766SZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 4654cf6af766SZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 4655cf6af766SZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 4656cf6af766SZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 4657cf6af766SZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4658cf6af766SZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4659cf6af766SZhang Chen 46607dce4e6fSZhang Chen@end example 46617dce4e6fSZhang Chen 46627dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 46637dce4e6fSZhang Chenthe colo-compare git log. 46647dce4e6fSZhang Chen 46651653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 46661653a5f3SGonglei 46671653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 46681653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 46691653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 46701653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 46711653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 46721653a5f3SGonglei@var{queues} is 1. 46731653a5f3SGonglei 46741653a5f3SGonglei@example 46751653a5f3SGonglei 4676664785acSThomas Huth # @value{qemu_system} \ 46771653a5f3SGonglei [...] \ 46781653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 46791653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 46801653a5f3SGonglei [...] 46811653a5f3SGonglei@end example 46821653a5f3SGonglei 4683042cea27SGonglei@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 4684042cea27SGonglei 4685042cea27SGongleiCreates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 4686042cea27SGongleiThe @var{id} parameter is a unique ID that will be used to reference this 4687042cea27SGongleicryptodev backend from the @option{virtio-crypto} device. 4688042cea27SGongleiThe chardev should be a unix domain socket backed one. The vhost-user uses 4689042cea27SGongleia specifically defined protocol to pass vhost ioctl replacement messages 4690042cea27SGongleito an application on the other end of the socket. 4691042cea27SGongleiThe @var{queues} parameter is optional, which specify the queue number 4692042cea27SGongleiof cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 4693042cea27SGonglei 4694042cea27SGonglei@example 4695042cea27SGonglei 4696664785acSThomas Huth # @value{qemu_system} \ 4697042cea27SGonglei [...] \ 4698042cea27SGonglei -chardev socket,id=chardev0,path=/path/to/socket \ 4699042cea27SGonglei -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 4700042cea27SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4701042cea27SGonglei [...] 4702042cea27SGonglei@end example 4703042cea27SGonglei 4704ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4705ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4706ac1d8878SDaniel P. Berrange 4707ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4708ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4709ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4710ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4711ac1d8878SDaniel P. Berrange 4712ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4713ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4714ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4715ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4716ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4717ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4718ac1d8878SDaniel P. Berrange 4719ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4720ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4721ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4722ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4723ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4724ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4725ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 472669c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4727ac1d8878SDaniel P. Berrange 4728ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4729ac1d8878SDaniel P. Berrange 4730ac1d8878SDaniel P. Berrange@example 4731ac1d8878SDaniel P. Berrange 4732664785acSThomas Huth # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw 4733ac1d8878SDaniel P. Berrange 4734ac1d8878SDaniel P. Berrange@end example 4735ac1d8878SDaniel P. Berrange 4736ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4737ac1d8878SDaniel P. Berrange 4738b43671f8SEric Blake # printf "letmein" > mypasswd.txt 4739664785acSThomas Huth # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw 4740ac1d8878SDaniel P. Berrange 4741ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4742ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4743ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4744ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4745ac1d8878SDaniel P. Berrange 4746ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4747ac1d8878SDaniel P. Berrange 4748ac1d8878SDaniel P. Berrange@example 4749ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4750ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4751ac1d8878SDaniel P. Berrange@end example 4752ac1d8878SDaniel P. Berrange 4753ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4754ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4755ac1d8878SDaniel P. Berrange 4756ac1d8878SDaniel P. Berrange@example 4757ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4758ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4759ac1d8878SDaniel P. Berrange@end example 4760ac1d8878SDaniel P. Berrange 4761ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4762ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4763ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4764ac1d8878SDaniel P. Berrange 4765ac1d8878SDaniel P. Berrange@example 4766b43671f8SEric Blake # SECRET=$(printf "letmein" | 4767ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4768ac1d8878SDaniel P. Berrange@end example 4769ac1d8878SDaniel P. Berrange 4770ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4771ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4772ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4773ac1d8878SDaniel P. Berrange 4774ac1d8878SDaniel P. Berrange@example 4775664785acSThomas Huth # @value{qemu_system} \ 4776ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4777ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4778ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4779ac1d8878SDaniel P. Berrange@end example 4780ac1d8878SDaniel P. Berrange 4781a9b4942fSBrijesh 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}] 4782a9b4942fSBrijesh Singh 4783a9b4942fSBrijesh SinghCreate a Secure Encrypted Virtualization (SEV) guest object, which can be used 4784a9b4942fSBrijesh Singhto provide the guest memory encryption support on AMD processors. 4785a9b4942fSBrijesh Singh 4786a9b4942fSBrijesh SinghWhen memory encryption is enabled, one of the physical address bit (aka the 4787a9b4942fSBrijesh SinghC-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 4788a9b4942fSBrijesh Singhis used to provide the C-bit position. The C-bit position is Host family dependent 4789a9b4942fSBrijesh Singhhence user must provide this value. On EPYC, the value should be 47. 4790a9b4942fSBrijesh Singh 4791a9b4942fSBrijesh SinghWhen memory encryption is enabled, we loose certain bits in physical address space. 4792a9b4942fSBrijesh SinghThe @option{reduced-phys-bits} is used to provide the number of bits we loose in 4793a9b4942fSBrijesh Singhphysical address space. Similar to C-bit, the value is Host family dependent. 4794a9b4942fSBrijesh SinghOn EPYC, the value should be 5. 4795a9b4942fSBrijesh Singh 4796a9b4942fSBrijesh SinghThe @option{sev-device} provides the device file to use for communicating with 4797a9b4942fSBrijesh Singhthe SEV firmware running inside AMD Secure Processor. The default device is 4798a9b4942fSBrijesh Singh'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 4799a9b4942fSBrijesh Singhcreated by CCP driver. 4800a9b4942fSBrijesh Singh 4801a9b4942fSBrijesh SinghThe @option{policy} provides the guest policy to be enforced by the SEV firmware 4802a9b4942fSBrijesh Singhand restrict what configuration and operational commands can be performed on this 4803a9b4942fSBrijesh Singhguest by the hypervisor. The policy should be provided by the guest owner and is 4804a9b4942fSBrijesh Singhbound to the guest and cannot be changed throughout the lifetime of the guest. 4805a9b4942fSBrijesh SinghThe default is 0. 4806a9b4942fSBrijesh Singh 4807a9b4942fSBrijesh SinghIf guest @option{policy} allows sharing the key with another SEV guest then 4808a9b4942fSBrijesh Singh@option{handle} can be use to provide handle of the guest from which to share 4809a9b4942fSBrijesh Singhthe key. 4810a9b4942fSBrijesh Singh 4811a9b4942fSBrijesh SinghThe @option{dh-cert-file} and @option{session-file} provides the guest owner's 4812a9b4942fSBrijesh SinghPublic Diffie-Hillman key defined in SEV spec. The PDH and session parameters 4813a9b4942fSBrijesh Singhare used for establishing a cryptographic session with the guest owner to 4814a9b4942fSBrijesh Singhnegotiate keys used for attestation. The file must be encoded in base64. 4815a9b4942fSBrijesh Singh 4816a9b4942fSBrijesh Singhe.g to launch a SEV guest 4817a9b4942fSBrijesh Singh@example 4818664785acSThomas Huth # @value{qemu_system_x86} \ 4819a9b4942fSBrijesh Singh ...... 4820a9b4942fSBrijesh Singh -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 4821a9b4942fSBrijesh Singh -machine ...,memory-encryption=sev0 4822a9b4942fSBrijesh Singh ..... 4823a9b4942fSBrijesh Singh 4824a9b4942fSBrijesh Singh@end example 4825fb5c4ebcSDaniel P. Berrangé 4826fb5c4ebcSDaniel P. Berrangé 4827fb5c4ebcSDaniel P. Berrangé@item -object authz-simple,id=@var{id},identity=@var{string} 4828fb5c4ebcSDaniel P. Berrangé 4829fb5c4ebcSDaniel P. BerrangéCreate an authorization object that will control access to network services. 4830fb5c4ebcSDaniel P. Berrangé 4831fb5c4ebcSDaniel P. BerrangéThe @option{identity} parameter is identifies the user and its format 4832fb5c4ebcSDaniel P. Berrangédepends on the network service that authorization object is associated 4833fb5c4ebcSDaniel P. Berrangéwith. For authorizing based on TLS x509 certificates, the identity must 4834fb5c4ebcSDaniel P. Berrangébe the x509 distinguished name. Note that care must be taken to escape 4835fb5c4ebcSDaniel P. Berrangéany commas in the distinguished name. 4836fb5c4ebcSDaniel P. Berrangé 4837fb5c4ebcSDaniel P. BerrangéAn example authorization object to validate a x509 distinguished name 4838fb5c4ebcSDaniel P. Berrangéwould look like: 4839fb5c4ebcSDaniel P. Berrangé@example 4840664785acSThomas Huth # @value{qemu_system} \ 4841fb5c4ebcSDaniel P. Berrangé ... 4842fb5c4ebcSDaniel P. Berrangé -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \ 4843fb5c4ebcSDaniel P. Berrangé ... 4844fb5c4ebcSDaniel P. Berrangé@end example 4845fb5c4ebcSDaniel P. Berrangé 4846fb5c4ebcSDaniel P. BerrangéNote the use of quotes due to the x509 distinguished name containing 4847fb5c4ebcSDaniel P. Berrangéwhitespace, and escaping of ','. 4848fb5c4ebcSDaniel P. Berrangé 484955d86984SDaniel P. Berrangé@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no} 485055d86984SDaniel P. Berrangé 485155d86984SDaniel P. BerrangéCreate an authorization object that will control access to network services. 485255d86984SDaniel P. Berrangé 485355d86984SDaniel P. BerrangéThe @option{filename} parameter is the fully qualified path to a file 485455d86984SDaniel P. Berrangécontaining the access control list rules in JSON format. 485555d86984SDaniel P. Berrangé 485655d86984SDaniel P. BerrangéAn example set of rules that match against SASL usernames might look 485755d86984SDaniel P. Berrangélike: 485855d86984SDaniel P. Berrangé 485955d86984SDaniel P. Berrangé@example 486055d86984SDaniel P. Berrangé @{ 486155d86984SDaniel P. Berrangé "rules": [ 486255d86984SDaniel P. Berrangé @{ "match": "fred", "policy": "allow", "format": "exact" @}, 486355d86984SDaniel P. Berrangé @{ "match": "bob", "policy": "allow", "format": "exact" @}, 486455d86984SDaniel P. Berrangé @{ "match": "danb", "policy": "deny", "format": "glob" @}, 486555d86984SDaniel P. Berrangé @{ "match": "dan*", "policy": "allow", "format": "exact" @}, 486655d86984SDaniel P. Berrangé ], 486755d86984SDaniel P. Berrangé "policy": "deny" 486855d86984SDaniel P. Berrangé @} 486955d86984SDaniel P. Berrangé@end example 487055d86984SDaniel P. Berrangé 487155d86984SDaniel P. BerrangéWhen checking access the object will iterate over all the rules and 487255d86984SDaniel P. Berrangéthe first rule to match will have its @option{policy} value returned 487355d86984SDaniel P. Berrangéas the result. If no rules match, then the default @option{policy} 487455d86984SDaniel P. Berrangévalue is returned. 487555d86984SDaniel P. Berrangé 487655d86984SDaniel P. BerrangéThe rules can either be an exact string match, or they can use the 487755d86984SDaniel P. Berrangésimple UNIX glob pattern matching to allow wildcards to be used. 487855d86984SDaniel P. Berrangé 487955d86984SDaniel P. BerrangéIf @option{refresh} is set to true the file will be monitored 488055d86984SDaniel P. Berrangéand automatically reloaded whenever its content changes. 488155d86984SDaniel P. Berrangé 488255d86984SDaniel P. BerrangéAs with the @code{authz-simple} object, the format of the identity 488355d86984SDaniel P. Berrangéstrings being matched depends on the network service, but is usually 488455d86984SDaniel P. Berrangéa TLS x509 distinguished name, or a SASL username. 488555d86984SDaniel P. Berrangé 488655d86984SDaniel P. BerrangéAn example authorization object to validate a SASL username 488755d86984SDaniel P. Berrangéwould look like: 488855d86984SDaniel P. Berrangé@example 4889664785acSThomas Huth # @value{qemu_system} \ 489055d86984SDaniel P. Berrangé ... 489155d86984SDaniel P. Berrangé -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes 489255d86984SDaniel P. Berrangé ... 489355d86984SDaniel P. Berrangé@end example 489455d86984SDaniel P. Berrangé 48958953caf3SDaniel P. Berrange@item -object authz-pam,id=@var{id},service=@var{string} 48968953caf3SDaniel P. Berrange 48978953caf3SDaniel P. BerrangeCreate an authorization object that will control access to network services. 48988953caf3SDaniel P. Berrange 48998953caf3SDaniel P. BerrangeThe @option{service} parameter provides the name of a PAM service to use 49008953caf3SDaniel P. Berrangefor authorization. It requires that a file @code{/etc/pam.d/@var{service}} 49018953caf3SDaniel P. Berrangeexist to provide the configuration for the @code{account} subsystem. 49028953caf3SDaniel P. Berrange 49038953caf3SDaniel P. BerrangeAn example authorization object to validate a TLS x509 distinguished 49048953caf3SDaniel P. Berrangename would look like: 49058953caf3SDaniel P. Berrange 49068953caf3SDaniel P. Berrange@example 4907664785acSThomas Huth # @value{qemu_system} \ 49088953caf3SDaniel P. Berrange ... 49098953caf3SDaniel P. Berrange -object authz-pam,id=auth0,service=qemu-vnc 49108953caf3SDaniel P. Berrange ... 49118953caf3SDaniel P. Berrange@end example 49128953caf3SDaniel P. Berrange 49138953caf3SDaniel P. BerrangeThere would then be a corresponding config file for PAM at 49148953caf3SDaniel P. Berrange@code{/etc/pam.d/qemu-vnc} that contains: 49158953caf3SDaniel P. Berrange 49168953caf3SDaniel P. Berrange@example 49178953caf3SDaniel P. Berrangeaccount requisite pam_listfile.so item=user sense=allow \ 49188953caf3SDaniel P. Berrange file=/etc/qemu/vnc.allow 49198953caf3SDaniel P. Berrange@end example 49208953caf3SDaniel P. Berrange 49218953caf3SDaniel P. BerrangeFinally the @code{/etc/qemu/vnc.allow} file would contain 49228953caf3SDaniel P. Berrangethe list of x509 distingished names that are permitted 49238953caf3SDaniel P. Berrangeaccess 49248953caf3SDaniel P. Berrange 49258953caf3SDaniel P. Berrange@example 49268953caf3SDaniel P. BerrangeCN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB 49278953caf3SDaniel P. Berrange@end example 49288953caf3SDaniel P. Berrange 4929*86d2a49bSStefan Hajnoczi@item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink} 4930*86d2a49bSStefan Hajnoczi 4931*86d2a49bSStefan HajnocziCreates a dedicated event loop thread that devices can be assigned to. This is 4932*86d2a49bSStefan Hajnocziknown as an IOThread. By default device emulation happens in vCPU threads or 4933*86d2a49bSStefan Hajnoczithe main event loop thread. This can become a scalability bottleneck. 4934*86d2a49bSStefan HajnocziIOThreads allow device emulation and I/O to run on other host CPUs. 4935*86d2a49bSStefan Hajnoczi 4936*86d2a49bSStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 4937*86d2a49bSStefan HajnocziIOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be 4938*86d2a49bSStefan Hajnocziassigned to an IOThread. Note that not all devices support an 4939*86d2a49bSStefan Hajnoczi@option{iothread} parameter. 4940*86d2a49bSStefan Hajnoczi 4941*86d2a49bSStefan HajnocziThe @code{query-iothreads} QMP command lists IOThreads and reports their thread 4942*86d2a49bSStefan HajnocziIDs so that the user can configure host CPU pinning/affinity. 4943*86d2a49bSStefan Hajnoczi 4944*86d2a49bSStefan HajnocziIOThreads use an adaptive polling algorithm to reduce event loop latency. 4945*86d2a49bSStefan HajnocziInstead of entering a blocking system call to monitor file descriptors and then 4946*86d2a49bSStefan Hajnoczipay the cost of being woken up when an event occurs, the polling algorithm 4947*86d2a49bSStefan Hajnoczispins waiting for events for a short time. The algorithm's default parameters 4948*86d2a49bSStefan Hajnocziare suitable for many cases but can be adjusted based on knowledge of the 4949*86d2a49bSStefan Hajnocziworkload and/or host device latency. 4950*86d2a49bSStefan Hajnoczi 4951*86d2a49bSStefan HajnocziThe @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy 4952*86d2a49bSStefan Hajnocziwait for events. Polling can be disabled by setting this value to 0. 4953*86d2a49bSStefan Hajnoczi 4954*86d2a49bSStefan HajnocziThe @option{poll-grow} parameter is the multiplier used to increase the polling 4955*86d2a49bSStefan Hajnoczitime when the algorithm detects it is missing events due to not polling long 4956*86d2a49bSStefan Hajnoczienough. 4957*86d2a49bSStefan Hajnoczi 4958*86d2a49bSStefan HajnocziThe @option{poll-shrink} parameter is the divisor used to decrease the polling 4959*86d2a49bSStefan Hajnoczitime when the algorithm detects it is spending too long polling without 4960*86d2a49bSStefan Hajnocziencountering events. 4961*86d2a49bSStefan Hajnoczi 4962*86d2a49bSStefan HajnocziThe polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}): 4963*86d2a49bSStefan Hajnoczi 4964*86d2a49bSStefan Hajnoczi@example 4965*86d2a49bSStefan Hajnoczi(qemu) qom-set /objects/iothread1 poll-max-ns 100000 4966*86d2a49bSStefan Hajnoczi@end example 49678953caf3SDaniel P. Berrange 4968b9174d4fSDaniel P. Berrange@end table 4969b9174d4fSDaniel P. Berrange 4970b9174d4fSDaniel P. BerrangeETEXI 4971b9174d4fSDaniel P. Berrange 4972b9174d4fSDaniel P. Berrange 49733dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 49743dbf2c7fSStefan WeilSTEXI 49753dbf2c7fSStefan Weil@end table 49763dbf2c7fSStefan WeilETEXI 4977