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, 14112b7f57eSMichael Tokarev "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,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" 14558a04db1SAndre Przywara " cores= number of CPU cores on one socket\n" 14658a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 147ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 148ad96090aSBlue Swirl QEMU_ARCH_ALL) 1495824d651Sblueswir1STEXI 15012b7f57eSMichael Tokarev@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1516616b2adSStefan Weil@findex -smp 1525824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1535824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1545824d651Sblueswir1to 4. 15558a04db1SAndre PrzywaraFor the PC target, the number of @var{cores} per socket, the number 15658a04db1SAndre Przywaraof @var{threads} per cores and the total number of @var{sockets} can be 15758a04db1SAndre Przywaraspecified. Missing values will be computed. If any on the three values is 15858a04db1SAndre Przywaragiven, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 15958a04db1SAndre Przywaraspecifies the maximum number of hotpluggable CPUs. 1605824d651Sblueswir1ETEXI 1615824d651Sblueswir1 162268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 163e0ee9fd0SEduardo Habkost "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1640f203430SHe Chen "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1652d19c656SIgor Mammedov "-numa dist,src=source,dst=destination,val=distance\n" 1662d19c656SIgor Mammedov "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n", 1672d19c656SIgor Mammedov QEMU_ARCH_ALL) 168268a362cSaliguoriSTEXI 169e0ee9fd0SEduardo Habkost@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 170e0ee9fd0SEduardo Habkost@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 1710f203430SHe Chen@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 172419fcdecSIgor Mammedov@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 1736616b2adSStefan Weil@findex -numa 1744b9a5dd7SEduardo HabkostDefine a NUMA node and assign RAM and VCPUs to it. 1750f203430SHe ChenSet the NUMA distance from a source node to a destination node. 1767febe36fSPaolo Bonzini 177419fcdecSIgor MammedovLegacy VCPU assignment uses @samp{cpus} option where 1784b9a5dd7SEduardo Habkost@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 1794b9a5dd7SEduardo Habkost@samp{cpus} option represent a contiguous range of CPU indexes 1804b9a5dd7SEduardo Habkost(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 1814b9a5dd7SEduardo Habkostset of VCPUs can be represented by providing multiple @samp{cpus} 1824b9a5dd7SEduardo Habkostoptions. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 1834b9a5dd7SEduardo Habkostsplit between them. 1844b9a5dd7SEduardo Habkost 1854b9a5dd7SEduardo HabkostFor example, the following option assigns VCPUs 0, 1, 2 and 5 to 1864b9a5dd7SEduardo Habkosta NUMA node: 1874b9a5dd7SEduardo Habkost@example 1884b9a5dd7SEduardo Habkost-numa node,cpus=0-2,cpus=5 1894b9a5dd7SEduardo Habkost@end example 1904b9a5dd7SEduardo Habkost 191419fcdecSIgor Mammedov@samp{cpu} option is a new alternative to @samp{cpus} option 192419fcdecSIgor Mammedovwhich uses @samp{socket-id|core-id|thread-id} properties to assign 193419fcdecSIgor MammedovCPU objects to a @var{node} using topology layout properties of CPU. 194419fcdecSIgor MammedovThe set of properties is machine specific, and depends on used 195419fcdecSIgor Mammedovmachine type/@samp{smp} options. It could be queried with 196419fcdecSIgor Mammedov@samp{hotpluggable-cpus} monitor command. 197419fcdecSIgor Mammedov@samp{node-id} property specifies @var{node} to which CPU object 198419fcdecSIgor Mammedovwill be assigned, it's required for @var{node} to be declared 199419fcdecSIgor Mammedovwith @samp{node} option before it's used with @samp{cpu} option. 200419fcdecSIgor Mammedov 201419fcdecSIgor MammedovFor example: 202419fcdecSIgor Mammedov@example 203419fcdecSIgor Mammedov-M pc \ 204419fcdecSIgor Mammedov-smp 1,sockets=2,maxcpus=2 \ 205419fcdecSIgor Mammedov-numa node,nodeid=0 -numa node,nodeid=1 \ 206419fcdecSIgor Mammedov-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 207419fcdecSIgor Mammedov@end example 208419fcdecSIgor Mammedov 2094b9a5dd7SEduardo Habkost@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 2104b9a5dd7SEduardo Habkostassigns RAM from a given memory backend device to a node. If 2114b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 2124b9a5dd7SEduardo Habkostsplit equally between them. 2134b9a5dd7SEduardo Habkost 2144b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 2154b9a5dd7SEduardo Habkostif one node uses @samp{memdev}, all of them have to use it. 2164b9a5dd7SEduardo Habkost 2170f203430SHe Chen@var{source} and @var{destination} are NUMA node IDs. 2180f203430SHe Chen@var{distance} is the NUMA distance from @var{source} to @var{destination}. 2190f203430SHe ChenThe distance from a node to itself is always 10. If any pair of nodes is 2200f203430SHe Chengiven a distance, then all pairs must be given distances. Although, when 2210f203430SHe Chendistances are only given in one direction for each pair of nodes, then 2220f203430SHe Chenthe distances in the opposite directions are assumed to be the same. If, 2230f203430SHe Chenhowever, an asymmetrical pair of distances is given for even one node 2240f203430SHe Chenpair, then all node pairs must be provided distance values for both 2250f203430SHe Chendirections, even when they are symmetrical. When a node is unreachable 2260f203430SHe Chenfrom another node, set the pair's distance to 255. 2270f203430SHe Chen 2284b9a5dd7SEduardo HabkostNote that the -@option{numa} option doesn't allocate any of the 2294b9a5dd7SEduardo Habkostspecified resources, it just assigns existing resources to NUMA 2304b9a5dd7SEduardo Habkostnodes. This means that one still has to use the @option{-m}, 2314b9a5dd7SEduardo Habkost@option{-smp} options to allocate RAM and VCPUs respectively. 2324b9a5dd7SEduardo Habkost 233268a362cSaliguoriETEXI 234268a362cSaliguori 23510adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 23610adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 23710adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 23810adb8beSMarkus ArmbrusterSTEXI 23910adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 24010adb8beSMarkus Armbruster@findex -add-fd 24110adb8beSMarkus Armbruster 24210adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 24310adb8beSMarkus Armbruster 24410adb8beSMarkus Armbruster@table @option 24510adb8beSMarkus Armbruster@item fd=@var{fd} 24610adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 24710adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 24810adb8beSMarkus Armbruster@item set=@var{set} 24910adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 25010adb8beSMarkus Armbruster@item opaque=@var{opaque} 25110adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 25210adb8beSMarkus Armbruster@end table 25310adb8beSMarkus Armbruster 25410adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 25510adb8beSMarkus Armbruster@example 25610adb8beSMarkus Armbrusterqemu-system-i386 25710adb8beSMarkus Armbruster-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 25810adb8beSMarkus Armbruster-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 25910adb8beSMarkus Armbruster-drive file=/dev/fdset/2,index=0,media=disk 26010adb8beSMarkus Armbruster@end example 26110adb8beSMarkus ArmbrusterETEXI 26210adb8beSMarkus Armbruster 26310adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 26410adb8beSMarkus Armbruster "-set group.id.arg=value\n" 26510adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 26610adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 26710adb8beSMarkus ArmbrusterSTEXI 26810adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 26910adb8beSMarkus Armbruster@findex -set 270e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 27110adb8beSMarkus ArmbrusterETEXI 27210adb8beSMarkus Armbruster 27310adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 2743751d7c4SPaolo Bonzini "-global driver.property=value\n" 2753751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 27610adb8beSMarkus Armbruster " set a global default for a driver property\n", 27710adb8beSMarkus Armbruster QEMU_ARCH_ALL) 27810adb8beSMarkus ArmbrusterSTEXI 27910adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 2803751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 28110adb8beSMarkus Armbruster@findex -global 28210adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 28310adb8beSMarkus Armbruster 28410adb8beSMarkus Armbruster@example 2851c9f3b88SMarkus Armbrusterqemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img 28610adb8beSMarkus Armbruster@end example 28710adb8beSMarkus Armbruster 28810adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 28910adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 29010adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 2913751d7c4SPaolo Bonzini 292ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 293ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 294ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 29510adb8beSMarkus ArmbrusterETEXI 29610adb8beSMarkus Armbruster 29710adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 29810adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 299c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 30010adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 30110adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 30210adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 30310adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 30410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 30510adb8beSMarkus ArmbrusterSTEXI 306c8a6ae8bSAmos 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] 30710adb8beSMarkus Armbruster@findex -boot 30810adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 309d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 31010adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 31110adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 31210adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 313c0d9f7d0SThomas Huth@option{once}. Note that the @option{order} or @option{once} parameter 314c0d9f7d0SThomas Huthshould not be used together with the @option{bootindex} property of 315c0d9f7d0SThomas Huthdevices, since the firmware implementations normally do not support both 316c0d9f7d0SThomas Huthat the same time. 31710adb8beSMarkus Armbruster 31810adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 31910adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 32010adb8beSMarkus Armbruster 32110adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 32210adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 32310adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 32410adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 32510adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 32610adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 32710adb8beSMarkus Armbruster 32810adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 32910adb8beSMarkus Armbrusterwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 33010adb8beSMarkus Armbrusterreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 33110adb8beSMarkus Armbrustersystem support it. 33210adb8beSMarkus Armbruster 333c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 334c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 335c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 336c8a6ae8bSAmos Kong 33710adb8beSMarkus Armbruster@example 33810adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 33910adb8beSMarkus Armbrusterqemu-system-i386 -boot order=nc 34010adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 34110adb8beSMarkus Armbrusterqemu-system-i386 -boot once=d 34210adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 34310adb8beSMarkus Armbrusterqemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 34410adb8beSMarkus Armbruster@end example 34510adb8beSMarkus Armbruster 34610adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 34710adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 34810adb8beSMarkus ArmbrusterETEXI 34910adb8beSMarkus Armbruster 35010adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 35189f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 3526e1d3c1cSIgor Mammedov " configure guest RAM\n" 3530daba1f0SAlexander Graf " size: initial amount of guest memory\n" 354c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 355b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 356b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 3576e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 35810adb8beSMarkus ArmbrusterSTEXI 3599fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 36010adb8beSMarkus Armbruster@findex -m 3619fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 3629fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 3639fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 3649fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 3659fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 3669fcc0794SLuiz Capitulino 3679fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 3689fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 3699fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 3709fcc0794SLuiz Capitulino 3719fcc0794SLuiz Capitulino@example 3729fcc0794SLuiz Capitulinoqemu-system-x86_64 -m 1G,slots=3,maxmem=4G 3739fcc0794SLuiz Capitulino@end example 3749fcc0794SLuiz Capitulino 3759fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 3769fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 37710adb8beSMarkus ArmbrusterETEXI 37810adb8beSMarkus Armbruster 37910adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 38010adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 38110adb8beSMarkus ArmbrusterSTEXI 38210adb8beSMarkus Armbruster@item -mem-path @var{path} 38310adb8beSMarkus Armbruster@findex -mem-path 38410adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 38510adb8beSMarkus ArmbrusterETEXI 38610adb8beSMarkus Armbruster 38710adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 38810adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 38910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 39010adb8beSMarkus ArmbrusterSTEXI 39110adb8beSMarkus Armbruster@item -mem-prealloc 39210adb8beSMarkus Armbruster@findex -mem-prealloc 39310adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 39410adb8beSMarkus ArmbrusterETEXI 39510adb8beSMarkus Armbruster 39610adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 39710adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 39810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 39910adb8beSMarkus ArmbrusterSTEXI 40010adb8beSMarkus Armbruster@item -k @var{language} 40110adb8beSMarkus Armbruster@findex -k 40210adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 40310adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 40432945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 40510adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 40610adb8beSMarkus Armbrusterhosts. 40710adb8beSMarkus Armbruster 40810adb8beSMarkus ArmbrusterThe available layouts are: 40910adb8beSMarkus Armbruster@example 41010adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 41110adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 41210adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 41310adb8beSMarkus Armbruster@end example 41410adb8beSMarkus Armbruster 41510adb8beSMarkus ArmbrusterThe default is @code{en-us}. 41610adb8beSMarkus ArmbrusterETEXI 41710adb8beSMarkus Armbruster 41810adb8beSMarkus Armbruster 41910adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 42010adb8beSMarkus Armbruster "-audio-help print list of audio drivers and their options\n", 42110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 42210adb8beSMarkus ArmbrusterSTEXI 42310adb8beSMarkus Armbruster@item -audio-help 42410adb8beSMarkus Armbruster@findex -audio-help 42510adb8beSMarkus ArmbrusterWill show the audio subsystem help: list of drivers, tunable 42610adb8beSMarkus Armbrusterparameters. 42710adb8beSMarkus ArmbrusterETEXI 42810adb8beSMarkus Armbruster 42910adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 43010adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 43110adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 43210adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 43310adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 43410adb8beSMarkus ArmbrusterSTEXI 43510adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 43610adb8beSMarkus Armbruster@findex -soundhw 43710adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 43810adb8beSMarkus Armbrusteravailable sound hardware. 43910adb8beSMarkus Armbruster 44010adb8beSMarkus Armbruster@example 44110adb8beSMarkus Armbrusterqemu-system-i386 -soundhw sb16,adlib disk.img 44210adb8beSMarkus Armbrusterqemu-system-i386 -soundhw es1370 disk.img 44310adb8beSMarkus Armbrusterqemu-system-i386 -soundhw ac97 disk.img 44410adb8beSMarkus Armbrusterqemu-system-i386 -soundhw hda disk.img 44510adb8beSMarkus Armbrusterqemu-system-i386 -soundhw all disk.img 44610adb8beSMarkus Armbrusterqemu-system-i386 -soundhw help 44710adb8beSMarkus Armbruster@end example 44810adb8beSMarkus Armbruster 44910adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 45010adb8beSMarkus Armbrusterrequire manually specifying clocking. 45110adb8beSMarkus Armbruster 45210adb8beSMarkus Armbruster@example 45310adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 45410adb8beSMarkus Armbruster@end example 45510adb8beSMarkus ArmbrusterETEXI 45610adb8beSMarkus Armbruster 45710adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 45810adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 45910adb8beSMarkus Armbruster " add device (based on driver)\n" 46010adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 46110adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 46210adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 46310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 46410adb8beSMarkus ArmbrusterSTEXI 46510adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 46610adb8beSMarkus Armbruster@findex -device 46710adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 46810adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 46910adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 47010adb8beSMarkus Armbruster@code{-device @var{driver},help}. 471f8490451SCorey Minyard 472f8490451SCorey MinyardSome drivers are: 473540c07d3SCédric Le Goater@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}] 474f8490451SCorey Minyard 475f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 476f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 477f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 478f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 479f8490451SCorey Minyard 480f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 481f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 482f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 483f8490451SCorey Minyardit. 484f8490451SCorey Minyard 4858c6fd7f3SCédric Le Goater@table @option 4868c6fd7f3SCédric Le Goater@item bmc=@var{id} 4878c6fd7f3SCédric Le GoaterThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 4888c6fd7f3SCédric Le Goater@item slave_addr=@var{val} 4898c6fd7f3SCédric Le GoaterDefine slave address to use for the BMC. The default is 0x20. 4908c6fd7f3SCédric Le Goater@item sdrfile=@var{file} 4918c6fd7f3SCédric Le Goaterfile containing raw Sensor Data Records (SDR) data. The default is none. 492540c07d3SCédric Le Goater@item fruareasize=@var{val} 493540c07d3SCédric Le Goatersize of a Field Replaceable Unit (FRU) area. The default is 1024. 494540c07d3SCédric Le Goater@item frudatafile=@var{file} 495540c07d3SCédric Le Goaterfile containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 4968c6fd7f3SCédric Le Goater@end table 4978c6fd7f3SCédric Le Goater 498f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 499f8490451SCorey Minyard 500f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 501f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 502f8490451SCorey Minyardto an external entity that provides the IPMI services. 503f8490451SCorey Minyard 504f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 505f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 506f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 507f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 508f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 509f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 510f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 511f8490451SCorey Minyardexposed to any outside network. 512f8490451SCorey Minyard 513f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 514f8490451SCorey Minyarddetails on the external interface. 515f8490451SCorey Minyard 516f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 517f8490451SCorey Minyard 518f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 519f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 520f8490451SCorey Minyard 521f8490451SCorey Minyard@table @option 522f8490451SCorey Minyard@item bmc=@var{id} 523f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 524f8490451SCorey Minyard@item ioport=@var{val} 525f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 526f8490451SCorey Minyard@item irq=@var{val} 527f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 528f8490451SCorey Minyardset this to 0. 529f8490451SCorey Minyard@end table 530f8490451SCorey Minyard 531f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 532f8490451SCorey Minyard 533f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 534f8490451SCorey Minyard0xe4 and the default interrupt is 5. 535f8490451SCorey Minyard 53610adb8beSMarkus ArmbrusterETEXI 53710adb8beSMarkus Armbruster 53810adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 5398f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 54010adb8beSMarkus Armbruster " set the name of the guest\n" 541*479a5747SRoman Bolshakov " string1 sets the window title and string2 the process name\n" 542*479a5747SRoman Bolshakov " When debug-threads is enabled, individual threads are given a separate name\n" 5438f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 54410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 54510adb8beSMarkus ArmbrusterSTEXI 54610adb8beSMarkus Armbruster@item -name @var{name} 54710adb8beSMarkus Armbruster@findex -name 54810adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 54910adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 55010adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 55110adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 5528f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 55310adb8beSMarkus ArmbrusterETEXI 55410adb8beSMarkus Armbruster 55510adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 55610adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 55710adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 55810adb8beSMarkus ArmbrusterSTEXI 55910adb8beSMarkus Armbruster@item -uuid @var{uuid} 56010adb8beSMarkus Armbruster@findex -uuid 56110adb8beSMarkus ArmbrusterSet system UUID. 56210adb8beSMarkus ArmbrusterETEXI 56310adb8beSMarkus Armbruster 56410adb8beSMarkus ArmbrusterSTEXI 56510adb8beSMarkus Armbruster@end table 56610adb8beSMarkus ArmbrusterETEXI 56710adb8beSMarkus ArmbrusterDEFHEADING() 56810adb8beSMarkus Armbruster 569de6b4f90SMarkus ArmbrusterDEFHEADING(Block device options:) 57010adb8beSMarkus ArmbrusterSTEXI 57110adb8beSMarkus Armbruster@table @option 57210adb8beSMarkus ArmbrusterETEXI 57310adb8beSMarkus Armbruster 5745824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 575ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 576ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 5775824d651Sblueswir1STEXI 5785824d651Sblueswir1@item -fda @var{file} 579f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 5806616b2adSStefan Weil@findex -fda 5816616b2adSStefan Weil@findex -fdb 58292a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 5835824d651Sblueswir1ETEXI 5845824d651Sblueswir1 5855824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 586ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 587ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 5885824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 589ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 590ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 5915824d651Sblueswir1STEXI 5925824d651Sblueswir1@item -hda @var{file} 593f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 594f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 595f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 5966616b2adSStefan Weil@findex -hda 5976616b2adSStefan Weil@findex -hdb 5986616b2adSStefan Weil@findex -hdc 5996616b2adSStefan Weil@findex -hdd 6005824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 6015824d651Sblueswir1ETEXI 6025824d651Sblueswir1 6035824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 604ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 605ad96090aSBlue Swirl QEMU_ARCH_ALL) 6065824d651Sblueswir1STEXI 6075824d651Sblueswir1@item -cdrom @var{file} 6086616b2adSStefan Weil@findex -cdrom 6095824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 6105824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 6115824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 6125824d651Sblueswir1ETEXI 6135824d651Sblueswir1 61442e5f393SMarkus ArmbrusterDEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 61542e5f393SMarkus Armbruster "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 61642e5f393SMarkus Armbruster " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 61742e5f393SMarkus Armbruster " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n" 61842e5f393SMarkus Armbruster " [,driver specific parameters...]\n" 61942e5f393SMarkus Armbruster " configure a block backend\n", QEMU_ARCH_ALL) 620dfaca464SKevin WolfSTEXI 621dfaca464SKevin Wolf@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 622dfaca464SKevin Wolf@findex -blockdev 623dfaca464SKevin Wolf 624370e8328SKevin WolfDefine a new block driver node. Some of the options apply to all block drivers, 625370e8328SKevin Wolfother options are only accepted for a specific block driver. See below for a 626370e8328SKevin Wolflist of generic options and options for the most common block drivers. 627370e8328SKevin Wolf 628370e8328SKevin WolfOptions that expect a reference to another node (e.g. @code{file}) can be 629370e8328SKevin Wolfgiven in two ways. Either you specify the node name of an already existing node 630370e8328SKevin Wolf(file=@var{node-name}), or you define a new node inline, adding options 631370e8328SKevin Wolffor the referenced node after a dot (file.filename=@var{path},file.aio=native). 632370e8328SKevin Wolf 633370e8328SKevin WolfA block driver node created with @option{-blockdev} can be used for a guest 634370e8328SKevin Wolfdevice by specifying its node name for the @code{drive} property in a 635370e8328SKevin Wolf@option{-device} argument that defines a block device. 636dfaca464SKevin Wolf 637dfaca464SKevin Wolf@table @option 638dfaca464SKevin Wolf@item Valid options for any block driver node: 639dfaca464SKevin Wolf 640dfaca464SKevin Wolf@table @code 641dfaca464SKevin Wolf@item driver 642dfaca464SKevin WolfSpecifies the block driver to use for the given node. 643dfaca464SKevin Wolf@item node-name 644dfaca464SKevin WolfThis defines the name of the block driver node by which it will be referenced 645dfaca464SKevin Wolflater. The name must be unique, i.e. it must not match the name of a different 646dfaca464SKevin Wolfblock driver node, or (if you use @option{-drive} as well) the ID of a drive. 647dfaca464SKevin Wolf 648dfaca464SKevin WolfIf no node name is specified, it is automatically generated. The generated node 649dfaca464SKevin Wolfname is not intended to be predictable and changes between QEMU invocations. 650dfaca464SKevin WolfFor the top level, an explicit node name must be specified. 651dfaca464SKevin Wolf@item read-only 652dfaca464SKevin WolfOpen the node read-only. Guest write attempts will fail. 653dfaca464SKevin Wolf@item cache.direct 654dfaca464SKevin WolfThe host page cache can be avoided with @option{cache.direct=on}. This will 655dfaca464SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform an 656dfaca464SKevin Wolfinternal copy of the data. 657dfaca464SKevin Wolf@item cache.no-flush 658dfaca464SKevin WolfIn case you don't care about data integrity over host failures, you can use 659dfaca464SKevin Wolf@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 660dfaca464SKevin Wolfany data to the disk but can instead keep things in cache. If anything goes 661dfaca464SKevin Wolfwrong, like your host losing power, the disk storage getting disconnected 662dfaca464SKevin Wolfaccidentally, etc. your image will most probably be rendered unusable. 663dfaca464SKevin Wolf@item discard=@var{discard} 664dfaca464SKevin Wolf@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 665dfaca464SKevin Wolfwhether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 666dfaca464SKevin Wolfignored or passed to the filesystem. Some machine types may not support 667dfaca464SKevin Wolfdiscard requests. 668dfaca464SKevin Wolf@item detect-zeroes=@var{detect-zeroes} 669dfaca464SKevin Wolf@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 670dfaca464SKevin Wolfconversion of plain zero writes by the OS to driver specific optimized 671dfaca464SKevin Wolfzero write commands. You may even choose "unmap" if @var{discard} is set 672dfaca464SKevin Wolfto "unmap" to allow a zero write to be converted to an @code{unmap} operation. 673dfaca464SKevin Wolf@end table 674dfaca464SKevin Wolf 675370e8328SKevin Wolf@item Driver-specific options for @code{file} 676370e8328SKevin Wolf 677370e8328SKevin WolfThis is the protocol-level block driver for accessing regular files. 678370e8328SKevin Wolf 679370e8328SKevin Wolf@table @code 680370e8328SKevin Wolf@item filename 681370e8328SKevin WolfThe path to the image file in the local filesystem 682370e8328SKevin Wolf@item aio 683370e8328SKevin WolfSpecifies the AIO backend (threads/native, default: threads) 6841878eaffSFam Zheng@item locking 6851878eaffSFam ZhengSpecifies whether the image file is protected with Linux OFD / POSIX locks. The 6861878eaffSFam Zhengdefault is to use the Linux Open File Descriptor API if available, otherwise no 6871878eaffSFam Zhenglock is applied. (auto/on/off, default: auto) 688370e8328SKevin Wolf@end table 689370e8328SKevin WolfExample: 690370e8328SKevin Wolf@example 691370e8328SKevin Wolf-blockdev driver=file,node-name=disk,filename=disk.img 692370e8328SKevin Wolf@end example 693370e8328SKevin Wolf 694370e8328SKevin Wolf@item Driver-specific options for @code{raw} 695370e8328SKevin Wolf 696370e8328SKevin WolfThis is the image format block driver for raw images. It is usually 697370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 698370e8328SKevin Wolf 699370e8328SKevin Wolf@table @code 700370e8328SKevin Wolf@item file 701370e8328SKevin WolfReference to or definition of the data source block driver node 702370e8328SKevin Wolf(e.g. a @code{file} driver node) 703370e8328SKevin Wolf@end table 704370e8328SKevin WolfExample 1: 705370e8328SKevin Wolf@example 706370e8328SKevin Wolf-blockdev driver=file,node-name=disk_file,filename=disk.img 707370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file=disk_file 708370e8328SKevin Wolf@end example 709370e8328SKevin WolfExample 2: 710370e8328SKevin Wolf@example 711370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 712370e8328SKevin Wolf@end example 713370e8328SKevin Wolf 714370e8328SKevin Wolf@item Driver-specific options for @code{qcow2} 715370e8328SKevin Wolf 716370e8328SKevin WolfThis is the image format block driver for qcow2 images. It is usually 717370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 718370e8328SKevin Wolf 719370e8328SKevin Wolf@table @code 720370e8328SKevin Wolf@item file 721370e8328SKevin WolfReference to or definition of the data source block driver node 722370e8328SKevin Wolf(e.g. a @code{file} driver node) 723370e8328SKevin Wolf 724370e8328SKevin Wolf@item backing 725370e8328SKevin WolfReference to or definition of the backing file block device (default is taken 7264f7be280SMax Reitzfrom the image file). It is allowed to pass @code{null} here in order to disable 7274f7be280SMax Reitzthe default backing file. 728370e8328SKevin Wolf 729370e8328SKevin Wolf@item lazy-refcounts 730370e8328SKevin WolfWhether to enable the lazy refcounts feature (on/off; default is taken from the 731370e8328SKevin Wolfimage file) 732370e8328SKevin Wolf 733370e8328SKevin Wolf@item cache-size 734370e8328SKevin WolfThe maximum total size of the L2 table and refcount block caches in bytes 73540fb215dSLeonid Bloch(default: the sum of l2-cache-size and refcount-cache-size) 736370e8328SKevin Wolf 737370e8328SKevin Wolf@item l2-cache-size 738370e8328SKevin WolfThe maximum size of the L2 table cache in bytes 73980668d0fSLeonid Bloch(default: if cache-size is not specified - 32M on Linux platforms, and 8M on 74080668d0fSLeonid Blochnon-Linux platforms; otherwise, as large as possible within the cache-size, 74180668d0fSLeonid Blochwhile permitting the requested or the minimal refcount cache size) 742370e8328SKevin Wolf 743370e8328SKevin Wolf@item refcount-cache-size 744370e8328SKevin WolfThe maximum size of the refcount block cache in bytes 74540fb215dSLeonid Bloch(default: 4 times the cluster size; or if cache-size is specified, the part of 74640fb215dSLeonid Blochit which is not used for the L2 cache) 747370e8328SKevin Wolf 748370e8328SKevin Wolf@item cache-clean-interval 749370e8328SKevin WolfClean unused entries in the L2 and refcount caches. The interval is in seconds. 750e3a7b455SLeonid BlochThe default value is 600 on supporting platforms, and 0 on other platforms. 751e3a7b455SLeonid BlochSetting it to 0 disables this feature. 752370e8328SKevin Wolf 753370e8328SKevin Wolf@item pass-discard-request 754370e8328SKevin WolfWhether discard requests to the qcow2 device should be forwarded to the data 755370e8328SKevin Wolfsource (on/off; default: on if discard=unmap is specified, off otherwise) 756370e8328SKevin Wolf 757370e8328SKevin Wolf@item pass-discard-snapshot 758370e8328SKevin WolfWhether discard requests for the data source should be issued when a snapshot 759370e8328SKevin Wolfoperation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 760370e8328SKevin Wolfdefault: on) 761370e8328SKevin Wolf 762370e8328SKevin Wolf@item pass-discard-other 763370e8328SKevin WolfWhether discard requests for the data source should be issued on other 764370e8328SKevin Wolfoccasions where a cluster gets freed (on/off; default: off) 765370e8328SKevin Wolf 766370e8328SKevin Wolf@item overlap-check 767370e8328SKevin WolfWhich overlap checks to perform for writes to the image 768370e8328SKevin Wolf(none/constant/cached/all; default: cached). For details or finer 769370e8328SKevin Wolfgranularity control refer to the QAPI documentation of @code{blockdev-add}. 770370e8328SKevin Wolf@end table 771370e8328SKevin Wolf 772370e8328SKevin WolfExample 1: 773370e8328SKevin Wolf@example 774370e8328SKevin Wolf-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 775370e8328SKevin Wolf-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 776370e8328SKevin Wolf@end example 777370e8328SKevin WolfExample 2: 778370e8328SKevin Wolf@example 779370e8328SKevin Wolf-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 780370e8328SKevin Wolf@end example 781370e8328SKevin Wolf 782370e8328SKevin Wolf@item Driver-specific options for other drivers 783370e8328SKevin WolfPlease refer to the QAPI documentation of the @code{blockdev-add} QMP command. 784370e8328SKevin Wolf 785dfaca464SKevin Wolf@end table 786dfaca464SKevin Wolf 787dfaca464SKevin WolfETEXI 78842e5f393SMarkus Armbruster 7895824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 7905824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 79192196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 792572023f7SKevin Wolf " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 793d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 794fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 7952f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 7963e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 7973e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 7983e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 7993e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 8002024c1dfSBenoît Canet " [[,iops_size=is]]\n" 80176f4afb4SAlberto Garcia " [[,group=g]]\n" 802ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 8035824d651Sblueswir1STEXI 8045824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 8056616b2adSStefan Weil@findex -drive 8065824d651Sblueswir1 807dfaca464SKevin WolfDefine a new drive. This includes creating a block driver node (the backend) as 808dfaca464SKevin Wolfwell as a guest device, and is mostly a shortcut for defining the corresponding 809dfaca464SKevin Wolf@option{-blockdev} and @option{-device} options. 810dfaca464SKevin Wolf 811dfaca464SKevin Wolf@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 812dfaca464SKevin Wolfaddition, it knows the following options: 8135824d651Sblueswir1 814b3f046c2SKevin Wolf@table @option 8155824d651Sblueswir1@item file=@var{file} 8165824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 8175824d651Sblueswir1this drive. If the filename contains comma, you must double it 8185824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 8190f5314a2SRonnie Sahlberg 8200f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 8210f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 8225824d651Sblueswir1@item if=@var{interface} 8235824d651Sblueswir1This option defines on which type on interface the drive is connected. 824ed1fcd00SCraig JellickAvailable types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 8255824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 8265824d651Sblueswir1These options define where is connected the drive by defining the bus number and 8275824d651Sblueswir1the unit id. 8285824d651Sblueswir1@item index=@var{index} 8295824d651Sblueswir1This option defines where is connected the drive by using an index in the list 8305824d651Sblueswir1of available connectors of a given interface type. 8315824d651Sblueswir1@item media=@var{media} 8325824d651Sblueswir1This option defines the type of the media: disk or cdrom. 8335824d651Sblueswir1@item snapshot=@var{snapshot} 8349d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 8359d85d557SMichael Tokarev(see @option{-snapshot}). 8365824d651Sblueswir1@item cache=@var{cache} 837dfaca464SKevin Wolf@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 838dfaca464SKevin Wolfand controls how the host cache is used to access block data. This is a 839dfaca464SKevin Wolfshortcut that sets the @option{cache.direct} and @option{cache.no-flush} 840dfaca464SKevin Wolfoptions (as in @option{-blockdev}), and additionally @option{cache.writeback}, 841dfaca464SKevin Wolfwhich provides a default for the @option{write-cache} option of block guest 842dfaca464SKevin Wolfdevices (as in @option{-device}). The modes correspond to the following 843dfaca464SKevin Wolfsettings: 844dfaca464SKevin Wolf 845dfaca464SKevin Wolf@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 846dfaca464SKevin Wolf@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 847dfaca464SKevin Wolf@c and the HTML output. 848dfaca464SKevin Wolf@example 849dfaca464SKevin Wolf@ │ cache.writeback cache.direct cache.no-flush 850dfaca464SKevin Wolf─────────────┼───────────────────────────────────────────────── 851dfaca464SKevin Wolfwriteback │ on off off 852dfaca464SKevin Wolfnone │ on on off 853dfaca464SKevin Wolfwritethrough │ off off off 854dfaca464SKevin Wolfdirectsync │ off on off 855dfaca464SKevin Wolfunsafe │ on off on 856dfaca464SKevin Wolf@end example 857dfaca464SKevin Wolf 858dfaca464SKevin WolfThe default mode is @option{cache=writeback}. 859dfaca464SKevin Wolf 8605c6c3a6cSChristoph Hellwig@item aio=@var{aio} 8615c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 8625824d651Sblueswir1@item format=@var{format} 8635824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 864d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 8655824d651Sblueswir1an untrusted format header. 866ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 867ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 868ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 869ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 870ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 871ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 872fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 873fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 874fb0490f6SStefan Hajnoczifile sectors into the image file. 87501f9cfabSStefan Hajnoczi@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 87601f9cfabSStefan HajnocziSpecify bandwidth throttling limits in bytes per second, either for all request 87701f9cfabSStefan Hajnoczitypes or for reads or writes only. Small values can lead to timeouts or hangs 87801f9cfabSStefan Hajnocziinside the guest. A safe minimum for disks is 2 MB/s. 87901f9cfabSStefan Hajnoczi@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 88001f9cfabSStefan HajnocziSpecify bursts in bytes per second, either for all request types or for reads 88101f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 88201f9cfabSStefan Hajnoczitemporarily. 88301f9cfabSStefan Hajnoczi@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 88401f9cfabSStefan HajnocziSpecify request rate limits in requests per second, either for all request 88501f9cfabSStefan Hajnoczitypes or for reads or writes only. 88601f9cfabSStefan Hajnoczi@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 88701f9cfabSStefan HajnocziSpecify bursts in requests per second, either for all request types or for reads 88801f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 88901f9cfabSStefan Hajnoczitemporarily. 89001f9cfabSStefan Hajnoczi@item iops_size=@var{is} 89101f9cfabSStefan HajnocziLet every @var{is} bytes of a request count as a new request for iops 89201f9cfabSStefan Hajnoczithrottling purposes. Use this option to prevent guests from circumventing iops 89301f9cfabSStefan Hajnoczilimits by sending fewer but larger requests. 89401f9cfabSStefan Hajnoczi@item group=@var{g} 89501f9cfabSStefan HajnocziJoin a throttling quota group with given name @var{g}. All drives that are 89601f9cfabSStefan Hajnoczimembers of the same group are accounted for together. Use this option to 89701f9cfabSStefan Hajnocziprevent guests from circumventing throttling limits by using many small disks 89801f9cfabSStefan Hajnocziinstead of a single larger disk. 8995824d651Sblueswir1@end table 9005824d651Sblueswir1 901dfaca464SKevin WolfBy default, the @option{cache.writeback=on} mode is used. It will report data 902a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 903a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 904a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 905a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 906a13e5e05SKevin Wolfdata corruption. 9075824d651Sblueswir1 908dfaca464SKevin WolfFor such guests, you should consider using @option{cache.writeback=off}. This 909a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 910a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 911a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 9125824d651Sblueswir1 913dfaca464SKevin WolfWhen using the @option{-snapshot} option, unsafe caching is always used. 914016f5cf6SAlexander Graf 915fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 916fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 917fb0490f6SStefan Hajnocziis off. 918fb0490f6SStefan Hajnoczi 9195824d651Sblueswir1Instead of @option{-cdrom} you can use: 9205824d651Sblueswir1@example 9213804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=cdrom 9225824d651Sblueswir1@end example 9235824d651Sblueswir1 9245824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 9255824d651Sblueswir1use: 9265824d651Sblueswir1@example 9273804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,media=disk 9283804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,media=disk 9293804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=disk 9303804da9dSStefan Weilqemu-system-i386 -drive file=file,index=3,media=disk 9315824d651Sblueswir1@end example 9325824d651Sblueswir1 933587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 934587ed6beSCorey Bryant@example 935587ed6beSCorey Bryantqemu-system-i386 936587ed6beSCorey Bryant-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 937587ed6beSCorey Bryant-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 938587ed6beSCorey Bryant-drive file=/dev/fdset/2,index=0,media=disk 939587ed6beSCorey Bryant@end example 940587ed6beSCorey Bryant 9415824d651Sblueswir1You can connect a CDROM to the slave of ide0: 9425824d651Sblueswir1@example 9433804da9dSStefan Weilqemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 9445824d651Sblueswir1@end example 9455824d651Sblueswir1 9465824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 9475824d651Sblueswir1@example 9483804da9dSStefan Weilqemu-system-i386 -drive if=ide,index=1,media=cdrom 9495824d651Sblueswir1@end example 9505824d651Sblueswir1 9515824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 9525824d651Sblueswir1@example 9533804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,if=floppy 9543804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,if=floppy 9555824d651Sblueswir1@end example 9565824d651Sblueswir1 9575824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 9585824d651Sblueswir1incremented: 9595824d651Sblueswir1@example 9603804da9dSStefan Weilqemu-system-i386 -drive file=a -drive file=b" 9615824d651Sblueswir1@end example 9625824d651Sblueswir1is interpreted like: 9635824d651Sblueswir1@example 9643804da9dSStefan Weilqemu-system-i386 -hda a -hdb b 9655824d651Sblueswir1@end example 9665824d651Sblueswir1ETEXI 9675824d651Sblueswir1 9685824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 969ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 970ad96090aSBlue Swirl QEMU_ARCH_ALL) 9715824d651Sblueswir1STEXI 9724e257e5eSKevin Wolf@item -mtdblock @var{file} 9736616b2adSStefan Weil@findex -mtdblock 9744e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 9755824d651Sblueswir1ETEXI 9765824d651Sblueswir1 9775824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 978ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 9795824d651Sblueswir1STEXI 9804e257e5eSKevin Wolf@item -sd @var{file} 9816616b2adSStefan Weil@findex -sd 9824e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 9835824d651Sblueswir1ETEXI 9845824d651Sblueswir1 9855824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 986ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 9875824d651Sblueswir1STEXI 9884e257e5eSKevin Wolf@item -pflash @var{file} 9896616b2adSStefan Weil@findex -pflash 9904e257e5eSKevin WolfUse @var{file} as a parallel flash image. 9915824d651Sblueswir1ETEXI 9925824d651Sblueswir1 9935824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 994ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 995ad96090aSBlue Swirl QEMU_ARCH_ALL) 9965824d651Sblueswir1STEXI 9975824d651Sblueswir1@item -snapshot 9986616b2adSStefan Weil@findex -snapshot 9995824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 10005824d651Sblueswir1the raw disk image you use is not written back. You can however force 10015824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 10025824d651Sblueswir1ETEXI 10035824d651Sblueswir1 100474db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 10052c30dd74SAneesh Kumar K.V "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 1006b96feb2cSTobias Schramm " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n" 1007b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1008b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1009b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1010b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1011b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-size=is]]\n", 101274db920cSGautham R Shenoy QEMU_ARCH_ALL) 101374db920cSGautham R Shenoy 101474db920cSGautham R ShenoySTEXI 101574db920cSGautham R Shenoy 1016b96feb2cSTobias Schramm@item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}] 101774db920cSGautham R Shenoy@findex -fsdev 10187c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 10197c92a3d2SAneesh Kumar K.V@table @option 10207c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 10217c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 102293aee84fSGreg KurzCurrently "local" and "proxy" file system drivers are supported. 10237c92a3d2SAneesh Kumar K.V@item id=@var{id} 10247c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 10257c92a3d2SAneesh Kumar K.V@item path=@var{path} 10267c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 10277c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 10287c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 10297c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 10302c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 10317c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1032b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 10332c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 10347c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 10352c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 10362c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 10377c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 10387c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1039d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 104093aee84fSGreg Kurzonly for local fsdriver. Other fsdrivers (like proxy) don't take 1041d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 10427c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 10437c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 10447c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 10457c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 10467c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 10472c74c2cbSM. Mohan Kumar@item readonly 10482c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 10492c74c2cbSM. Mohan Kumarread-write access is given. 105084a87cc4SM. Mohan Kumar@item socket=@var{socket} 105184a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 105284a87cc4SM. Mohan Kumarwith virtfs-proxy-helper 1053f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 1054f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 1055f67e3ffdSM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 1056f67e3ffdSM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 1057b96feb2cSTobias Schramm@item fmode=@var{fmode} 1058b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1059b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1060b96feb2cSTobias Schramm@item dmode=@var{dmode} 1061b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1062b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 106374db920cSGautham R Shenoy@end table 10647c92a3d2SAneesh Kumar K.V 10657c92a3d2SAneesh Kumar K.V-fsdev option is used along with -device driver "virtio-9p-pci". 10667c92a3d2SAneesh Kumar K.V@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 10677c92a3d2SAneesh Kumar K.VOptions for virtio-9p-pci driver are: 10687c92a3d2SAneesh Kumar K.V@table @option 10697c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 10707c92a3d2SAneesh Kumar K.VSpecifies the id value specified along with -fsdev option 10717c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 10727c92a3d2SAneesh Kumar K.VSpecifies the tag name to be used by the guest to mount this export point 10737c92a3d2SAneesh Kumar K.V@end table 10747c92a3d2SAneesh Kumar K.V 107574db920cSGautham R ShenoyETEXI 107674db920cSGautham R Shenoy 10773d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 10782c30dd74SAneesh Kumar K.V "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 1079b96feb2cSTobias Schramm " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n", 10803d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 10813d54abc7SGautham R Shenoy 10823d54abc7SGautham R ShenoySTEXI 10833d54abc7SGautham R Shenoy 1084b96feb2cSTobias Schramm@item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}] 10853d54abc7SGautham R Shenoy@findex -virtfs 10863d54abc7SGautham R Shenoy 10877c92a3d2SAneesh Kumar K.VThe general form of a Virtual File system pass-through options are: 10887c92a3d2SAneesh Kumar K.V@table @option 10897c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 10907c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 109193aee84fSGreg KurzCurrently "local" and "proxy" file system drivers are supported. 10927c92a3d2SAneesh Kumar K.V@item id=@var{id} 10937c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 10947c92a3d2SAneesh Kumar K.V@item path=@var{path} 10957c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 10967c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 10977c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 10987c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 10992c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 11007c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1101b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 11022c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 11037c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 11042c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 11052c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 11067c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 11077c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1108d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 110993aee84fSGreg Kurzfor local fsdriver. Other fsdrivers (like proxy) don't take security 1110d9b36a6eSM. Mohan Kumarmodel as a parameter. 11117c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 11127c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 11137c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 11147c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 11157c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 11162c74c2cbSM. Mohan Kumar@item readonly 11172c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 11182c74c2cbSM. Mohan Kumarread-write access is given. 111984a87cc4SM. Mohan Kumar@item socket=@var{socket} 112084a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 112184a87cc4SM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 112284a87cc4SM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 1123f67e3ffdSM. Mohan Kumar@item sock_fd 1124f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 1125f67e3ffdSM. Mohan Kumardescriptor for interfacing with virtfs-proxy-helper 1126b96feb2cSTobias Schramm@item fmode=@var{fmode} 1127b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1128b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1129b96feb2cSTobias Schramm@item dmode=@var{dmode} 1130b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1131b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 11323d54abc7SGautham R Shenoy@end table 11333d54abc7SGautham R ShenoyETEXI 11343d54abc7SGautham R Shenoy 11359db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 11369db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 11379db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 11389db221aeSAneesh Kumar K.VSTEXI 11399db221aeSAneesh Kumar K.V@item -virtfs_synth 11409db221aeSAneesh Kumar K.V@findex -virtfs_synth 11419db221aeSAneesh Kumar K.VCreate synthetic file system image 11429db221aeSAneesh Kumar K.VETEXI 11439db221aeSAneesh Kumar K.V 114461d70487SMarkus ArmbrusterDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 114561d70487SMarkus Armbruster "-iscsi [user=user][,password=password]\n" 114661d70487SMarkus Armbruster " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 114761d70487SMarkus Armbruster " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 114861d70487SMarkus Armbruster " [,timeout=timeout]\n" 114961d70487SMarkus Armbruster " iSCSI session parameters\n", QEMU_ARCH_ALL) 115061d70487SMarkus Armbruster 11515824d651Sblueswir1STEXI 115244743148SMarkus Armbruster@item -iscsi 115344743148SMarkus Armbruster@findex -iscsi 115444743148SMarkus ArmbrusterConfigure iSCSI session parameters. 115544743148SMarkus ArmbrusterETEXI 115644743148SMarkus Armbruster 115744743148SMarkus ArmbrusterSTEXI 11585824d651Sblueswir1@end table 11595824d651Sblueswir1ETEXI 11605824d651Sblueswir1DEFHEADING() 11615824d651Sblueswir1 1162de6b4f90SMarkus ArmbrusterDEFHEADING(USB options:) 116310adb8beSMarkus ArmbrusterSTEXI 116410adb8beSMarkus Armbruster@table @option 116510adb8beSMarkus ArmbrusterETEXI 116610adb8beSMarkus Armbruster 116710adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 1168a358a3afSThomas Huth "-usb enable the USB driver (if it is not used by default yet)\n", 116910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 117010adb8beSMarkus ArmbrusterSTEXI 117110adb8beSMarkus Armbruster@item -usb 117210adb8beSMarkus Armbruster@findex -usb 1173a358a3afSThomas HuthEnable the USB driver (if it is not used by default yet). 117410adb8beSMarkus ArmbrusterETEXI 117510adb8beSMarkus Armbruster 117610adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 117710adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 117810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 117910adb8beSMarkus ArmbrusterSTEXI 118010adb8beSMarkus Armbruster 118110adb8beSMarkus Armbruster@item -usbdevice @var{devname} 118210adb8beSMarkus Armbruster@findex -usbdevice 1183a358a3afSThomas HuthAdd the USB device @var{devname}. Note that this option is deprecated, 1184a358a3afSThomas Huthplease use @code{-device usb-...} instead. @xref{usb_devices}. 118510adb8beSMarkus Armbruster 118610adb8beSMarkus Armbruster@table @option 118710adb8beSMarkus Armbruster 118810adb8beSMarkus Armbruster@item mouse 118910adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 119010adb8beSMarkus Armbruster 119110adb8beSMarkus Armbruster@item tablet 119210adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 119310adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 119410adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 119510adb8beSMarkus Armbruster 119610adb8beSMarkus Armbruster@item braille 119710adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 119810adb8beSMarkus Armbrusteror fake device. 119910adb8beSMarkus Armbruster 120010adb8beSMarkus Armbruster@end table 120110adb8beSMarkus ArmbrusterETEXI 120210adb8beSMarkus Armbruster 120310adb8beSMarkus ArmbrusterSTEXI 120410adb8beSMarkus Armbruster@end table 120510adb8beSMarkus ArmbrusterETEXI 120610adb8beSMarkus ArmbrusterDEFHEADING() 120710adb8beSMarkus Armbruster 1208de6b4f90SMarkus ArmbrusterDEFHEADING(Display options:) 12095824d651Sblueswir1STEXI 12105824d651Sblueswir1@table @option 12115824d651Sblueswir1ETEXI 12125824d651Sblueswir1 12131472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 12141472a95bSJes Sorensen "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 12154867e47cSElie Tournier " [,window_close=on|off][,gl=on|core|es|off]\n" 1216f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 1217f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 1218f04ec5afSRobert Ho "-display curses\n" 1219144aaa99SErik Skultety "-display none\n" 1220144aaa99SErik Skultety "-display egl-headless[,rendernode=<file>]" 1221f04ec5afSRobert Ho " select display type\n" 1222f04ec5afSRobert Ho "The default display is equivalent to\n" 1223f04ec5afSRobert Ho#if defined(CONFIG_GTK) 1224f04ec5afSRobert Ho "\t\"-display gtk\"\n" 1225f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 1226f04ec5afSRobert Ho "\t\"-display sdl\"\n" 1227f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 1228f04ec5afSRobert Ho "\t\"-display cocoa\"\n" 1229f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 1230f04ec5afSRobert Ho "\t\"-vnc localhost:0,to=99,id=default\"\n" 1231f04ec5afSRobert Ho#else 1232f04ec5afSRobert Ho "\t\"-display none\"\n" 1233f04ec5afSRobert Ho#endif 1234f04ec5afSRobert Ho , QEMU_ARCH_ALL) 12351472a95bSJes SorensenSTEXI 12361472a95bSJes Sorensen@item -display @var{type} 12371472a95bSJes Sorensen@findex -display 12381472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 12391472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 12401472a95bSJes Sorensen@table @option 12411472a95bSJes Sorensen@item sdl 12421472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 12431472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 12441472a95bSJes Sorensen@item curses 12451472a95bSJes SorensenDisplay video output via curses. For graphics device models which 12461472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 12471472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 12481472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 12491472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 12504171d32eSJes Sorensen@item none 12514171d32eSJes SorensenDo not display video output. The guest will still see an emulated 12524171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 12534171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 12544171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 12554171d32eSJes Sorensenthe destination of the serial and parallel port data. 1256881249c7SJan Kiszka@item gtk 1257881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 1258881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 1259881249c7SJan Kiszkaruntime. 12603264ff12SJes Sorensen@item vnc 12613264ff12SJes SorensenStart a VNC server on display <arg> 1262144aaa99SErik Skultety@item egl-headless 1263144aaa99SErik SkultetyOffload all OpenGL operations to a local DRI device. For any graphical display, 1264144aaa99SErik Skultetythis display needs to be paired with either VNC or SPICE displays. 12651472a95bSJes Sorensen@end table 12661472a95bSJes SorensenETEXI 12671472a95bSJes Sorensen 12685824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 1269ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1270ad96090aSBlue Swirl QEMU_ARCH_ALL) 12715824d651Sblueswir1STEXI 12725824d651Sblueswir1@item -nographic 12736616b2adSStefan Weil@findex -nographic 1274dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1275dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1276dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1277dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1278dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1279dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1280dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1281dc0a3e44SColin Lordswitching between the console and monitor. 12825824d651Sblueswir1ETEXI 12835824d651Sblueswir1 12845824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1285f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1286ad96090aSBlue Swirl QEMU_ARCH_ALL) 12875824d651Sblueswir1STEXI 12885824d651Sblueswir1@item -curses 1289b8f490ebSMarkus Armbruster@findex -curses 1290dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1291dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1292dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1293dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1294dc0a3e44SColin Lordmode. 12955824d651Sblueswir1ETEXI 12965824d651Sblueswir1 12975824d651Sblueswir1DEF("no-frame", 0, QEMU_OPTION_no_frame, 1298ad96090aSBlue Swirl "-no-frame open SDL window without a frame and window decorations\n", 1299ad96090aSBlue Swirl QEMU_ARCH_ALL) 13005824d651Sblueswir1STEXI 13015824d651Sblueswir1@item -no-frame 13026616b2adSStefan Weil@findex -no-frame 13035824d651Sblueswir1Do not use decorations for SDL windows and start them using the whole 13045824d651Sblueswir1available screen space. This makes the using QEMU in a dedicated desktop 13055824d651Sblueswir1workspace more convenient. 13065824d651Sblueswir1ETEXI 13075824d651Sblueswir1 13085824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1309ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1310ad96090aSBlue Swirl QEMU_ARCH_ALL) 13115824d651Sblueswir1STEXI 13125824d651Sblueswir1@item -alt-grab 13136616b2adSStefan Weil@findex -alt-grab 1314de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1315de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 13165824d651Sblueswir1ETEXI 13175824d651Sblueswir1 13180ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1319ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1320ad96090aSBlue Swirl QEMU_ARCH_ALL) 13210ca9f8a4SDustin KirklandSTEXI 13220ca9f8a4SDustin Kirkland@item -ctrl-grab 13236616b2adSStefan Weil@findex -ctrl-grab 1324de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1325de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 13260ca9f8a4SDustin KirklandETEXI 13270ca9f8a4SDustin Kirkland 13285824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1329ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 13305824d651Sblueswir1STEXI 13315824d651Sblueswir1@item -no-quit 13326616b2adSStefan Weil@findex -no-quit 13335824d651Sblueswir1Disable SDL window close capability. 13345824d651Sblueswir1ETEXI 13355824d651Sblueswir1 13365824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1337f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 13385824d651Sblueswir1STEXI 13395824d651Sblueswir1@item -sdl 13406616b2adSStefan Weil@findex -sdl 13415824d651Sblueswir1Enable SDL. 13425824d651Sblueswir1ETEXI 13435824d651Sblueswir1 134429b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 134527af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 134627af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 134727af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1348fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 134927af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 135027af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 135127af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 135227af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 135327af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 135427af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 135527af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 135627af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 13575ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 13585ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 13597b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 136027af7788SYonit Halperin " enable spice\n" 136127af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 136227af7788SYonit Halperin QEMU_ARCH_ALL) 136329b0040bSGerd HoffmannSTEXI 136429b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 136529b0040bSGerd Hoffmann@findex -spice 136629b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 136729b0040bSGerd Hoffmann 136829b0040bSGerd Hoffmann@table @option 136929b0040bSGerd Hoffmann 137029b0040bSGerd Hoffmann@item port=<nr> 1371c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 137229b0040bSGerd Hoffmann 1373333b0eebSGerd Hoffmann@item addr=<addr> 1374333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1375333b0eebSGerd Hoffmann 1376333b0eebSGerd Hoffmann@item ipv4 1377f9cfd655SMarkus Armbruster@itemx ipv6 1378f9cfd655SMarkus Armbruster@itemx unix 1379333b0eebSGerd HoffmannForce using the specified IP version. 1380333b0eebSGerd Hoffmann 138129b0040bSGerd Hoffmann@item password=<secret> 138229b0040bSGerd HoffmannSet the password you need to authenticate. 138329b0040bSGerd Hoffmann 138448b3ed0aSMarc-André Lureau@item sasl 138548b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 138648b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 138748b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 138848b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 138948b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 139048b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 139148b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 139248b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 139348b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 139448b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 139548b3ed0aSMarc-André Lureaucredentials. 139648b3ed0aSMarc-André Lureau 139729b0040bSGerd Hoffmann@item disable-ticketing 139829b0040bSGerd HoffmannAllow client connects without authentication. 139929b0040bSGerd Hoffmann 1400d4970b07SHans de Goede@item disable-copy-paste 1401d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1402d4970b07SHans de Goede 14035ad24e5fSHans de Goede@item disable-agent-file-xfer 14045ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 14055ad24e5fSHans de Goede 1406c448e855SGerd Hoffmann@item tls-port=<nr> 1407c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1408c448e855SGerd Hoffmann 1409c448e855SGerd Hoffmann@item x509-dir=<dir> 1410c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1411c448e855SGerd Hoffmann 1412c448e855SGerd Hoffmann@item x509-key-file=<file> 1413f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1414f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1415f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1416f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1417c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1418c448e855SGerd Hoffmann 1419c448e855SGerd Hoffmann@item tls-ciphers=<list> 1420c448e855SGerd HoffmannSpecify which ciphers to use. 1421c448e855SGerd Hoffmann 1422d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1423f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 142417b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 142517b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 142617b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 142717b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 142817b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 142917b6dea0SGerd Hoffmann 14309f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 14319f04e09eSYonit HalperinConfigure image compression (lossless). 14329f04e09eSYonit HalperinDefault is auto_glz. 14339f04e09eSYonit Halperin 14349f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1435f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 14369f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 14379f04e09eSYonit HalperinDefault is auto. 14389f04e09eSYonit Halperin 143984a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 144093ca519eSLi ZhijianConfigure video stream detection. Default is off. 144184a23f25SGerd Hoffmann 144284a23f25SGerd Hoffmann@item agent-mouse=[on|off] 144384a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 144484a23f25SGerd Hoffmann 144584a23f25SGerd Hoffmann@item playback-compression=[on|off] 144684a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 144784a23f25SGerd Hoffmann 14488c957053SYonit Halperin@item seamless-migration=[on|off] 14498c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 14508c957053SYonit Halperin 1451474114b7SGerd Hoffmann@item gl=[on|off] 1452474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1453474114b7SGerd Hoffmann 14547b525508SMarc-André Lureau@item rendernode=<file> 14557b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 14567b525508SMarc-André Lureauthe first available. (Since 2.9) 14577b525508SMarc-André Lureau 145829b0040bSGerd Hoffmann@end table 145929b0040bSGerd HoffmannETEXI 146029b0040bSGerd Hoffmann 14615824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1462ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1463ad96090aSBlue Swirl QEMU_ARCH_ALL) 14645824d651Sblueswir1STEXI 14655824d651Sblueswir1@item -portrait 14666616b2adSStefan Weil@findex -portrait 14675824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 14685824d651Sblueswir1ETEXI 14695824d651Sblueswir1 14709312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 14719312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 14729312805dSVasily Khoruzhick QEMU_ARCH_ALL) 14739312805dSVasily KhoruzhickSTEXI 14746265c43bSMarkus Armbruster@item -rotate @var{deg} 14759312805dSVasily Khoruzhick@findex -rotate 14769312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 14779312805dSVasily KhoruzhickETEXI 14789312805dSVasily Khoruzhick 14795824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1480a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1481ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 14825824d651Sblueswir1STEXI 1483e4558dcaSmalc@item -vga @var{type} 14846616b2adSStefan Weil@findex -vga 14855824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1486b3f046c2SKevin Wolf@table @option 14875824d651Sblueswir1@item cirrus 14885824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 14895824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 14905824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 149141eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 14925824d651Sblueswir1@item std 14935824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 14945824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 14955824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 149641eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 14975824d651Sblueswir1@item vmware 14985824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 14995824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 15005824d651Sblueswir1card. 1501a19cbfb3SGerd Hoffmann@item qxl 1502a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1503a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1504a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 150533632788SMark Cave-Ayland@item tcx 150633632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 150733632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 150833632788SMark Cave-Aylandfixed resolution of 1024x768. 150933632788SMark Cave-Ayland@item cg3 151033632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 151133632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 151233632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1513a94f0c5cSGerd Hoffmann@item virtio 1514a94f0c5cSGerd HoffmannVirtio VGA card. 15155824d651Sblueswir1@item none 15165824d651Sblueswir1Disable VGA card. 15175824d651Sblueswir1@end table 15185824d651Sblueswir1ETEXI 15195824d651Sblueswir1 15205824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1521ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 15225824d651Sblueswir1STEXI 15235824d651Sblueswir1@item -full-screen 15246616b2adSStefan Weil@findex -full-screen 15255824d651Sblueswir1Start in full screen. 15265824d651Sblueswir1ETEXI 15275824d651Sblueswir1 15285824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1529ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1530ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 15315824d651Sblueswir1STEXI 153295d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 15336616b2adSStefan Weil@findex -g 153495d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 15355824d651Sblueswir1ETEXI 15365824d651Sblueswir1 15375824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1538f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 15395824d651Sblueswir1STEXI 15405824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 15416616b2adSStefan Weil@findex -vnc 1542dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1543dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1544dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1545dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1546dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1547a358a3afSThomas Huth(option @option{-device usb-tablet}). When using the VNC display, you 1548dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1549dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 15505824d651Sblueswir1 1551b3f046c2SKevin Wolf@table @option 15525824d651Sblueswir1 155399a9a52aSRobert Ho@item to=@var{L} 155499a9a52aSRobert Ho 155599a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 155699a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 155799a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 155899a9a52aSRobert Hoapplication. By default, to=0. 155999a9a52aSRobert Ho 15605824d651Sblueswir1@item @var{host}:@var{d} 15615824d651Sblueswir1 15625824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 15635824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 15645824d651Sblueswir1be omitted in which case the server will accept connections from any host. 15655824d651Sblueswir1 15664e257e5eSKevin Wolf@item unix:@var{path} 15675824d651Sblueswir1 15685824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 15695824d651Sblueswir1location of a unix socket to listen for connections on. 15705824d651Sblueswir1 15715824d651Sblueswir1@item none 15725824d651Sblueswir1 15735824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 15745824d651Sblueswir1can be used to later start the VNC server. 15755824d651Sblueswir1 15765824d651Sblueswir1@end table 15775824d651Sblueswir1 15785824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 15795824d651Sblueswir1separated by commas. Valid options are 15805824d651Sblueswir1 1581b3f046c2SKevin Wolf@table @option 15825824d651Sblueswir1 15835824d651Sblueswir1@item reverse 15845824d651Sblueswir1 15855824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 15865824d651Sblueswir1client is specified by the @var{display}. For reverse network 15875824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 15885824d651Sblueswir1is a TCP port number, not a display number. 15895824d651Sblueswir1 15907536ee4bSTim Hardeck@item websocket 15917536ee4bSTim Hardeck 15927536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1593275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 1594275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 1595275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 1596275e0d61SDaniel P. Berrange 1597275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 1598275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 1599275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 1600275e0d61SDaniel P. Berrange 16013e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 16023e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 16033e305e4aSDaniel P. Berrangerequires encrypted client connections. 16047536ee4bSTim Hardeck 16055824d651Sblueswir1@item password 16065824d651Sblueswir1 16075824d651Sblueswir1Require that password based authentication is used for client connections. 160886ee5bc3SMichal Novotny 160986ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 161086ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 161186ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 161286ee5bc3SMichal Novotny"vnc" or "spice". 161386ee5bc3SMichal Novotny 161486ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 161586ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 161686ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 161786ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 161886ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 161986ee5bc3SMichal Novotnydate and time). 162086ee5bc3SMichal Novotny 162186ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 162286ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 16235824d651Sblueswir1 16243e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 16253e305e4aSDaniel P. Berrange 16263e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 16273e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 16283e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 16293e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 16303e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 16313e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 16323e305e4aSDaniel P. Berrange 16335824d651Sblueswir1@item sasl 16345824d651Sblueswir1 16355824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 16365824d651Sblueswir1The exact choice of authentication method used is controlled from the 16375824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 16385824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 16395824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 16405824d651Sblueswir1to make it search alternate locations for the service config. 16415824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 16425824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 16435824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 16445824d651Sblueswir1ensures a data encryption preventing compromise of authentication 16455824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 16465824d651Sblueswir1SASL authentication. 16475824d651Sblueswir1 16485824d651Sblueswir1@item acl 16495824d651Sblueswir1 16505824d651Sblueswir1Turn on access control lists for checking of the x509 client certificate 16515824d651Sblueswir1and SASL party. For x509 certs, the ACL check is made against the 16525824d651Sblueswir1certificate's distinguished name. This is something that looks like 16535824d651Sblueswir1@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 16545824d651Sblueswir1made against the username, which depending on the SASL plugin, may 16555824d651Sblueswir1include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 16565824d651Sblueswir1When the @option{acl} flag is set, the initial access list will be 16575824d651Sblueswir1empty, with a @code{deny} policy. Thus no one will be allowed to 16585824d651Sblueswir1use the VNC server until the ACLs have been loaded. This can be 16595824d651Sblueswir1achieved using the @code{acl} monitor command. 16605824d651Sblueswir1 16616f9c78c1SCorentin Chary@item lossy 16626f9c78c1SCorentin Chary 16636f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 16646f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 16656f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 16666f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 16676f9c78c1SCorentin Chary 166880e0c8c3SCorentin Chary@item non-adaptive 166980e0c8c3SCorentin Chary 167080e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 167180e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 167280e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 167361cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 16749d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 167580e0c8c3SCorentin Charylike Tight. 167680e0c8c3SCorentin Chary 16778cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 16788cf36489SGerd Hoffmann 16798cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 16808cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 16818cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 16828cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 16838cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 16848cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 16858cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 16868cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 16878cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 1688b65ee4faSStefan Weilspec but is traditional QEMU behavior. 16898cf36489SGerd Hoffmann 1690c5ce8333SGerd Hoffmann@item key-delay-ms 1691c5ce8333SGerd Hoffmann 1692c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 1693d3b0db6dSAlexander GrafDefault is 10. Keyboards are low-bandwidth devices, so this slowdown 1694c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 1695c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 1696c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 1697c5ce8333SGerd Hoffmann 16985824d651Sblueswir1@end table 16995824d651Sblueswir1ETEXI 17005824d651Sblueswir1 17015824d651Sblueswir1STEXI 17025824d651Sblueswir1@end table 17035824d651Sblueswir1ETEXI 1704a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 17055824d651Sblueswir1 1706de6b4f90SMarkus ArmbrusterARCHHEADING(i386 target only:, QEMU_ARCH_I386) 17075824d651Sblueswir1STEXI 17085824d651Sblueswir1@table @option 17095824d651Sblueswir1ETEXI 17105824d651Sblueswir1 17115824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1712ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1713ad96090aSBlue Swirl QEMU_ARCH_I386) 17145824d651Sblueswir1STEXI 17155824d651Sblueswir1@item -win2k-hack 17166616b2adSStefan Weil@findex -win2k-hack 17175824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 17185824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 17195824d651Sblueswir1slows down the IDE transfers). 17205824d651Sblueswir1ETEXI 17215824d651Sblueswir1 17225824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1723ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1724ad96090aSBlue Swirl QEMU_ARCH_I386) 17255824d651Sblueswir1STEXI 17265824d651Sblueswir1@item -no-fd-bootchk 17276616b2adSStefan Weil@findex -no-fd-bootchk 17284eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 17295824d651Sblueswir1be needed to boot from old floppy disks. 17305824d651Sblueswir1ETEXI 17315824d651Sblueswir1 17325824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1733f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 17345824d651Sblueswir1STEXI 17355824d651Sblueswir1@item -no-acpi 17366616b2adSStefan Weil@findex -no-acpi 17375824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 17385824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 17395824d651Sblueswir1only). 17405824d651Sblueswir1ETEXI 17415824d651Sblueswir1 17425824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1743ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 17445824d651Sblueswir1STEXI 17455824d651Sblueswir1@item -no-hpet 17466616b2adSStefan Weil@findex -no-hpet 17475824d651Sblueswir1Disable HPET support. 17485824d651Sblueswir1ETEXI 17495824d651Sblueswir1 17505824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1751104bf02eSMichael 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" 1752ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 17535824d651Sblueswir1STEXI 17545824d651Sblueswir1@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}]...] 17556616b2adSStefan Weil@findex -acpitable 17565824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 1757104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 1758104bf02eSMichael TokarevACPI headers (possible overridden by other options). 1759104bf02eSMichael TokarevFor data=, only data 1760104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 1761104bf02eSMichael Tokarevcommand line. 1762ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 1763ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 1764ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 1765ae123749SLaszlo Ersekspec. 17665824d651Sblueswir1ETEXI 17675824d651Sblueswir1 1768b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1769b6f6e3d3Saliguori "-smbios file=binary\n" 1770ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 1771b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1772b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 1773ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 1774b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1775b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 1776b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 1777b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1778b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 1779b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 1780b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1781b155eb1dSGabriel L. Somlo " [,sku=str]\n" 1782b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 1783b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1784b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 1785b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 1786b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 17873ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 1788b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 1789c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1790b6f6e3d3SaliguoriSTEXI 1791b6f6e3d3Saliguori@item -smbios file=@var{binary} 17926616b2adSStefan Weil@findex -smbios 1793b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 1794b6f6e3d3Saliguori 179584351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1796b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 1797b6f6e3d3Saliguori 1798b6f6e3d3Saliguori@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}] 1799b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 1800b155eb1dSGabriel L. Somlo 1801b155eb1dSGabriel L. Somlo@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}] 1802b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 1803b155eb1dSGabriel L. Somlo 1804b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1805b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 1806b155eb1dSGabriel L. Somlo 1807b155eb1dSGabriel 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}] 1808b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 1809b155eb1dSGabriel L. Somlo 18103ebd6cc8SGabriel 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}] 1811b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 1812b6f6e3d3SaliguoriETEXI 1813b6f6e3d3Saliguori 18145824d651Sblueswir1STEXI 18155824d651Sblueswir1@end table 18165824d651Sblueswir1ETEXI 1817c70a01e4SMarkus ArmbrusterDEFHEADING() 18185824d651Sblueswir1 1819de6b4f90SMarkus ArmbrusterDEFHEADING(Network options:) 18205824d651Sblueswir1STEXI 18215824d651Sblueswir1@table @option 18225824d651Sblueswir1ETEXI 18235824d651Sblueswir1 18246a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 18255824d651Sblueswir1#ifdef CONFIG_SLIRP 18260b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 18270b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 18280b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 1829f18d1375SBenjamin Drung " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 18300fca92b9SFam Zheng " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1831ad196a9dSJan Kiszka#ifndef _WIN32 1832c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 1833ad196a9dSJan Kiszka#endif 18346a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 18356a8b4a5bSThomas Huth " its DHCP server and optional services\n" 18365824d651Sblueswir1#endif 18375824d651Sblueswir1#ifdef _WIN32 18386a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 18396a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 18405824d651Sblueswir1#else 18416a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 1842584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 18436a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 184469e87b32SJason Wang " [,poll-us=n]\n" 18456a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 1846584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 1847a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1848a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1849a7c36ee4SCorey Bryant " to deconfigure it\n" 1850ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 1851a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1852a7c36ee4SCorey Bryant " configure it\n" 18535824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 18542ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1855ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1856f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1857ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1858ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 185982b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 18605430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 18615430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 186282b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 18632ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1864ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 186569e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 186669e87b32SJason Wang " spent on busy polling for vhost net\n" 18676a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 18686a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 18696a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 18706a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 18710df0ff6dSMark McLoughlin#endif 18723fb69aa1SAnton Ivanov#ifdef __linux__ 18736a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 18746a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 18756a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 18766a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 18776a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 18786a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 18793fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 18802f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 18813fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 18823fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 18833fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 18843fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 18853fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 18863fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 18873952651aSGonglei " use 'srcport=' to specify source udp port\n" 18883fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 18893fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 18903fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 18913fb69aa1SAnton Ivanov " well as a weak security measure\n" 18923fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 18933fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 18943fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 18953fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 18963fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 18973fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 18983fb69aa1SAnton Ivanov#endif 18996a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 19006a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 19016a8b4a5bSThomas Huth " using a socket connection\n" 19026a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 19036a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 19043a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 19056a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 19066a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 19076a8b4a5bSThomas Huth " using an UDP tunnel\n" 19085824d651Sblueswir1#ifdef CONFIG_VDE 19096a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 19106a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 19116a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 19125824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 19135824d651Sblueswir1 " ownership and permissions for communication port.\n" 19145824d651Sblueswir1#endif 191558952137SVincenzo Maffione#ifdef CONFIG_NETMAP 19166a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 191758952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 191858952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 191958952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 192058952137SVincenzo Maffione#endif 1921253dc14cSThomas Huth#ifdef CONFIG_POSIX 19226a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 19236a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 1924253dc14cSThomas Huth#endif 192518d65d22SThomas Huth "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 1926af1a5c3eSThomas Huth " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 192778cd6f7bSThomas HuthDEF("nic", HAS_ARG, QEMU_OPTION_nic, 1928dfaa7d50SBALATON Zoltan "-nic [tap|bridge|" 192978cd6f7bSThomas Huth#ifdef CONFIG_SLIRP 193078cd6f7bSThomas Huth "user|" 193178cd6f7bSThomas Huth#endif 193278cd6f7bSThomas Huth#ifdef __linux__ 193378cd6f7bSThomas Huth "l2tpv3|" 193478cd6f7bSThomas Huth#endif 193578cd6f7bSThomas Huth#ifdef CONFIG_VDE 193678cd6f7bSThomas Huth "vde|" 193778cd6f7bSThomas Huth#endif 193878cd6f7bSThomas Huth#ifdef CONFIG_NETMAP 193978cd6f7bSThomas Huth "netmap|" 194078cd6f7bSThomas Huth#endif 194178cd6f7bSThomas Huth#ifdef CONFIG_POSIX 194278cd6f7bSThomas Huth "vhost-user|" 194378cd6f7bSThomas Huth#endif 194478cd6f7bSThomas Huth "socket][,option][,...][mac=macaddr]\n" 194578cd6f7bSThomas Huth " initialize an on-board / default host NIC (using MAC address\n" 194678cd6f7bSThomas Huth " macaddr) and connect it to the given host network backend\n" 1947dfaa7d50SBALATON Zoltan "-nic none use it alone to have zero network devices (the default is to\n" 194878cd6f7bSThomas Huth " provided a 'user' network connection)\n", 194978cd6f7bSThomas Huth QEMU_ARCH_ALL) 19506a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 1951af1a5c3eSThomas Huth "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 19520e60a82dSThomas Huth " configure or create an on-board (or machine default) NIC and\n" 1953af1a5c3eSThomas Huth " connect it to hub 0 (please use -nic unless you need a hub)\n" 19546a8b4a5bSThomas Huth "-net [" 1955a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 1956a1ea458fSMark McLoughlin "user|" 1957a1ea458fSMark McLoughlin#endif 1958a1ea458fSMark McLoughlin "tap|" 1959a7c36ee4SCorey Bryant "bridge|" 1960a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 1961a1ea458fSMark McLoughlin "vde|" 1962a1ea458fSMark McLoughlin#endif 196358952137SVincenzo Maffione#ifdef CONFIG_NETMAP 196458952137SVincenzo Maffione "netmap|" 196558952137SVincenzo Maffione#endif 1966af1a5c3eSThomas Huth "socket][,option][,option][,...]\n" 19676a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 19686a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 19695824d651Sblueswir1STEXI 1970abbbb035SThomas Huth@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 1971abbbb035SThomas Huth@findex -nic 1972abbbb035SThomas HuthThis option is a shortcut for configuring both the on-board (default) guest 1973abbbb035SThomas HuthNIC hardware and the host network backend in one go. The host backend options 1974abbbb035SThomas Huthare the same as with the corresponding @option{-netdev} options below. 1975abbbb035SThomas HuthThe guest NIC model can be set with @option{model=@var{modelname}}. 1976abbbb035SThomas HuthUse @option{model=help} to list the available device types. 1977abbbb035SThomas HuthThe hardware MAC address can be set with @option{mac=@var{macaddr}}. 1978abbbb035SThomas Huth 1979abbbb035SThomas HuthThe following two example do exactly the same, to show how @option{-nic} can 1980abbbb035SThomas Huthbe used to shorten the command line length (note that the e1000 is the default 1981abbbb035SThomas Huthon i386, so the @option{model=e1000} parameter could even be omitted here, too): 1982abbbb035SThomas Huth@example 1983abbbb035SThomas Huthqemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 1984abbbb035SThomas Huthqemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 1985abbbb035SThomas Huth@end example 1986abbbb035SThomas Huth 1987abbbb035SThomas Huth@item -nic none 1988abbbb035SThomas HuthIndicate that no network devices should be configured. It is used to override 1989abbbb035SThomas Huththe default configuration (default NIC with ``user'' host network backend) 1990abbbb035SThomas Huthwhich is activated if no other networking options are provided. 19915824d651Sblueswir1 199208d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1993b8f490ebSMarkus Armbruster@findex -netdev 1994abbbb035SThomas HuthConfigure user mode host network backend which requires no administrator 1995ad196a9dSJan Kiszkaprivilege to run. Valid options are: 19965824d651Sblueswir1 1997b3f046c2SKevin Wolf@table @option 199808d12022SStefan Hajnoczi@item id=@var{id} 1999ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 2000ad196a9dSJan Kiszka 2001abbbb035SThomas Huth@item ipv4=on|off and ipv6=on|off 2002abbbb035SThomas HuthSpecify that either IPv4 or IPv6 must be enabled. If neither is specified 2003abbbb035SThomas Huthboth protocols are enabled. 20040b11c036SSamuel Thibault 2005c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 2006c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 2007c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 2008b0b36e5dSBrad Hards10.0.2.0/24. 2009c92ef6a2SJan Kiszka 2010c92ef6a2SJan Kiszka@item host=@var{addr} 2011c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 2012c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 2013ad196a9dSJan Kiszka 2014d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 2015d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 2016d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 2017d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 2018d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 20197aac531eSYann Bordenave 2020d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 20217aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 20227aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 20237aac531eSYann Bordenave 2024c54ed5bcSJan Kiszka@item restrict=on|off 2025caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 2026ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 2027caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 2028ad196a9dSJan Kiszka 2029ad196a9dSJan Kiszka@item hostname=@var{name} 203063d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 2031ad196a9dSJan Kiszka 2032c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 2033c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 2034b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2035c92ef6a2SJan Kiszka 2036c92ef6a2SJan Kiszka@item dns=@var{addr} 2037c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 2038c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 2039c92ef6a2SJan Kiszkai.e. x.x.x.3. 2040c92ef6a2SJan Kiszka 2041d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 20427aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 20437aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 20447aac531eSYann Bordenavenetwork, i.e. xxxx::3. 20457aac531eSYann Bordenave 204663d2960bSKlaus Stengel@item dnssearch=@var{domain} 204763d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 204863d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 204963d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 205063d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 205163d2960bSKlaus Stengelcan not be resolved. 205263d2960bSKlaus Stengel 205363d2960bSKlaus StengelExample: 205463d2960bSKlaus Stengel@example 2055abbbb035SThomas Huthqemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 205663d2960bSKlaus Stengel@end example 205763d2960bSKlaus Stengel 2058f18d1375SBenjamin Drung@item domainname=@var{domain} 2059f18d1375SBenjamin DrungSpecifies the client domain name reported by the built-in DHCP server. 2060f18d1375SBenjamin Drung 2061ad196a9dSJan Kiszka@item tftp=@var{dir} 2062ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 2063ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 2064ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 2065c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 2066ad196a9dSJan Kiszka 20670fca92b9SFam Zheng@item tftp-server-name=@var{name} 20680fca92b9SFam ZhengIn BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option 20690fca92b9SFam Zheng66). This can be used to advise the guest to load boot files or configurations 20700fca92b9SFam Zhengfrom a different server than the host address. 20710fca92b9SFam Zheng 2072ad196a9dSJan Kiszka@item bootfile=@var{file} 2073ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 2074ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 2075ad196a9dSJan Kiszkaa guest from a local directory. 2076ad196a9dSJan Kiszka 2077ad196a9dSJan KiszkaExample (using pxelinux): 2078ad196a9dSJan Kiszka@example 2079abbbb035SThomas Huthqemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \ 2080abbbb035SThomas Huth -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2081ad196a9dSJan Kiszka@end example 2082ad196a9dSJan Kiszka 2083c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 2084ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 2085ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 2086c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 2087c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 2088ad196a9dSJan Kiszka 2089ad196a9dSJan KiszkaIn the guest Windows OS, the line: 2090ad196a9dSJan Kiszka@example 2091ad196a9dSJan Kiszka10.0.2.4 smbserver 2092ad196a9dSJan Kiszka@end example 2093ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2094ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2095ad196a9dSJan Kiszka 2096ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2097ad196a9dSJan Kiszka 2098e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 2099ad196a9dSJan Kiszka 21003c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2101c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 2102c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 2103c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 21043c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 21053c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 2106c92ef6a2SJan Kiszkaused. This option can be given multiple times. 2107ad196a9dSJan Kiszka 2108ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 2109ad196a9dSJan Kiszkascreen 0, use the following: 2110ad196a9dSJan Kiszka 2111ad196a9dSJan Kiszka@example 2112ad196a9dSJan Kiszka# on the host 2113abbbb035SThomas Huthqemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 2114ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 2115ad196a9dSJan Kiszkaxterm -display :1 2116ad196a9dSJan Kiszka@end example 2117ad196a9dSJan Kiszka 2118ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 2119ad196a9dSJan Kiszkathe guest, use the following: 2120ad196a9dSJan Kiszka 2121ad196a9dSJan Kiszka@example 2122ad196a9dSJan Kiszka# on the host 2123abbbb035SThomas Huthqemu-system-i386 -nic user,hostfwd=tcp::5555-:23 2124ad196a9dSJan Kiszkatelnet localhost 5555 2125ad196a9dSJan Kiszka@end example 2126ad196a9dSJan Kiszka 2127ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 2128ad196a9dSJan Kiszkaconnect to the guest telnet server. 2129ad196a9dSJan Kiszka 2130c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2131f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 21323c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 2133b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 2134b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 2135b412eb61SAlexander Graf 213643ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 2137b412eb61SAlexander Graflifetime, like in the following example: 2138b412eb61SAlexander Graf 2139b412eb61SAlexander Graf@example 2140b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2141b412eb61SAlexander Graf# the guest accesses it 2142abbbb035SThomas Huthqemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 2143b412eb61SAlexander Graf@end example 2144b412eb61SAlexander Graf 2145b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 214643ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 2147b412eb61SAlexander Graf 2148b412eb61SAlexander Graf@example 2149b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2150b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 2151abbbb035SThomas Huthqemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2152b412eb61SAlexander Graf@end example 2153ad196a9dSJan Kiszka 2154ad196a9dSJan Kiszka@end table 2155ad196a9dSJan Kiszka 2156584613eaSAlexey 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}] 2157abbbb035SThomas HuthConfigure a host TAP network backend with ID @var{id}. 2158a7c36ee4SCorey Bryant 2159a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 21605824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2161a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 2162a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 2163a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2164a7c36ee4SCorey Bryantto disable script execution. 2165a7c36ee4SCorey Bryant 2166a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 2167584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 2168584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 2169584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 2170a7c36ee4SCorey Bryant 2171a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 2172a7c36ee4SCorey Bryantopened host TAP interface. 2173a7c36ee4SCorey Bryant 2174a7c36ee4SCorey BryantExamples: 21755824d651Sblueswir1 21765824d651Sblueswir1@example 2177a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 2178abbbb035SThomas Huthqemu-system-i386 linux.img -nic tap 21795824d651Sblueswir1@end example 21805824d651Sblueswir1 21815824d651Sblueswir1@example 2182a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 2183a7c36ee4SCorey Bryant#to a TAP device 21843804da9dSStefan Weilqemu-system-i386 linux.img \ 218574f78b99SThomas Huth -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 218674f78b99SThomas Huth -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 21875824d651Sblueswir1@end example 21885824d651Sblueswir1 2189a7c36ee4SCorey Bryant@example 2190a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2191a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2192abbbb035SThomas Huthqemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \ 2193abbbb035SThomas Huth -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 2194a7c36ee4SCorey Bryant@end example 2195a7c36ee4SCorey Bryant 219608d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2197a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 2198a7c36ee4SCorey Bryant 2199a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 2200a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 2201420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 2202a7c36ee4SCorey Bryantdevice is @file{br0}. 2203a7c36ee4SCorey Bryant 2204a7c36ee4SCorey BryantExamples: 2205a7c36ee4SCorey Bryant 2206a7c36ee4SCorey Bryant@example 2207a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2208a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2209abbbb035SThomas Huthqemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 2210a7c36ee4SCorey Bryant@end example 2211a7c36ee4SCorey Bryant 2212a7c36ee4SCorey Bryant@example 2213a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2214a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 2215abbbb035SThomas Huthqemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 2216a7c36ee4SCorey Bryant@end example 2217a7c36ee4SCorey Bryant 221808d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 22195824d651Sblueswir1 2220abbbb035SThomas HuthThis host network backend can be used to connect the guest's network to 2221abbbb035SThomas Huthanother QEMU virtual machine using a TCP socket connection. If @option{listen} 2222abbbb035SThomas Huthis specified, QEMU waits for incoming connections on @var{port} 22235824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 22245824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 22255824d651Sblueswir1specifies an already opened TCP socket. 22265824d651Sblueswir1 22275824d651Sblueswir1Example: 22285824d651Sblueswir1@example 22295824d651Sblueswir1# launch a first QEMU instance 22303804da9dSStefan Weilqemu-system-i386 linux.img \ 2231abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2232abbbb035SThomas Huth -netdev socket,id=n1,listen=:1234 2233abbbb035SThomas Huth# connect the network of this instance to the network of the first instance 22343804da9dSStefan Weilqemu-system-i386 linux.img \ 2235abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2236abbbb035SThomas Huth -netdev socket,id=n2,connect=127.0.0.1:1234 22375824d651Sblueswir1@end example 22385824d651Sblueswir1 223908d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 22405824d651Sblueswir1 2241abbbb035SThomas HuthConfigure a socket host network backend to share the guest's network traffic 2242abbbb035SThomas Huthwith another QEMU virtual machines using a UDP multicast socket, effectively 2243abbbb035SThomas Huthmaking a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 22445824d651Sblueswir1NOTES: 22455824d651Sblueswir1@enumerate 22465824d651Sblueswir1@item 22475824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 22485824d651Sblueswir1correct multicast setup for these hosts). 22495824d651Sblueswir1@item 22505824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 22515824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 22525824d651Sblueswir1@item 22535824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 22545824d651Sblueswir1@end enumerate 22555824d651Sblueswir1 22565824d651Sblueswir1Example: 22575824d651Sblueswir1@example 22585824d651Sblueswir1# launch one QEMU instance 22593804da9dSStefan Weilqemu-system-i386 linux.img \ 2260abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2261abbbb035SThomas Huth -netdev socket,id=n1,mcast=230.0.0.1:1234 22625824d651Sblueswir1# launch another QEMU instance on same "bus" 22633804da9dSStefan Weilqemu-system-i386 linux.img \ 2264abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2265abbbb035SThomas Huth -netdev socket,id=n2,mcast=230.0.0.1:1234 22665824d651Sblueswir1# launch yet another QEMU instance on same "bus" 22673804da9dSStefan Weilqemu-system-i386 linux.img \ 226837a4442aSThomas Huth -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 2269abbbb035SThomas Huth -netdev socket,id=n3,mcast=230.0.0.1:1234 22705824d651Sblueswir1@end example 22715824d651Sblueswir1 22725824d651Sblueswir1Example (User Mode Linux compat.): 22735824d651Sblueswir1@example 2274abbbb035SThomas Huth# launch QEMU instance (note mcast address selected is UML's default) 22753804da9dSStefan Weilqemu-system-i386 linux.img \ 2276abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2277abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102 22785824d651Sblueswir1# launch UML 22795824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 22805824d651Sblueswir1@end example 22815824d651Sblueswir1 22823a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 22833a75e74cSMike Ryan@example 22843804da9dSStefan Weilqemu-system-i386 linux.img \ 2285abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2286abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 22873a75e74cSMike Ryan@end example 22883a75e74cSMike Ryan 22893fb69aa1SAnton 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}] 2290abbbb035SThomas HuthConfigure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a 2291abbbb035SThomas Huthpopular protocol to transport Ethernet (and other Layer 2) data frames between 22923fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 22933fb69aa1SAnton Ivanov(from version 3.3 onwards). 22943fb69aa1SAnton Ivanov 22953fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 22963fb69aa1SAnton Ivanov 22971e9a7379SMarkus Armbruster@table @option 22983fb69aa1SAnton Ivanov@item src=@var{srcaddr} 22993fb69aa1SAnton Ivanov source address (mandatory) 23003fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 23013fb69aa1SAnton Ivanov destination address (mandatory) 23023fb69aa1SAnton Ivanov@item udp 23033fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 23043fb69aa1SAnton Ivanov@item srcport=@var{srcport} 23053fb69aa1SAnton Ivanov source udp port. 23063fb69aa1SAnton Ivanov@item dstport=@var{dstport} 23073fb69aa1SAnton Ivanov destination udp port. 23083fb69aa1SAnton Ivanov@item ipv6 23093fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 23103fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2311f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 23123fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 23133fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 23143fb69aa1SAnton Ivanovbit. 23153fb69aa1SAnton Ivanov@item cookie64 23163fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 23173fb69aa1SAnton Ivanov@item counter=off 23183fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 23193fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 23203fb69aa1SAnton Ivanov@item pincounter=on 23213fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 23223fb69aa1SAnton Ivanovnetworks which have packet reorder. 23233fb69aa1SAnton Ivanov@item offset=@var{offset} 23243fb69aa1SAnton Ivanov Add an extra offset between header and data 23251e9a7379SMarkus Armbruster@end table 23263fb69aa1SAnton Ivanov 23273fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 23283fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 23293fb69aa1SAnton Ivanov@example 23303fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 23313fb69aa1SAnton Ivanov# on 1.2.3.4 23323fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 23333fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 23343fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 23353fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 23363fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 23373fb69aa1SAnton Ivanovifconfig vmtunnel0 up 23383fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 23393fb69aa1SAnton Ivanov 23403fb69aa1SAnton Ivanov 23413fb69aa1SAnton Ivanov# on 4.3.2.1 23423fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 23433fb69aa1SAnton Ivanov 2344abbbb035SThomas Huthqemu-system-i386 linux.img -device e1000,netdev=n1 \ 2345abbbb035SThomas 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 23463fb69aa1SAnton Ivanov 23473fb69aa1SAnton Ivanov@end example 23483fb69aa1SAnton Ivanov 234908d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2350abbbb035SThomas HuthConfigure VDE backend to connect to PORT @var{n} of a vde switch running on host and 23515824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 23525824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2353c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 23545824d651Sblueswir1with vde support enabled. 23555824d651Sblueswir1 23565824d651Sblueswir1Example: 23575824d651Sblueswir1@example 23585824d651Sblueswir1# launch vde switch 23595824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 23605824d651Sblueswir1# launch QEMU instance 2361abbbb035SThomas Huthqemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch 23625824d651Sblueswir1@end example 23635824d651Sblueswir1 2364b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 236503ce5744SNikolay Nikolaev 236603ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 236703ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 236803ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 236903ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2370b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2371b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 237203ce5744SNikolay Nikolaev 237303ce5744SNikolay NikolaevExample: 237403ce5744SNikolay Nikolaev@example 237503ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 237603ce5744SNikolay Nikolaev -numa node,memdev=mem \ 237779cad2faSVincenzo Maffione -chardev socket,id=chr0,path=/path/to/socket \ 237803ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 237903ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 238003ce5744SNikolay Nikolaev@end example 238103ce5744SNikolay Nikolaev 2382abbbb035SThomas Huth@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 238378cd6f7bSThomas Huth 2384abbbb035SThomas HuthCreate a hub port on the emulated hub with ID @var{hubid}. 238578cd6f7bSThomas Huth 2386abbbb035SThomas HuthThe hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 2387af1a5c3eSThomas Huthsingle netdev. Alternatively, you can also connect the hubport to another 2388af1a5c3eSThomas Huthnetdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 2389abbbb035SThomas Huth 2390af1a5c3eSThomas Huth@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 2391abbbb035SThomas Huth@findex -net 2392abbbb035SThomas HuthLegacy option to configure or create an on-board (or machine default) Network 2393af1a5c3eSThomas HuthInterface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 2394af1a5c3eSThomas Huththe default hub), or to the netdev @var{nd}. 2395abbbb035SThomas HuthThe NIC is an e1000 by default on the PC target. Optionally, the MAC address 2396abbbb035SThomas Huthcan be changed to @var{mac}, the device address set to @var{addr} (PCI cards 2397abbbb035SThomas Huthonly), and a @var{name} can be assigned for use in monitor commands. 2398abbbb035SThomas HuthOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2399abbbb035SThomas Huththat the card should have; this option currently only affects virtio cards; set 2400abbbb035SThomas Huth@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2401abbbb035SThomas HuthNIC is created. QEMU can emulate several different models of network card. 2402abbbb035SThomas HuthUse @code{-net nic,model=help} for a list of available devices for your target. 2403abbbb035SThomas Huth 2404af1a5c3eSThomas Huth@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 2405abbbb035SThomas HuthConfigure a host network backend (with the options corresponding to the same 2406af1a5c3eSThomas Huth@option{-netdev} option) and connect it to the emulated hub 0 (the default 2407af1a5c3eSThomas Huthhub). Use @var{name} to specify the name of the hub port. 24085824d651Sblueswir1ETEXI 24095824d651Sblueswir1 2410c70a01e4SMarkus ArmbrusterSTEXI 2411c70a01e4SMarkus Armbruster@end table 2412c70a01e4SMarkus ArmbrusterETEXI 24137273a2dbSMatthew BoothDEFHEADING() 24147273a2dbSMatthew Booth 2415de6b4f90SMarkus ArmbrusterDEFHEADING(Character device options:) 24167273a2dbSMatthew Booth 24177273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2418517b3d40SLin Ma "-chardev help\n" 2419d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24205dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2421981b06e7SJulia Suvorova " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n" 2422a8fb5427SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n" 2423981b06e7SJulia Suvorova "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n" 2424d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 24257273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 242697331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2427d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2428d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24297273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2430d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2431d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2432d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2433d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24347273a2dbSMatthew Booth#ifdef _WIN32 2435d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2436d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24377273a2dbSMatthew Booth#else 2438d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2439d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 24407273a2dbSMatthew Booth#endif 24417273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2442d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24437273a2dbSMatthew Booth#endif 24447273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 24457273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2446d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2447d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24487273a2dbSMatthew Booth#endif 24497273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2450d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2451d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24527273a2dbSMatthew Booth#endif 2453cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2454d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2455d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2456cbcc6336SAlon Levy#endif 2457ad96090aSBlue Swirl , QEMU_ARCH_ALL 24587273a2dbSMatthew Booth) 24597273a2dbSMatthew Booth 24607273a2dbSMatthew BoothSTEXI 2461dddba068SMarkus Armbruster 2462dddba068SMarkus ArmbrusterThe general form of a character device option is: 2463dddba068SMarkus Armbruster@table @option 246497331287SJan Kiszka@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 24656616b2adSStefan Weil@findex -chardev 24667273a2dbSMatthew BoothBackend is one of: 24677273a2dbSMatthew Booth@option{null}, 24687273a2dbSMatthew Booth@option{socket}, 24697273a2dbSMatthew Booth@option{udp}, 24707273a2dbSMatthew Booth@option{msmouse}, 24717273a2dbSMatthew Booth@option{vc}, 24724f57378fSMarkus Armbruster@option{ringbuf}, 24737273a2dbSMatthew Booth@option{file}, 24747273a2dbSMatthew Booth@option{pipe}, 24757273a2dbSMatthew Booth@option{console}, 24767273a2dbSMatthew Booth@option{serial}, 24777273a2dbSMatthew Booth@option{pty}, 24787273a2dbSMatthew Booth@option{stdio}, 24797273a2dbSMatthew Booth@option{braille}, 24807273a2dbSMatthew Booth@option{tty}, 248188a946d3SGerd Hoffmann@option{parallel}, 2482cbcc6336SAlon Levy@option{parport}, 248316fdc56aSThomas Huth@option{spicevmc}, 24845a49d3e9SMarc-André Lureau@option{spiceport}. 24857273a2dbSMatthew BoothThe specific backend will determine the applicable options. 24867273a2dbSMatthew Booth 2487dddba068SMarkus ArmbrusterUse @code{-chardev help} to print all available chardev backend types. 2488517b3d40SLin Ma 24897273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 24907273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 24917273a2dbSMatthew Booth 249297331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2493a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2494a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2495a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2496a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2497a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2498a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2499a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2500a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2501a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2502a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2503a40db1b3SPeter Maydell 2504a40db1b3SPeter Maydell@example 2505a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2506bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2507a40db1b3SPeter Maydell-serial chardev:char0 \ 2508a40db1b3SPeter Maydell-serial chardev:char0 2509a40db1b3SPeter Maydell@end example 2510a40db1b3SPeter Maydell 2511a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2512a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2513a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2514a40db1b3SPeter Maydell 2515a40db1b3SPeter Maydell@example 2516a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2517bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2518a40db1b3SPeter Maydell-parallel chardev:char0 \ 2519a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2520a40db1b3SPeter Maydell-serial chardev:char1 \ 2521a40db1b3SPeter Maydell-serial chardev:char1 2522a40db1b3SPeter Maydell@end example 2523a40db1b3SPeter Maydell 2524a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2525a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2526a40db1b3SPeter Maydellmultiplexer}. 2527a40db1b3SPeter Maydell 2528a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2529a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2530a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2531a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2532a40db1b3SPeter Maydellstdio. 2533a40db1b3SPeter Maydell 2534a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2535a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 253697331287SJan Kiszka 2537d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2538d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2539d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2540d0d7708bSDaniel P. Berrangeopened. 2541d0d7708bSDaniel P. Berrange 2542dddba068SMarkus Armbruster@end table 25437273a2dbSMatthew Booth 2544dddba068SMarkus ArmbrusterThe available backends are: 2545dddba068SMarkus Armbruster 2546dddba068SMarkus Armbruster@table @option 25477273a2dbSMatthew Booth@item -chardev null,id=@var{id} 25487273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 25497273a2dbSMatthew Boothreceives. The null backend does not take any options. 25507273a2dbSMatthew Booth 2551981b06e7SJulia Suvorova@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}] 25527273a2dbSMatthew Booth 25537273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 25547273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 25557273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 25567273a2dbSMatthew Booth 25577273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 25587273a2dbSMatthew Booth 25597273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 25607273a2dbSMatthew Boothconnect to a listening socket. 25617273a2dbSMatthew Booth 25627273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 25637273a2dbSMatthew Boothescape sequences. 25647273a2dbSMatthew Booth 2565981b06e7SJulia Suvorova@option{websocket} specifies that the socket uses WebSocket protocol for 2566981b06e7SJulia Suvorovacommunication. 2567981b06e7SJulia Suvorova 25685dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 25695dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 25705dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 25715dd1f02bSCorey Minyard 2572a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2573a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2574a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2575a8fb5427SDaniel P. Berrangeargument. 2576a8fb5427SDaniel P. Berrange 25777273a2dbSMatthew BoothTCP and unix socket options are given below: 25787273a2dbSMatthew Booth 25797273a2dbSMatthew Booth@table @option 25807273a2dbSMatthew Booth 25818d533561SAurelien Jarno@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 25827273a2dbSMatthew Booth 25837273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 25847273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 25857273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 25867273a2dbSMatthew Booth 25877273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 25887273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 25897273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 25907273a2dbSMatthew Booth@option{port} is required. 25917273a2dbSMatthew Booth 25927273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 25937273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 25947273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 25957273a2dbSMatthew Boothas a port number. 25967273a2dbSMatthew Booth 25977273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 25987273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 25997273a2dbSMatthew Booth 26007273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 26017273a2dbSMatthew Booth 26027273a2dbSMatthew Booth@item unix options: path=@var{path} 26037273a2dbSMatthew Booth 26047273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 26057273a2dbSMatthew Boothrequired. 26067273a2dbSMatthew Booth 26077273a2dbSMatthew Booth@end table 26087273a2dbSMatthew Booth 26097273a2dbSMatthew Booth@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 26107273a2dbSMatthew Booth 26117273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 26127273a2dbSMatthew Booth 26137273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 26147273a2dbSMatthew Boothdefaults to @code{localhost}. 26157273a2dbSMatthew Booth 26167273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 26177273a2dbSMatthew Boothis required. 26187273a2dbSMatthew Booth 26197273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 26207273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 26217273a2dbSMatthew Booth 26227273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 26237273a2dbSMatthew Boothavailable local port will be used. 26247273a2dbSMatthew Booth 26257273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 26267273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 26277273a2dbSMatthew Booth 26287273a2dbSMatthew Booth@item -chardev msmouse,id=@var{id} 26297273a2dbSMatthew Booth 26307273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 26317273a2dbSMatthew Boothtake any options. 26327273a2dbSMatthew Booth 26337273a2dbSMatthew Booth@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 26347273a2dbSMatthew Booth 26357273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 26367273a2dbSMatthew Boothsize. 26377273a2dbSMatthew Booth 26387273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 26397273a2dbSMatthew Booththe console, in pixels. 26407273a2dbSMatthew Booth 26417273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 26427273a2dbSMatthew Boothconsole with the given dimensions. 26437273a2dbSMatthew Booth 26444f57378fSMarkus Armbruster@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 264551767e7cSLei Li 26463949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 2647e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 264851767e7cSLei Li 26497273a2dbSMatthew Booth@item -chardev file,id=@var{id},path=@var{path} 26507273a2dbSMatthew Booth 26517273a2dbSMatthew BoothLog all traffic received from the guest to a file. 26527273a2dbSMatthew Booth 26537273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 26547273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 26557273a2dbSMatthew Boothis required. 26567273a2dbSMatthew Booth 26577273a2dbSMatthew Booth@item -chardev pipe,id=@var{id},path=@var{path} 26587273a2dbSMatthew Booth 26597273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 26607273a2dbSMatthew BoothWindows hosts and other hosts: 26617273a2dbSMatthew Booth 26627273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 26637273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 26647273a2dbSMatthew Booth 26657273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 26667273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 26677273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 26687273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 26697273a2dbSMatthew Boothbe present. 26707273a2dbSMatthew Booth 26717273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 26727273a2dbSMatthew Boothrequired. 26737273a2dbSMatthew Booth 26747273a2dbSMatthew Booth@item -chardev console,id=@var{id} 26757273a2dbSMatthew Booth 26767273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 26777273a2dbSMatthew Boothtake any options. 26787273a2dbSMatthew Booth 26797273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 26807273a2dbSMatthew Booth 26817273a2dbSMatthew Booth@item -chardev serial,id=@var{id},path=@option{path} 26827273a2dbSMatthew Booth 26837273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 26847273a2dbSMatthew Booth 2685d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 2686d59044efSGerd Hoffmannnot only serial lines. 26877273a2dbSMatthew Booth 26887273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 26897273a2dbSMatthew Booth 26907273a2dbSMatthew Booth@item -chardev pty,id=@var{id} 26917273a2dbSMatthew Booth 26927273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 26937273a2dbSMatthew Boothnot take any options. 26947273a2dbSMatthew Booth 26957273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 26967273a2dbSMatthew Booth 2697b7fdb3abSAurelien Jarno@item -chardev stdio,id=@var{id}[,signal=on|off] 2698b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 2699b7fdb3abSAurelien Jarno 2700b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 2701b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2702b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 2703b7fdb3abSAurelien Jarno 27047273a2dbSMatthew Booth@item -chardev braille,id=@var{id} 27057273a2dbSMatthew Booth 27067273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 27077273a2dbSMatthew Booth 27087273a2dbSMatthew Booth@item -chardev tty,id=@var{id},path=@var{path} 27097273a2dbSMatthew Booth 27107273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2711d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 27127273a2dbSMatthew Booth 27137273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 27147273a2dbSMatthew Booth 271588a946d3SGerd Hoffmann@item -chardev parallel,id=@var{id},path=@var{path} 2716f9cfd655SMarkus Armbruster@itemx -chardev parport,id=@var{id},path=@var{path} 27177273a2dbSMatthew Booth 271888a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 27197273a2dbSMatthew Booth 27207273a2dbSMatthew BoothConnect to a local parallel port. 27217273a2dbSMatthew Booth 27227273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 27237273a2dbSMatthew Boothrequired. 27247273a2dbSMatthew Booth 2725cbcc6336SAlon Levy@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 2726cbcc6336SAlon Levy 27273a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 27283a846906SStefan Hajnoczi 2729cbcc6336SAlon Levy@option{debug} debug level for spicevmc 2730cbcc6336SAlon Levy 2731cbcc6336SAlon Levy@option{name} name of spice channel to connect to 2732cbcc6336SAlon Levy 2733cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 2734cbcc6336SAlon Levy 27355a49d3e9SMarc-André Lureau@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 27365a49d3e9SMarc-André Lureau 27375a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 27385a49d3e9SMarc-André Lureau 27395a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 27405a49d3e9SMarc-André Lureau 27415a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 27425a49d3e9SMarc-André Lureau 27435a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 27445a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 27457273a2dbSMatthew BoothETEXI 27467273a2dbSMatthew Booth 2747c70a01e4SMarkus ArmbrusterSTEXI 2748c70a01e4SMarkus Armbruster@end table 2749c70a01e4SMarkus ArmbrusterETEXI 27507273a2dbSMatthew BoothDEFHEADING() 27517273a2dbSMatthew Booth 2752de6b4f90SMarkus ArmbrusterDEFHEADING(Bluetooth(R) options:) 2753c70a01e4SMarkus ArmbrusterSTEXI 2754c70a01e4SMarkus Armbruster@table @option 2755c70a01e4SMarkus ArmbrusterETEXI 27567273a2dbSMatthew Booth 27575824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 27585824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 27595824d651Sblueswir1 "-bt hci,host[:id]\n" \ 27605824d651Sblueswir1 " use host's HCI with the given name\n" \ 27615824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 27625824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 27635824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 27645824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 27655824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 2766ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2767ad96090aSBlue Swirl QEMU_ARCH_ALL) 27685824d651Sblueswir1STEXI 27695824d651Sblueswir1@item -bt hci[...] 27706616b2adSStefan Weil@findex -bt 27715824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 27725824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 27735824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 27745824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 27755824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 27765824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 27775824d651Sblueswir1machines have none. 27785824d651Sblueswir1 2779c0188e69SThomas HuthNote: This option and the whole bluetooth subsystem is considered as deprecated. 2780c0188e69SThomas HuthIf you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where 2781c0188e69SThomas Huthyou describe your usecase. 2782c0188e69SThomas Huth 27835824d651Sblueswir1@anchor{bt-hcis} 27845824d651Sblueswir1The following three types are recognized: 27855824d651Sblueswir1 2786b3f046c2SKevin Wolf@table @option 27875824d651Sblueswir1@item -bt hci,null 27885824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 27895824d651Sblueswir1and will not respond to any HCI commands or emit events. 27905824d651Sblueswir1 27915824d651Sblueswir1@item -bt hci,host[:@var{id}] 27925824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 27935824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 27945824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 27955824d651Sblueswir1capable systems like Linux. 27965824d651Sblueswir1 27975824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 27985824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 27995824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 28005824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 28015824d651Sblueswir1with other devices in the same network (scatternet). 28025824d651Sblueswir1@end table 28035824d651Sblueswir1 28045824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 28055824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 28065824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 28075824d651Sblueswir1allows the host and target machines to participate in a common scatternet 28085824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 28095824d651Sblueswir1be used as following: 28105824d651Sblueswir1 28115824d651Sblueswir1@example 28123804da9dSStefan Weilqemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 28135824d651Sblueswir1@end example 28145824d651Sblueswir1 28155824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 28165824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 28175824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 28185824d651Sblueswir1currently: 28195824d651Sblueswir1 2820b3f046c2SKevin Wolf@table @option 28215824d651Sblueswir1@item keyboard 28225824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 28235824d651Sblueswir1@end table 28245824d651Sblueswir1ETEXI 28255824d651Sblueswir1 2826c70a01e4SMarkus ArmbrusterSTEXI 2827c70a01e4SMarkus Armbruster@end table 2828c70a01e4SMarkus ArmbrusterETEXI 28295824d651Sblueswir1DEFHEADING() 28305824d651Sblueswir1 2831d1a0cf73SStefan Berger#ifdef CONFIG_TPM 2832de6b4f90SMarkus ArmbrusterDEFHEADING(TPM device options:) 2833d1a0cf73SStefan Berger 2834d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 283592dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 283692dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 283792dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 2838f4ede81eSAmarnath Valluri " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 2839f4ede81eSAmarnath Valluri "-tpmdev emulator,id=id,chardev=dev\n" 2840f4ede81eSAmarnath Valluri " configure the TPM device using chardev backend\n", 2841d1a0cf73SStefan Berger QEMU_ARCH_ALL) 2842d1a0cf73SStefan BergerSTEXI 2843d1a0cf73SStefan Berger 2844d1a0cf73SStefan BergerThe general form of a TPM device option is: 2845d1a0cf73SStefan Berger@table @option 2846d1a0cf73SStefan Berger 2847d1a0cf73SStefan Berger@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 2848d1a0cf73SStefan Berger@findex -tpmdev 2849d1a0cf73SStefan Berger 2850d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 285128c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 285228c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 2853d1a0cf73SStefan Berger 28542252aaf0SMarkus ArmbrusterUse @code{-tpmdev help} to print all available TPM backend types. 2855d1a0cf73SStefan Berger 28562252aaf0SMarkus Armbruster@end table 28572252aaf0SMarkus Armbruster 28582252aaf0SMarkus ArmbrusterThe available backends are: 28592252aaf0SMarkus Armbruster 28602252aaf0SMarkus Armbruster@table @option 2861d1a0cf73SStefan Berger 286292dcc234SStefan Berger@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 28634549a8b7SStefan Berger 28644549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 28654549a8b7SStefan Bergerdriver. 28664549a8b7SStefan Berger 28674549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 28684549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 28694549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 28704549a8b7SStefan Berger 287192dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 287292dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 287392dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 287492dcc234SStefan Bergersysfs entry to use. 287592dcc234SStefan Berger 28764549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 28774549a8b7SStefan Berger 28784549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 28794549a8b7SStefan Bergerused by any other application on the host. 28804549a8b7SStefan Berger 28814549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 28824549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 28834549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 28844549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 28854549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 28864549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 28874549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 28884549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 28894549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 28904549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 28914549a8b7SStefan Berger 28924549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 28934549a8b7SStefan Berger@example 28944549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 28954549a8b7SStefan Berger@end example 28964549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 28974549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 28984549a8b7SStefan Berger 2899f4ede81eSAmarnath Valluri@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 2900f4ede81eSAmarnath Valluri 2901f4ede81eSAmarnath Valluri(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 2902f4ede81eSAmarnath Vallurichardev backend. 2903f4ede81eSAmarnath Valluri 2904f4ede81eSAmarnath Valluri@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 2905f4ede81eSAmarnath Valluri 2906f4ede81eSAmarnath ValluriTo create a TPM emulator backend device with chardev socket backend: 2907f4ede81eSAmarnath Valluri@example 2908f4ede81eSAmarnath Valluri 2909f4ede81eSAmarnath Valluri-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 2910f4ede81eSAmarnath Valluri 2911f4ede81eSAmarnath Valluri@end example 2912f4ede81eSAmarnath Valluri 2913d1a0cf73SStefan BergerETEXI 2914d1a0cf73SStefan Berger 29152252aaf0SMarkus ArmbrusterSTEXI 29162252aaf0SMarkus Armbruster@end table 29172252aaf0SMarkus ArmbrusterETEXI 2918d1a0cf73SStefan BergerDEFHEADING() 2919d1a0cf73SStefan Berger 2920d1a0cf73SStefan Berger#endif 2921d1a0cf73SStefan Berger 2922de6b4f90SMarkus ArmbrusterDEFHEADING(Linux/Multiboot boot specific:) 29235824d651Sblueswir1STEXI 29247677f05dSAlexander Graf 29257677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 29267677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 29275824d651Sblueswir1for easier testing of various kernels. 29285824d651Sblueswir1 29295824d651Sblueswir1@table @option 29305824d651Sblueswir1ETEXI 29315824d651Sblueswir1 29325824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2933ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 29345824d651Sblueswir1STEXI 29355824d651Sblueswir1@item -kernel @var{bzImage} 29366616b2adSStefan Weil@findex -kernel 29377677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 29387677f05dSAlexander Grafor in multiboot format. 29395824d651Sblueswir1ETEXI 29405824d651Sblueswir1 29415824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2942ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 29435824d651Sblueswir1STEXI 29445824d651Sblueswir1@item -append @var{cmdline} 29456616b2adSStefan Weil@findex -append 29465824d651Sblueswir1Use @var{cmdline} as kernel command line 29475824d651Sblueswir1ETEXI 29485824d651Sblueswir1 29495824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2950ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 29515824d651Sblueswir1STEXI 29525824d651Sblueswir1@item -initrd @var{file} 29536616b2adSStefan Weil@findex -initrd 29545824d651Sblueswir1Use @var{file} as initial ram disk. 29557677f05dSAlexander Graf 29567677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 29577677f05dSAlexander Graf 29587677f05dSAlexander GrafThis syntax is only available with multiboot. 29597677f05dSAlexander Graf 29607677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 29617677f05dSAlexander Graffirst module. 29625824d651Sblueswir1ETEXI 29635824d651Sblueswir1 2964412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2965379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2966412beee6SGrant LikelySTEXI 2967412beee6SGrant Likely@item -dtb @var{file} 2968412beee6SGrant Likely@findex -dtb 2969412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 2970412beee6SGrant Likelyon boot. 2971412beee6SGrant LikelyETEXI 2972412beee6SGrant Likely 29735824d651Sblueswir1STEXI 29745824d651Sblueswir1@end table 29755824d651Sblueswir1ETEXI 29765824d651Sblueswir1DEFHEADING() 29775824d651Sblueswir1 2978de6b4f90SMarkus ArmbrusterDEFHEADING(Debug/Expert options:) 29795824d651Sblueswir1STEXI 29805824d651Sblueswir1@table @option 29815824d651Sblueswir1ETEXI 29825824d651Sblueswir1 298381b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 298481b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 298563d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 29866407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 298763d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 298881b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 298981b2b810SGabriel L. SomloSTEXI 299063d3145aSMarkus Armbruster 299181b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 299281b2b810SGabriel L. Somlo@findex -fw_cfg 299363d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 29946407d76eSGabriel L. Somlo 29956407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 299663d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 299763d3145aSMarkus Armbruster 299863d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 299963d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 300063d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 300163d3145aSMarkus Armbruster 300263d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 300363d3145aSMarkus Armbruster 300463d3145aSMarkus ArmbrusterExample: 300563d3145aSMarkus Armbruster@example 300663d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 300763d3145aSMarkus Armbruster@end example 300863d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 300963d3145aSMarkus Armbrusterfrom ./my_blob.bin. 301063d3145aSMarkus Armbruster 301181b2b810SGabriel L. SomloETEXI 301281b2b810SGabriel L. Somlo 30135824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3014ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 3015ad96090aSBlue Swirl QEMU_ARCH_ALL) 30165824d651Sblueswir1STEXI 30175824d651Sblueswir1@item -serial @var{dev} 30186616b2adSStefan Weil@findex -serial 30195824d651Sblueswir1Redirect the virtual serial port to host character device 30205824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 30215824d651Sblueswir1@code{stdio} in non graphical mode. 30225824d651Sblueswir1 30235824d651Sblueswir1This option can be used several times to simulate up to 4 serial 30245824d651Sblueswir1ports. 30255824d651Sblueswir1 30265824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 30275824d651Sblueswir1 30285824d651Sblueswir1Available character devices are: 3029b3f046c2SKevin Wolf@table @option 30304e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 30315824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 30325824d651Sblueswir1@example 30335824d651Sblueswir1vc:800x600 30345824d651Sblueswir1@end example 30355824d651Sblueswir1It is also possible to specify width or height in characters: 30365824d651Sblueswir1@example 30375824d651Sblueswir1vc:80Cx24C 30385824d651Sblueswir1@end example 30395824d651Sblueswir1@item pty 30405824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 30415824d651Sblueswir1@item none 30425824d651Sblueswir1No device is allocated. 30435824d651Sblueswir1@item null 30445824d651Sblueswir1void device 304588e020e5SIngo van Lil@item chardev:@var{id} 304688e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 30475824d651Sblueswir1@item /dev/XXX 30485824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 30495824d651Sblueswir1parameters are set according to the emulated ones. 30505824d651Sblueswir1@item /dev/parport@var{N} 30515824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 30525824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 30535824d651Sblueswir1@item file:@var{filename} 30545824d651Sblueswir1Write output to @var{filename}. No character can be read. 30555824d651Sblueswir1@item stdio 30565824d651Sblueswir1[Unix only] standard input/output 30575824d651Sblueswir1@item pipe:@var{filename} 30585824d651Sblueswir1name pipe @var{filename} 30595824d651Sblueswir1@item COM@var{n} 30605824d651Sblueswir1[Windows only] Use host serial port @var{n} 30615824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 30625824d651Sblueswir1This implements UDP Net Console. 30635824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 30645824d651Sblueswir1they default to @code{0.0.0.0}. 30655824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 30665824d651Sblueswir1 30675824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3068b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3069b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 30705824d651Sblueswir1will appear in the netconsole session. 30715824d651Sblueswir1 30725824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3073b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 30745824d651Sblueswir1source port each time by using something like @code{-serial 3075b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 30765824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 30775824d651Sblueswir1characters via udp. If you have a patched version of netcat which 30785824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3079bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3080b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 30815824d651Sblueswir1@table @code 3082071c9394SStefan Weil@item QEMU Options: 30835824d651Sblueswir1-serial udp::4555@@:4556 30845824d651Sblueswir1@item netcat options: 30855824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 30865824d651Sblueswir1@item telnet options: 30875824d651Sblueswir1localhost 5555 30885824d651Sblueswir1@end table 30895824d651Sblueswir1 30905dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 30915824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 30925824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 30935824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 30945824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 30955824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 30965824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 30975dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 30985dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 30995dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 31005824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 31015824d651Sblueswir1connect to the corresponding character device. 31025824d651Sblueswir1@table @code 31035824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 31045824d651Sblueswir1-serial tcp:192.168.0.2:4444 31055824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 31065824d651Sblueswir1-serial tcp::4444,server 31075824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 31085824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 31095824d651Sblueswir1@end table 31105824d651Sblueswir1 31115824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 31125824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 31135824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 31145824d651Sblueswir1difference is that the port acts like a telnet server or client using 31155824d651Sblueswir1telnet option negotiation. This will also allow you to send the 31165824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 31175824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 31185824d651Sblueswir1type "send break" followed by pressing the enter key. 31195824d651Sblueswir1 3120981b06e7SJulia Suvorova@item websocket:@var{host}:@var{port},server[,nowait][,nodelay] 3121981b06e7SJulia SuvorovaThe WebSocket protocol is used instead of raw tcp socket. The port acts as 3122981b06e7SJulia Suvorovaa WebSocket server. Client mode is not supported. 3123981b06e7SJulia Suvorova 31245dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 31255824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 31265824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 31275824d651Sblueswir1@var{path} is used for connections. 31285824d651Sblueswir1 31295824d651Sblueswir1@item mon:@var{dev_string} 31305824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 31315824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 313202c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 31335824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 31345824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 31355824d651Sblueswir1listening on port 4444 would be: 31365824d651Sblueswir1@table @code 31375824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 31385824d651Sblueswir1@end table 3139be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 314002c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 31415824d651Sblueswir1 31425824d651Sblueswir1@item braille 31435824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 31445824d651Sblueswir1or fake device. 31455824d651Sblueswir1 3146be8b28a9SKevin Wolf@item msmouse 3147be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 31485824d651Sblueswir1@end table 31495824d651Sblueswir1ETEXI 31505824d651Sblueswir1 31515824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3152ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3153ad96090aSBlue Swirl QEMU_ARCH_ALL) 31545824d651Sblueswir1STEXI 31555824d651Sblueswir1@item -parallel @var{dev} 31566616b2adSStefan Weil@findex -parallel 31575824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 31585824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 31595824d651Sblueswir1be used to use hardware devices connected on the corresponding host 31605824d651Sblueswir1parallel port. 31615824d651Sblueswir1 31625824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 31635824d651Sblueswir1ports. 31645824d651Sblueswir1 31655824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 31665824d651Sblueswir1ETEXI 31675824d651Sblueswir1 31685824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3169ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3170ad96090aSBlue Swirl QEMU_ARCH_ALL) 31715824d651Sblueswir1STEXI 31724e307fc8SGerd Hoffmann@item -monitor @var{dev} 31736616b2adSStefan Weil@findex -monitor 31745824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 31755824d651Sblueswir1serial port). 31765824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 31775824d651Sblueswir1non graphical mode. 317870e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 31795824d651Sblueswir1ETEXI 31806ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3181ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3182ad96090aSBlue Swirl QEMU_ARCH_ALL) 318395d5f08bSStefan WeilSTEXI 318495d5f08bSStefan Weil@item -qmp @var{dev} 31856616b2adSStefan Weil@findex -qmp 318695d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 318795d5f08bSStefan WeilETEXI 31884821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 31894821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 31904821cd4cSMax Reitz QEMU_ARCH_ALL) 31914821cd4cSMax ReitzSTEXI 31924821cd4cSMax Reitz@item -qmp-pretty @var{dev} 31934821cd4cSMax Reitz@findex -qmp-pretty 31944821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 31954821cd4cSMax ReitzETEXI 31965824d651Sblueswir1 319722a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3198ef670726SVicente Jimenez Aguilar "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 319922a0e04bSGerd HoffmannSTEXI 3200ef670726SVicente Jimenez Aguilar@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 32016616b2adSStefan Weil@findex -mon 3202ef670726SVicente Jimenez AguilarSetup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 3203ef670726SVicente Jimenez Aguilareasing human reading and debugging. 320422a0e04bSGerd HoffmannETEXI 320522a0e04bSGerd Hoffmann 3206c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3207ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3208ad96090aSBlue Swirl QEMU_ARCH_ALL) 3209c9f398e5SH. Peter AnvinSTEXI 3210c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 32116616b2adSStefan Weil@findex -debugcon 3212c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3213c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3214c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3215c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3216c9f398e5SH. Peter Anvinnon graphical mode. 3217c9f398e5SH. Peter AnvinETEXI 3218c9f398e5SH. Peter Anvin 32195824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3220ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 32215824d651Sblueswir1STEXI 32225824d651Sblueswir1@item -pidfile @var{file} 32236616b2adSStefan Weil@findex -pidfile 32245824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 32255824d651Sblueswir1from a script. 32265824d651Sblueswir1ETEXI 32275824d651Sblueswir1 32281b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3229ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 32301b530a6dSaurel32STEXI 32311b530a6dSaurel32@item -singlestep 32326616b2adSStefan Weil@findex -singlestep 32331b530a6dSaurel32Run the emulation in single step mode. 32341b530a6dSaurel32ETEXI 32351b530a6dSaurel32 3236047f7038SIgor MammedovDEF("preconfig", 0, QEMU_OPTION_preconfig, \ 3237361ac948SMarkus Armbruster "--preconfig pause QEMU before machine is initialized (experimental)\n", 3238047f7038SIgor Mammedov QEMU_ARCH_ALL) 3239047f7038SIgor MammedovSTEXI 3240047f7038SIgor Mammedov@item --preconfig 3241047f7038SIgor Mammedov@findex --preconfig 3242047f7038SIgor MammedovPause QEMU for interactive configuration before the machine is created, 3243047f7038SIgor Mammedovwhich allows querying and configuring properties that will affect 3244361ac948SMarkus Armbrustermachine initialization. Use QMP command 'x-exit-preconfig' to exit 3245361ac948SMarkus Armbrusterthe preconfig state and move to the next state (i.e. run guest if -S 3246361ac948SMarkus Armbrusterisn't used or pause the second time if -S is used). This option is 3247361ac948SMarkus Armbrusterexperimental. 3248047f7038SIgor MammedovETEXI 3249047f7038SIgor Mammedov 32505824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3251ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3252ad96090aSBlue Swirl QEMU_ARCH_ALL) 32535824d651Sblueswir1STEXI 32545824d651Sblueswir1@item -S 32556616b2adSStefan Weil@findex -S 32565824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 32575824d651Sblueswir1ETEXI 32585824d651Sblueswir1 3259888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3260888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3261888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3262888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3263888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3264888a6bc6SSatoru MoriyaSTEXI 3265888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3266888a6bc6SSatoru Moriya@findex -realtime 3267888a6bc6SSatoru MoriyaRun qemu with realtime features. 3268888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3269888a6bc6SSatoru Moriya(enabled by default). 3270888a6bc6SSatoru MoriyaETEXI 3271888a6bc6SSatoru Moriya 32726f131f13SMichael S. TsirkinDEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, 3273dfaa7d50SBALATON Zoltan "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" 32746f131f13SMichael S. Tsirkin " run qemu with overcommit hints\n" 32756f131f13SMichael S. Tsirkin " mem-lock=on|off controls memory lock support (default: off)\n" 32766f131f13SMichael S. Tsirkin " cpu-pm=on|off controls cpu power management (default: off)\n", 32776f131f13SMichael S. Tsirkin QEMU_ARCH_ALL) 32786f131f13SMichael S. TsirkinSTEXI 32796f131f13SMichael S. Tsirkin@item -overcommit mem-lock=on|off 32806f131f13SMichael S. Tsirkin@item -overcommit cpu-pm=on|off 32816f131f13SMichael S. Tsirkin@findex -overcommit 32826f131f13SMichael S. TsirkinRun qemu with hints about host resource overcommit. The default is 32836f131f13SMichael S. Tsirkinto assume that host overcommits all resources. 32846f131f13SMichael S. Tsirkin 32856f131f13SMichael S. TsirkinLocking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled 32866f131f13SMichael S. Tsirkinby default). This works when host memory is not overcommitted and reduces the 32876f131f13SMichael S. Tsirkinworst-case latency for guest. This is equivalent to @option{realtime}. 32886f131f13SMichael S. Tsirkin 32896f131f13SMichael S. TsirkinGuest ability to manage power state of host cpus (increasing latency for other 32906f131f13SMichael S. Tsirkinprocesses on the same host cpu, but decreasing latency for guest) can be 32916f131f13SMichael S. Tsirkinenabled via @option{cpu-pm=on} (disabled by default). This works best when 32926f131f13SMichael S. Tsirkinhost CPU is not overcommitted. When used, host estimates of CPU cycle and power 32936f131f13SMichael S. Tsirkinutilization will be incorrect, not taking into account guest idle time. 32946f131f13SMichael S. TsirkinETEXI 32956f131f13SMichael S. Tsirkin 329659030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3297ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 32985824d651Sblueswir1STEXI 329959030a8cSaliguori@item -gdb @var{dev} 33006616b2adSStefan Weil@findex -gdb 330159030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 330259030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3303b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 330459030a8cSaliguoriwithin gdb and establish the connection via a pipe: 330559030a8cSaliguori@example 33063804da9dSStefan Weil(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 330759030a8cSaliguori@end example 33085824d651Sblueswir1ETEXI 33095824d651Sblueswir1 331059030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3311ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3312ad96090aSBlue Swirl QEMU_ARCH_ALL) 33135824d651Sblueswir1STEXI 331459030a8cSaliguori@item -s 33156616b2adSStefan Weil@findex -s 331659030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 331759030a8cSaliguori(@pxref{gdb_usage}). 33185824d651Sblueswir1ETEXI 33195824d651Sblueswir1 33205824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3321989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3322ad96090aSBlue Swirl QEMU_ARCH_ALL) 33235824d651Sblueswir1STEXI 3324989b697dSPeter Maydell@item -d @var{item1}[,...] 33256616b2adSStefan Weil@findex -d 3326989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 33275824d651Sblueswir1ETEXI 33285824d651Sblueswir1 3329c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3330989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3331c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3332c235d738SMatthew FernandezSTEXI 33338bd383b4SStefan Weil@item -D @var{logfile} 3334c235d738SMatthew Fernandez@findex -D 3335989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3336c235d738SMatthew FernandezETEXI 3337c235d738SMatthew Fernandez 33383514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 33393514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 33403514552eSAlex Bennée QEMU_ARCH_ALL) 33413514552eSAlex BennéeSTEXI 33423514552eSAlex Bennée@item -dfilter @var{range1}[,...] 33433514552eSAlex Bennée@findex -dfilter 33443514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 33453514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 33463514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 33473514552eSAlex Bennéeaddresses and sizes required. For example: 33483514552eSAlex Bennée@example 33493514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 33503514552eSAlex Bennée@end example 33513514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 33523514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 33533514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 33543514552eSAlex BennéeETEXI 33553514552eSAlex Bennée 33565824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3357ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3358ad96090aSBlue Swirl QEMU_ARCH_ALL) 33595824d651Sblueswir1STEXI 33605824d651Sblueswir1@item -L @var{path} 33616616b2adSStefan Weil@findex -L 33625824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 336337146e7eSRichard W.M. Jones 336437146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 33655824d651Sblueswir1ETEXI 33665824d651Sblueswir1 33675824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3368ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 33695824d651Sblueswir1STEXI 33705824d651Sblueswir1@item -bios @var{file} 33716616b2adSStefan Weil@findex -bios 33725824d651Sblueswir1Set the filename for the BIOS. 33735824d651Sblueswir1ETEXI 33745824d651Sblueswir1 33755824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3376ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 33775824d651Sblueswir1STEXI 33785824d651Sblueswir1@item -enable-kvm 33796616b2adSStefan Weil@findex -enable-kvm 33805824d651Sblueswir1Enable KVM full virtualization support. This option is only available 33815824d651Sblueswir1if KVM support is enabled when compiling. 33825824d651Sblueswir1ETEXI 33835824d651Sblueswir1 3384b0cb0a66SVincent PalatinDEF("enable-hax", 0, QEMU_OPTION_enable_hax, \ 3385b0cb0a66SVincent Palatin "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386) 3386b0cb0a66SVincent PalatinSTEXI 3387b0cb0a66SVincent Palatin@item -enable-hax 3388b0cb0a66SVincent Palatin@findex -enable-hax 3389b0cb0a66SVincent PalatinEnable HAX (Hardware-based Acceleration eXecution) support. This option 3390b0cb0a66SVincent Palatinis only available if HAX support is enabled when compiling. HAX is only 3391b0cb0a66SVincent Palatinapplicable to MAC and Windows platform, and thus does not conflict with 3392c44df2ffSThomas HuthKVM. This option is deprecated, use @option{-accel hax} instead. 3393b0cb0a66SVincent PalatinETEXI 3394b0cb0a66SVincent Palatin 3395e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3396ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3397e37630caSaliguoriDEF("xen-create", 0, QEMU_OPTION_xen_create, 3398e37630caSaliguori "-xen-create create domain using xen hypercalls, bypassing xend\n" 3399ad96090aSBlue Swirl " warning: should not be used when xend is in use\n", 3400ad96090aSBlue Swirl QEMU_ARCH_ALL) 3401e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3402e37630caSaliguori "-xen-attach attach to existing xen domain\n" 3403b65ee4faSStefan Weil " xend will use this when starting QEMU\n", 3404ad96090aSBlue Swirl QEMU_ARCH_ALL) 34051c599472SPaul DurrantDEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 34061c599472SPaul Durrant "-xen-domid-restrict restrict set of available xen operations\n" 34071c599472SPaul Durrant " to specified domain id. (Does not affect\n" 34081c599472SPaul Durrant " xenpv machine type).\n", 34091c599472SPaul Durrant QEMU_ARCH_ALL) 341095d5f08bSStefan WeilSTEXI 341195d5f08bSStefan Weil@item -xen-domid @var{id} 34126616b2adSStefan Weil@findex -xen-domid 341395d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 341495d5f08bSStefan Weil@item -xen-create 34156616b2adSStefan Weil@findex -xen-create 341695d5f08bSStefan WeilCreate domain using xen hypercalls, bypassing xend. 341795d5f08bSStefan WeilWarning: should not be used when xend is in use (XEN only). 341895d5f08bSStefan Weil@item -xen-attach 34196616b2adSStefan Weil@findex -xen-attach 342095d5f08bSStefan WeilAttach to existing xen domain. 3421b65ee4faSStefan Weilxend will use this when starting QEMU (XEN only). 34221c599472SPaul Durrant@findex -xen-domid-restrict 34231c599472SPaul DurrantRestrict set of available xen operations to specified domain id (XEN only). 342495d5f08bSStefan WeilETEXI 3425e37630caSaliguori 34265824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3427ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 34285824d651Sblueswir1STEXI 34295824d651Sblueswir1@item -no-reboot 34306616b2adSStefan Weil@findex -no-reboot 34315824d651Sblueswir1Exit instead of rebooting. 34325824d651Sblueswir1ETEXI 34335824d651Sblueswir1 34345824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3435ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 34365824d651Sblueswir1STEXI 34375824d651Sblueswir1@item -no-shutdown 34386616b2adSStefan Weil@findex -no-shutdown 34395824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 34405824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 34415824d651Sblueswir1disk image. 34425824d651Sblueswir1ETEXI 34435824d651Sblueswir1 34445824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 34455824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3446ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3447ad96090aSBlue Swirl QEMU_ARCH_ALL) 34485824d651Sblueswir1STEXI 34495824d651Sblueswir1@item -loadvm @var{file} 34506616b2adSStefan Weil@findex -loadvm 34515824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 34525824d651Sblueswir1ETEXI 34535824d651Sblueswir1 34545824d651Sblueswir1#ifndef _WIN32 34555824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3456ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 34575824d651Sblueswir1#endif 34585824d651Sblueswir1STEXI 34595824d651Sblueswir1@item -daemonize 34606616b2adSStefan Weil@findex -daemonize 34615824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 34625824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 34635824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 34645824d651Sblueswir1to cope with initialization race conditions. 34655824d651Sblueswir1ETEXI 34665824d651Sblueswir1 34675824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3468ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3469ad96090aSBlue Swirl QEMU_ARCH_ALL) 34705824d651Sblueswir1STEXI 34715824d651Sblueswir1@item -option-rom @var{file} 34726616b2adSStefan Weil@findex -option-rom 34735824d651Sblueswir1Load the contents of @var{file} as an option ROM. 34745824d651Sblueswir1This option is useful to load things like EtherBoot. 34755824d651Sblueswir1ETEXI 34765824d651Sblueswir1 3477e218052fSMarkus ArmbrusterHXCOMM Silently ignored for compatibility 3478e218052fSMarkus ArmbrusterDEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 34795824d651Sblueswir1 34801ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 3481238d1240SArtem Pisarenko "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3482ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3483ad96090aSBlue Swirl QEMU_ARCH_ALL) 34841ed2fc1fSJan Kiszka 34855824d651Sblueswir1STEXI 34865824d651Sblueswir1 3487238d1240SArtem Pisarenko@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew] 34886616b2adSStefan Weil@findex -rtc 34891ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 34901ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 3491238d1240SArtem PisarenkoMS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the 34921ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 34931ed2fc1fSJan Kiszka 34949d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 34956875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 34966875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 349778808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 3498238d1240SArtem Pisarenkoto @code{rt} instead, which provides a host monotonic clock if host support it. 3499238d1240SArtem PisarenkoTo even prevent the RTC from progressing during suspension, you can set @option{clock} 3500238d1240SArtem Pisarenkoto @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in 3501238d1240SArtem Pisarenkoicount mode in order to preserve determinism; however, note that in icount mode 3502238d1240SArtem Pisarenkothe speed of the virtual clock is variable and can in general differ from the 3503238d1240SArtem Pisarenkohost clock. 35046875204cSJan Kiszka 35051ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 35061ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 35071ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 35081ed2fc1fSJan Kiszkare-inject them. 35095824d651Sblueswir1ETEXI 35105824d651Sblueswir1 35115824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 35129c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3513bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3514f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3515f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 35165824d651Sblueswir1STEXI 35179c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 35186616b2adSStefan Weil@findex -icount 35195824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 35204e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 35215824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 35225824d651Sblueswir1time within a few seconds of real time. 35235824d651Sblueswir1 3524f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3525778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3526778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3527f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3528f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3529f1f4b57eSVictor CLEMENTthe guest point of view. 3530f1f4b57eSVictor CLEMENT 35315824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 35325824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 35335824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 35345824d651Sblueswir1executed often has little or no correlation with actual performance. 3535a8bfac37SSebastian Tanase 3536b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3537a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3538a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3539a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 354082597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3541a8bfac37SSebastian Tanaseto inform about the delay. 3542a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3543a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3544a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3545a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 35464c27b859SPavel Dovgalyuk 35474c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 35484c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 35494c27b859SPavel Dovgalyukread from this file in replay mode. 35509c2037d0SPavel Dovgalyuk 35519c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 35529c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 35539c2037d0SPavel Dovgalyukto load the initial VM state. 35545824d651Sblueswir1ETEXI 35555824d651Sblueswir1 35569dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3557d7933ef3SXu Wang "-watchdog model\n" \ 3558ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3559ad96090aSBlue Swirl QEMU_ARCH_ALL) 35609dd986ccSRichard W.M. JonesSTEXI 35619dd986ccSRichard W.M. Jones@item -watchdog @var{model} 35626616b2adSStefan Weil@findex -watchdog 35639dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 35649dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3565d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3566d7933ef3SXu Wangwhich your guest has drivers. 35679dd986ccSRichard W.M. Jones 3568d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3569d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 35709dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3571d7933ef3SXu Wang 3572d7933ef3SXu WangThe following models may be available: 3573d7933ef3SXu Wang@table @option 3574d7933ef3SXu Wang@item ib700 3575d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3576d7933ef3SXu Wang@item i6300esb 3577d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3578d7933ef3SXu Wangdual-timer watchdog. 3579188f24c2SXu Wang@item diag288 3580188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3581188f24c2SXu Wang(currently KVM only). 3582d7933ef3SXu Wang@end table 35839dd986ccSRichard W.M. JonesETEXI 35849dd986ccSRichard W.M. Jones 35859dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 35867ad9270eSMarkus Armbruster "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 3587ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3588ad96090aSBlue Swirl QEMU_ARCH_ALL) 35899dd986ccSRichard W.M. JonesSTEXI 35909dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3591b8f490ebSMarkus Armbruster@findex -watchdog-action 35929dd986ccSRichard W.M. Jones 35939dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 35949dd986ccSRichard W.M. Jonesexpires. 35959dd986ccSRichard W.M. JonesThe default is 35969dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 35979dd986ccSRichard W.M. JonesOther possible actions are: 35989dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 35999dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 36007ad9270eSMarkus Armbruster@code{inject-nmi} (inject a NMI into the guest), 36019dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 36029dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 36039dd986ccSRichard W.M. Jones@code{none} (do nothing). 36049dd986ccSRichard W.M. Jones 36059dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 36069dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 36079dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 36089dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 36099dd986ccSRichard W.M. Jones 36109dd986ccSRichard W.M. JonesExamples: 36119dd986ccSRichard W.M. Jones 36129dd986ccSRichard W.M. Jones@table @code 36139dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3614f9cfd655SMarkus Armbruster@itemx -watchdog ib700 36159dd986ccSRichard W.M. Jones@end table 36169dd986ccSRichard W.M. JonesETEXI 36179dd986ccSRichard W.M. Jones 36185824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3619ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3620ad96090aSBlue Swirl QEMU_ARCH_ALL) 36215824d651Sblueswir1STEXI 36225824d651Sblueswir1 36234e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 36246616b2adSStefan Weil@findex -echr 36255824d651Sblueswir1Change the escape character used for switching to the monitor when using 36265824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 36275824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 36285824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 36295824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 36305824d651Sblueswir1instance you could use the either of the following to change the escape 36315824d651Sblueswir1character to Control-t. 36325824d651Sblueswir1@table @code 36335824d651Sblueswir1@item -echr 0x14 3634f9cfd655SMarkus Armbruster@itemx -echr 20 36355824d651Sblueswir1@end table 36365824d651Sblueswir1ETEXI 36375824d651Sblueswir1 36385824d651Sblueswir1DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 36395824d651Sblueswir1 "-virtioconsole c\n" \ 3640ad96090aSBlue Swirl " set virtio console\n", QEMU_ARCH_ALL) 36415824d651Sblueswir1STEXI 36425824d651Sblueswir1@item -virtioconsole @var{c} 36436616b2adSStefan Weil@findex -virtioconsole 36445824d651Sblueswir1Set virtio console. 364545401299SThomas HuthThis option is deprecated, please use @option{-device virtconsole} instead. 36465824d651Sblueswir1ETEXI 36475824d651Sblueswir1 36485824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3649ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 36505824d651Sblueswir1STEXI 365195d5f08bSStefan Weil@item -show-cursor 36526616b2adSStefan Weil@findex -show-cursor 365395d5f08bSStefan WeilShow cursor. 36545824d651Sblueswir1ETEXI 36555824d651Sblueswir1 36565824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3657ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 36585824d651Sblueswir1STEXI 365995d5f08bSStefan Weil@item -tb-size @var{n} 36606616b2adSStefan Weil@findex -tb-size 366195d5f08bSStefan WeilSet TB size. 36625824d651Sblueswir1ETEXI 36635824d651Sblueswir1 36645824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 36657c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 36667c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 36677c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 36687c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 36697c601803SMichael Tokarev " specified protocol and socket address\n" \ 36707c601803SMichael Tokarev "-incoming fd:fd\n" \ 36717c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 36727c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 36731597051bSDr. David Alan Gilbert " or from given external command\n" \ 36741597051bSDr. David Alan Gilbert "-incoming defer\n" \ 36751597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3676ad96090aSBlue Swirl QEMU_ARCH_ALL) 36775824d651Sblueswir1STEXI 36787c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3679f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 36806616b2adSStefan Weil@findex -incoming 36817c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 36827c601803SMichael Tokarev 36837c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 36847c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 36857c601803SMichael Tokarev 36867c601803SMichael Tokarev@item -incoming fd:@var{fd} 36877c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 36887c601803SMichael Tokarev 36897c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 36907c601803SMichael TokarevAccept incoming migration as an output from specified external command. 36911597051bSDr. David Alan Gilbert 36921597051bSDr. David Alan Gilbert@item -incoming defer 36931597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 36941597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 36951597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 36965824d651Sblueswir1ETEXI 36975824d651Sblueswir1 3698d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 3699d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 3700d15c05fcSAshijeet AcharyaSTEXI 3701d15c05fcSAshijeet Acharya@item -only-migratable 3702d15c05fcSAshijeet Acharya@findex -only-migratable 3703d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 3704d15c05fcSAshijeet Acharyaunmigratable state. 3705d15c05fcSAshijeet AcharyaETEXI 3706d15c05fcSAshijeet Acharya 3707d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3708ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3709d8c208ddSGerd HoffmannSTEXI 37103dbf2c7fSStefan Weil@item -nodefaults 37116616b2adSStefan Weil@findex -nodefaults 371266c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 371366c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 371466c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 371566c19bf1SMichal Novotnydefault devices. 3716d8c208ddSGerd HoffmannETEXI 3717d8c208ddSGerd Hoffmann 37185824d651Sblueswir1#ifndef _WIN32 37195824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3720ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3721ad96090aSBlue Swirl QEMU_ARCH_ALL) 37225824d651Sblueswir1#endif 37235824d651Sblueswir1STEXI 37244e257e5eSKevin Wolf@item -chroot @var{dir} 37256616b2adSStefan Weil@findex -chroot 37265824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 37275824d651Sblueswir1directory. Especially useful in combination with -runas. 37285824d651Sblueswir1ETEXI 37295824d651Sblueswir1 37305824d651Sblueswir1#ifndef _WIN32 37315824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 37322c42f1e8SIan Jackson "-runas user change to user id user just before starting the VM\n" \ 37332c42f1e8SIan Jackson " user can be numeric uid:gid instead\n", 3734ad96090aSBlue Swirl QEMU_ARCH_ALL) 37355824d651Sblueswir1#endif 37365824d651Sblueswir1STEXI 37374e257e5eSKevin Wolf@item -runas @var{user} 37386616b2adSStefan Weil@findex -runas 37395824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 37405824d651Sblueswir1to the specified user. 37415824d651Sblueswir1ETEXI 37425824d651Sblueswir1 37435824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 37445824d651Sblueswir1 "-prom-env variable=value\n" 3745ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 3746ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 374795d5f08bSStefan WeilSTEXI 374895d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 37496616b2adSStefan Weil@findex -prom-env 375095d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 375195d5f08bSStefan WeilETEXI 37525824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 3753f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 37543b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 37553b3c1694SLeon Alrae QEMU_ARCH_MIPS) 375695d5f08bSStefan WeilSTEXI 375795d5f08bSStefan Weil@item -semihosting 37586616b2adSStefan Weil@findex -semihosting 37593b3c1694SLeon AlraeEnable semihosting mode (ARM, M68K, Xtensa, MIPS only). 3760a38bb079SLiviu IonescuETEXI 3761a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3762a59d31a1SLeon Alrae "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 3763a59d31a1SLeon Alrae " semihosting configuration\n", 37643b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 37653b3c1694SLeon AlraeQEMU_ARCH_MIPS) 3766a38bb079SLiviu IonescuSTEXI 3767a59d31a1SLeon Alrae@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 3768a38bb079SLiviu Ionescu@findex -semihosting-config 37693b3c1694SLeon AlraeEnable and configure semihosting (ARM, M68K, Xtensa, MIPS only). 3770a59d31a1SLeon Alrae@table @option 3771a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 3772a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 3773a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 3774a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 3775a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 3776a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 3777a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 3778a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 3779a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 3780a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 3781a59d31a1SLeon Alrae@end table 378295d5f08bSStefan WeilETEXI 37835824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 3784ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 378595d5f08bSStefan WeilSTEXI 378695d5f08bSStefan Weil@item -old-param 37876616b2adSStefan Weil@findex -old-param (ARM) 378895d5f08bSStefan WeilOld param mode (ARM only). 378995d5f08bSStefan WeilETEXI 379095d5f08bSStefan Weil 37917d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 379273a1e647SEduardo Otubo "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 379324f8cdc5SEduardo Otubo " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 37942b716fa6SEduardo Otubo " Enable seccomp mode 2 system call filter (default 'off').\n" \ 37952b716fa6SEduardo Otubo " use 'obsolete' to allow obsolete system calls that are provided\n" \ 37962b716fa6SEduardo Otubo " by the kernel, but typically no longer used by modern\n" \ 379773a1e647SEduardo Otubo " C library implementations.\n" \ 379873a1e647SEduardo Otubo " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 379973a1e647SEduardo Otubo " its privileges by blacklisting all set*uid|gid system calls.\n" \ 380073a1e647SEduardo Otubo " The value 'children' will deny set*uid|gid system calls for\n" \ 3801995a226fSEduardo Otubo " main QEMU process but will allow forks and execves to run unprivileged\n" \ 3802995a226fSEduardo Otubo " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 380324f8cdc5SEduardo Otubo " blacklisting *fork and execve\n" \ 380424f8cdc5SEduardo Otubo " use 'resourcecontrol' to disable process affinity and schedular priority\n", 38057d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 38067d76ad4fSEduardo OtuboSTEXI 380724f8cdc5SEduardo Otubo@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 38087d76ad4fSEduardo Otubo@findex -sandbox 38097d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 38107d76ad4fSEduardo Otubodisable it. The default is 'off'. 38112b716fa6SEduardo Otubo@table @option 38122b716fa6SEduardo Otubo@item obsolete=@var{string} 38132b716fa6SEduardo OtuboEnable Obsolete system calls 381473a1e647SEduardo Otubo@item elevateprivileges=@var{string} 381573a1e647SEduardo OtuboDisable set*uid|gid system calls 3816995a226fSEduardo Otubo@item spawn=@var{string} 3817995a226fSEduardo OtuboDisable *fork and execve 381824f8cdc5SEduardo Otubo@item resourcecontrol=@var{string} 381924f8cdc5SEduardo OtuboDisable process affinity and schedular priority 38202b716fa6SEduardo Otubo@end table 38217d76ad4fSEduardo OtuboETEXI 38227d76ad4fSEduardo Otubo 3823715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3824ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 38253dbf2c7fSStefan WeilSTEXI 38263dbf2c7fSStefan Weil@item -readconfig @var{file} 38276616b2adSStefan Weil@findex -readconfig 3828ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 3829ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 3830ed24cfacSMichal Novotnycharacter limit. 38313dbf2c7fSStefan WeilETEXI 3832715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3833715a664aSGerd Hoffmann "-writeconfig <file>\n" 3834ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 38353dbf2c7fSStefan WeilSTEXI 38363dbf2c7fSStefan Weil@item -writeconfig @var{file} 38376616b2adSStefan Weil@findex -writeconfig 3838ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 3839ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 3840ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 38413dbf2c7fSStefan WeilETEXI 38422feac451SThomas Huth 3843f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3844f29a5614SEduardo Habkost "-no-user-config\n" 38453478eae9SEduardo Habkost " do not load default user-provided config files at startup\n", 3846f29a5614SEduardo Habkost QEMU_ARCH_ALL) 3847f29a5614SEduardo HabkostSTEXI 3848f29a5614SEduardo Habkost@item -no-user-config 3849f29a5614SEduardo Habkost@findex -no-user-config 3850f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 38513478eae9SEduardo Habkostconfig files on @var{sysconfdir}. 3852292444cbSAnthony LiguoriETEXI 38532feac451SThomas Huth 3854ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 385510578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 385623d15e86SLluís " specify tracing options\n", 3857ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 3858ab6540d5SPrerna SaxenaSTEXI 385923d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 386023d15e86SLluísHXCOMM HX does not support conditional compilation of text. 3861e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 3862ab6540d5SPrerna Saxena@findex -trace 3863eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 3864ab6540d5SPrerna SaxenaETEXI 38653dbf2c7fSStefan Weil 386631e70d6cSMarkus ArmbrusterHXCOMM Internal use 386731e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 386831e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3869c7f0f3b1SAnthony Liguori 38700f66998fSPaul Moore#ifdef __linux__ 38710f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 38720f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 38730f66998fSPaul Moore QEMU_ARCH_ALL) 38740f66998fSPaul Moore#endif 38750f66998fSPaul MooreSTEXI 38760f66998fSPaul Moore@item -enable-fips 38770f66998fSPaul Moore@findex -enable-fips 38780f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 38790f66998fSPaul MooreETEXI 38800f66998fSPaul Moore 3881a0dac021SJan KiszkaHXCOMM Deprecated by -machine accel=tcg property 3882c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3883a0dac021SJan Kiszka 38845e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 38855e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 38865e2ac519SSeiji Aguchi " change the format of messages\n" 38875e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 38885e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 38895e2ac519SSeiji AguchiSTEXI 38905e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 38915e2ac519SSeiji Aguchi@findex -msg 38925e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 38935e2ac519SSeiji AguchiETEXI 38945e2ac519SSeiji Aguchi 3895abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 3896abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 3897abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 3898abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 3899abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 39002382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 3901abfd9ce3SAmit Shah QEMU_ARCH_ALL) 3902abfd9ce3SAmit ShahSTEXI 3903abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 3904abfd9ce3SAmit Shah@findex -dump-vmstate 3905abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 3906abfd9ce3SAmit Shahin @var{file} 3907abfd9ce3SAmit ShahETEXI 3908abfd9ce3SAmit Shah 390912df189dSEmilio G. CotaDEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, 391012df189dSEmilio G. Cota "-enable-sync-profile\n" 391112df189dSEmilio G. Cota " enable synchronization profiling\n", 391212df189dSEmilio G. Cota QEMU_ARCH_ALL) 391312df189dSEmilio G. CotaSTEXI 391412df189dSEmilio G. Cota@item -enable-sync-profile 391512df189dSEmilio G. Cota@findex -enable-sync-profile 391612df189dSEmilio G. CotaEnable synchronization profiling. 391712df189dSEmilio G. CotaETEXI 391812df189dSEmilio G. Cota 391943f187a5SPaolo BonziniSTEXI 392043f187a5SPaolo Bonzini@end table 392143f187a5SPaolo BonziniETEXI 392243f187a5SPaolo BonziniDEFHEADING() 3923de6b4f90SMarkus Armbruster 3924de6b4f90SMarkus ArmbrusterDEFHEADING(Generic object creation:) 392543f187a5SPaolo BonziniSTEXI 392643f187a5SPaolo Bonzini@table @option 392743f187a5SPaolo BonziniETEXI 3928b9174d4fSDaniel P. Berrange 3929b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 3930b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 3931b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 3932b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 3933b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 3934b9174d4fSDaniel P. Berrange " '/objects' path.\n", 3935b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 3936b9174d4fSDaniel P. BerrangeSTEXI 3937b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3938b9174d4fSDaniel P. Berrange@findex -object 3939b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 3940b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 3941b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 3942b9174d4fSDaniel P. Berrange'/objects' path. 3943b9174d4fSDaniel P. Berrange 3944b9174d4fSDaniel P. Berrange@table @option 3945b9174d4fSDaniel P. Berrange 394698376843SHaozhong 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} 3947b9174d4fSDaniel P. Berrange 3948b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 3949c7cddce1SStefan Hajnoczithe guest RAM with huge pages. 3950c7cddce1SStefan Hajnoczi 3951c7cddce1SStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 3952c7cddce1SStefan Hajnoczimemory region when configuring the @option{-numa} argument. 3953c7cddce1SStefan Hajnoczi 3954c7cddce1SStefan HajnocziThe @option{size} option provides the size of the memory region, and accepts 3955c7cddce1SStefan Hajnoczicommon suffixes, eg @option{500M}. 3956c7cddce1SStefan Hajnoczi 3957c7cddce1SStefan HajnocziThe @option{mem-path} provides the path to either a shared memory or huge page 3958c7cddce1SStefan Hajnoczifilesystem mount. 3959c7cddce1SStefan Hajnoczi 3960b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 3961b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 3962b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 3963c7cddce1SStefan Hajnoczi 396406329cceSMarcel ApfelbaumThe @option{share} is also required for pvrdma devices due to 396506329cceSMarcel Apfelbaumlimitations in the RDMA API provided by Linux. 396606329cceSMarcel Apfelbaum 396706329cceSMarcel ApfelbaumSetting share=on might affect the ability to configure NUMA 396806329cceSMarcel Apfelbaumbindings for the memory backend under some circumstances, see 396906329cceSMarcel ApfelbaumDocumentation/vm/numa_memory_policy.txt on the Linux kernel 397006329cceSMarcel Apfelbaumsource tree for additional details. 397106329cceSMarcel Apfelbaum 397211ae6ed8SEduardo HabkostSetting the @option{discard-data} boolean option to @var{on} 397311ae6ed8SEduardo Habkostindicates that file contents can be destroyed when QEMU exits, 397411ae6ed8SEduardo Habkostto avoid unnecessarily flushing data to the backing file. Note 397511ae6ed8SEduardo Habkostthat @option{discard-data} is only an optimization, and QEMU 397611ae6ed8SEduardo Habkostmight not discard file contents if it aborts unexpectedly or is 397711ae6ed8SEduardo Habkostterminated using SIGKILL. 3978b9174d4fSDaniel P. Berrange 3979c7cddce1SStefan HajnocziThe @option{merge} boolean option enables memory merge, also known as 3980c7cddce1SStefan HajnocziMADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 3981c7cddce1SStefan Hajnoczimemory deduplication. 3982c7cddce1SStefan Hajnoczi 3983c7cddce1SStefan HajnocziSetting the @option{dump} boolean option to @var{off} excludes the memory from 3984c7cddce1SStefan Hajnoczicore dumps. This feature is also known as MADV_DONTDUMP. 3985c7cddce1SStefan Hajnoczi 3986c7cddce1SStefan HajnocziThe @option{prealloc} boolean option enables memory preallocation. 3987c7cddce1SStefan Hajnoczi 3988c7cddce1SStefan HajnocziThe @option{host-nodes} option binds the memory range to a list of NUMA host 3989c7cddce1SStefan Hajnoczinodes. 3990c7cddce1SStefan Hajnoczi 3991c7cddce1SStefan HajnocziThe @option{policy} option sets the NUMA policy to one of the following values: 3992c7cddce1SStefan Hajnoczi 3993c7cddce1SStefan Hajnoczi@table @option 3994c7cddce1SStefan Hajnoczi@item @var{default} 3995c7cddce1SStefan Hajnoczidefault host policy 3996c7cddce1SStefan Hajnoczi 3997c7cddce1SStefan Hajnoczi@item @var{preferred} 3998c7cddce1SStefan Hajnocziprefer the given host node list for allocation 3999c7cddce1SStefan Hajnoczi 4000c7cddce1SStefan Hajnoczi@item @var{bind} 4001c7cddce1SStefan Hajnoczirestrict memory allocation to the given host node list 4002c7cddce1SStefan Hajnoczi 4003c7cddce1SStefan Hajnoczi@item @var{interleave} 4004c7cddce1SStefan Hajnocziinterleave memory allocations across the given host node list 4005c7cddce1SStefan Hajnoczi@end table 4006c7cddce1SStefan Hajnoczi 400798376843SHaozhong ZhangThe @option{align} option specifies the base address alignment when 400898376843SHaozhong ZhangQEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 400998376843SHaozhong Zhang@option{2M}. Some backend store specified by @option{mem-path} 401098376843SHaozhong Zhangrequires an alignment different than the default one used by QEMU, eg 401198376843SHaozhong Zhangthe device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 401298376843SHaozhong Zhangsuch cases, users can specify the required alignment via this option. 401398376843SHaozhong Zhang 4014a4de8552SJunyan HeThe @option{pmem} option specifies whether the backing file specified 4015a4de8552SJunyan Heby @option{mem-path} is in host persistent memory that can be accessed 4016a4de8552SJunyan Heusing the SNIA NVM programming model (e.g. Intel NVDIMM). 4017a4de8552SJunyan HeIf @option{pmem} is set to 'on', QEMU will take necessary operations to 4018a4de8552SJunyan Heguarantee the persistence of its own writes to @option{mem-path} 4019a4de8552SJunyan He(e.g. in vNVDIMM label emulation and live migration). 4020a4de8552SJunyan He 402106329cceSMarcel 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} 4022cd19491aSStefan Hajnoczi 4023cd19491aSStefan HajnocziCreates a memory backend object, which can be used to back the guest RAM. 4024cd19491aSStefan HajnocziMemory backend objects offer more control than the @option{-m} option that is 4025cd19491aSStefan Hajnoczitraditionally used to define guest RAM. Please refer to 4026cd19491aSStefan Hajnoczi@option{memory-backend-file} for a description of the options. 4027cd19491aSStefan Hajnoczi 402836ea3979SMarc-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} 4029dbb9e0f4SMarc-André Lureau 4030dbb9e0f4SMarc-André LureauCreates an anonymous memory file backend object, which allows QEMU to 4031dbb9e0f4SMarc-André Lureaushare the memory with an external process (e.g. when using 4032dbb9e0f4SMarc-André Lureauvhost-user). The memory is allocated with memfd and optional 4033dbb9e0f4SMarc-André Lureausealing. (Linux only) 4034dbb9e0f4SMarc-André Lureau 4035dbb9e0f4SMarc-André LureauThe @option{seal} option creates a sealed-file, that will block 4036dbb9e0f4SMarc-André Lureaufurther resizing the memory ('on' by default). 4037dbb9e0f4SMarc-André Lureau 4038dbb9e0f4SMarc-André LureauThe @option{hugetlb} option specify the file to be created resides in 4039dbb9e0f4SMarc-André Lureauthe hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 4040dbb9e0f4SMarc-André Lureauthe @option{hugetlb} option, the @option{hugetlbsize} option specify 4041dbb9e0f4SMarc-André Lureauthe hugetlb page size on systems that support multiple hugetlb page 4042dbb9e0f4SMarc-André Lureausizes (it must be a power of 2 value supported by the system). 4043dbb9e0f4SMarc-André Lureau 4044dbb9e0f4SMarc-André LureauIn some versions of Linux, the @option{hugetlb} option is incompatible 4045dbb9e0f4SMarc-André Lureauwith the @option{seal} option (requires at least Linux 4.16). 4046dbb9e0f4SMarc-André Lureau 4047dbb9e0f4SMarc-André LureauPlease refer to @option{memory-backend-file} for a description of the 4048dbb9e0f4SMarc-André Lureauother options. 4049dbb9e0f4SMarc-André Lureau 405036ea3979SMarc-André LureauThe @option{share} boolean option is @var{on} by default with memfd. 405136ea3979SMarc-André Lureau 4052b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4053b9174d4fSDaniel P. Berrange 4054b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4055b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 4056b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 4057b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 4058b9174d4fSDaniel P. Berrangeentropy from and if omitted defaults to @option{/dev/random}. 4059b9174d4fSDaniel P. Berrange 4060b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4061b9174d4fSDaniel P. Berrange 4062b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4063b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 4064b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 4065b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 4066b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 4067b9174d4fSDaniel P. Berrangeto the RNG daemon. 4068b9174d4fSDaniel P. Berrange 4069e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4070e00adf6cSDaniel P. Berrange 4071e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 4072e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 4073e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 4074e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 4075e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 4076e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 4077e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 4078e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 4079e00adf6cSDaniel P. Berrange 4080e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 4081e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 4082e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 4083e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 4084e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 4085e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 4086e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 4087e00adf6cSDaniel P. Berrangeupfront and saved. 4088e00adf6cSDaniel P. Berrange 4089e1a6dc91SRichard W.M. Jones@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}] 4090e1a6dc91SRichard W.M. Jones 4091e1a6dc91SRichard W.M. JonesCreates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide 4092e1a6dc91SRichard W.M. JonesTLS support on network backends. The @option{id} parameter is a unique 4093e1a6dc91SRichard W.M. JonesID which network backends will use to access the credentials. The 4094e1a6dc91SRichard W.M. Jones@option{endpoint} is either @option{server} or @option{client} depending 4095e1a6dc91SRichard W.M. Joneson whether the QEMU network backend that uses the credentials will be 4096e1a6dc91SRichard W.M. Jonesacting as a client or as a server. For clients only, @option{username} 4097e1a6dc91SRichard W.M. Jonesis the username which will be sent to the server. If omitted 4098e1a6dc91SRichard W.M. Jonesit defaults to ``qemu''. 4099e1a6dc91SRichard W.M. Jones 4100e1a6dc91SRichard W.M. JonesThe @var{dir} parameter tells QEMU where to find the keys file. 4101e1a6dc91SRichard W.M. JonesIt is called ``@var{dir}/keys.psk'' and contains ``username:key'' 4102e1a6dc91SRichard W.M. Jonespairs. This file can most easily be created using the GnuTLS 4103e1a6dc91SRichard W.M. Jones@code{psktool} program. 4104e1a6dc91SRichard W.M. Jones 4105e1a6dc91SRichard W.M. JonesFor server endpoints, @var{dir} may also contain a file 4106e1a6dc91SRichard W.M. Jones@var{dh-params.pem} providing diffie-hellman parameters to use 4107e1a6dc91SRichard W.M. Jonesfor the TLS server. If the file is missing, QEMU will generate 4108e1a6dc91SRichard W.M. Jonesa set of DH parameters at startup. This is a computationally 4109e1a6dc91SRichard W.M. Jonesexpensive operation that consumes random pool entropy, so it is 4110e1a6dc91SRichard W.M. Jonesrecommended that a persistent set of parameters be generated 4111e1a6dc91SRichard W.M. Jonesup front and saved. 4112e1a6dc91SRichard W.M. Jones 411300e5e9dfSChristophe 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} 411485bcbc78SDaniel P. Berrange 411585bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 411685bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 411785bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 411885bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 411985bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 412085bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 412185bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 412285bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 412385bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 412485bcbc78SDaniel P. Berrange 412585bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 412685bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 412785bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 412885bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 412985bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 413085bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 413185bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 413285bcbc78SDaniel P. Berrangeupfront and saved. 413385bcbc78SDaniel P. Berrange 413485bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 413585bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 413685bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 413785bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 413885bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 413985bcbc78SDaniel P. Berrange 41401d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 41411d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 41421d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 41431d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 41441d7b5b4aSDaniel P. Berrangepassword for decryption. 41451d7b5b4aSDaniel P. Berrange 414600e5e9dfSChristophe FergeauThe @var{priority} parameter allows to override the global default 414700e5e9dfSChristophe Fergeaupriority used by gnutls. This can be useful if the system administrator 414800e5e9dfSChristophe Fergeauneeds to use a weaker set of crypto priorities for QEMU without 414900e5e9dfSChristophe Fergeaupotentially forcing the weakness onto all applications. Or conversely 415000e5e9dfSChristophe Fergeauif one wants wants a stronger default for QEMU than for all other 415100e5e9dfSChristophe Fergeauapplications, they can do this through this parameter. Its format is 415200e5e9dfSChristophe Fergeaua gnutls priority string as described at 415300e5e9dfSChristophe Fergeau@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 415400e5e9dfSChristophe Fergeau 4155338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 41567dbb11c8SYang Hongyang 41577dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 41587dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 41597dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 4160338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 4161338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 41627dbb11c8SYang Hongyang 41637dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 41647dbb11c8SYang Hongyang 41657dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 41667dbb11c8SYang Hongyang queue of the netdev (default). 41677dbb11c8SYang Hongyang 41687dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 41697dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 41707dbb11c8SYang Hongyang 41717dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 41727dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 41737dbb11c8SYang Hongyang 4174e2521f0eSZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4175f6d3afb5SZhang Chen 4176e2521f0eSZhang 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. 4177f6d3afb5SZhang Chen 417800d5c240SZhang 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] 4179d46f75b2SZhang Chen 4180d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 418100d5c240SZhang Chen@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 418200d5c240SZhang Chenfilter-redirector will redirect packet with vnet_hdr_len. 4183d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 4184d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 4185d46f75b2SZhang Chenneed to be specified. 4186d46f75b2SZhang Chen 41874b39bdceSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4188e6eee8abSZhang Chen 4189e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 4190e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 4191e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 41924b39bdceSZhang Chenclient.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4193e6eee8abSZhang Chen 4194e6eee8abSZhang Chenusage: 4195e6eee8abSZhang Chencolo secondary: 4196e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4197e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4198e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4199e6eee8abSZhang Chen 4200c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4201d3e0c032SThomas Huth 4202d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 4203d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4204d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 4205d3e0c032SThomas Huthor Wireshark. 4206d3e0c032SThomas Huth 4207aa3a7032SZhang Chen@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid}[,vnet_hdr_support] 42087dce4e6fSZhang Chen 42097dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 42107dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 42117dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 42127dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 4213aa3a7032SZhang Chenif it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len. 42147dce4e6fSZhang Chen 42157dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 42167dce4e6fSZhang Chen 42177dce4e6fSZhang Chen@example 42187dce4e6fSZhang Chen 42197dce4e6fSZhang Chenprimary: 42207dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 42217dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 42227dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 42237dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 42247dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 42257dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 42267dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 42277dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 42287dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 42297dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 42307dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 42317dce4e6fSZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0 42327dce4e6fSZhang Chen 42337dce4e6fSZhang Chensecondary: 42347dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 42357dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 42367dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 42377dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 42387dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 42397dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 42407dce4e6fSZhang Chen 42417dce4e6fSZhang Chen@end example 42427dce4e6fSZhang Chen 42437dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 42447dce4e6fSZhang Chenthe colo-compare git log. 42457dce4e6fSZhang Chen 42461653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 42471653a5f3SGonglei 42481653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 42491653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 42501653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 42511653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 42521653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 42531653a5f3SGonglei@var{queues} is 1. 42541653a5f3SGonglei 42551653a5f3SGonglei@example 42561653a5f3SGonglei 42571653a5f3SGonglei # qemu-system-x86_64 \ 42581653a5f3SGonglei [...] \ 42591653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 42601653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 42611653a5f3SGonglei [...] 42621653a5f3SGonglei@end example 42631653a5f3SGonglei 4264042cea27SGonglei@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 4265042cea27SGonglei 4266042cea27SGongleiCreates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 4267042cea27SGongleiThe @var{id} parameter is a unique ID that will be used to reference this 4268042cea27SGongleicryptodev backend from the @option{virtio-crypto} device. 4269042cea27SGongleiThe chardev should be a unix domain socket backed one. The vhost-user uses 4270042cea27SGongleia specifically defined protocol to pass vhost ioctl replacement messages 4271042cea27SGongleito an application on the other end of the socket. 4272042cea27SGongleiThe @var{queues} parameter is optional, which specify the queue number 4273042cea27SGongleiof cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 4274042cea27SGonglei 4275042cea27SGonglei@example 4276042cea27SGonglei 4277042cea27SGonglei # qemu-system-x86_64 \ 4278042cea27SGonglei [...] \ 4279042cea27SGonglei -chardev socket,id=chardev0,path=/path/to/socket \ 4280042cea27SGonglei -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 4281042cea27SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4282042cea27SGonglei [...] 4283042cea27SGonglei@end example 4284042cea27SGonglei 4285ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4286ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4287ac1d8878SDaniel P. Berrange 4288ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4289ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4290ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4291ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4292ac1d8878SDaniel P. Berrange 4293ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4294ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4295ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4296ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4297ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4298ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4299ac1d8878SDaniel P. Berrange 4300ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4301ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4302ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4303ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4304ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4305ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4306ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 430769c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4308ac1d8878SDaniel P. Berrange 4309ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4310ac1d8878SDaniel P. Berrange 4311ac1d8878SDaniel P. Berrange@example 4312ac1d8878SDaniel P. Berrange 4313ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,data=letmein,format=raw 4314ac1d8878SDaniel P. Berrange 4315ac1d8878SDaniel P. Berrange@end example 4316ac1d8878SDaniel P. Berrange 4317ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4318ac1d8878SDaniel P. Berrange 4319b43671f8SEric Blake # printf "letmein" > mypasswd.txt 4320ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 4321ac1d8878SDaniel P. Berrange 4322ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4323ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4324ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4325ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4326ac1d8878SDaniel P. Berrange 4327ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4328ac1d8878SDaniel P. Berrange 4329ac1d8878SDaniel P. Berrange@example 4330ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4331ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4332ac1d8878SDaniel P. Berrange@end example 4333ac1d8878SDaniel P. Berrange 4334ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4335ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4336ac1d8878SDaniel P. Berrange 4337ac1d8878SDaniel P. Berrange@example 4338ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4339ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4340ac1d8878SDaniel P. Berrange@end example 4341ac1d8878SDaniel P. Berrange 4342ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4343ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4344ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4345ac1d8878SDaniel P. Berrange 4346ac1d8878SDaniel P. Berrange@example 4347b43671f8SEric Blake # SECRET=$(printf "letmein" | 4348ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4349ac1d8878SDaniel P. Berrange@end example 4350ac1d8878SDaniel P. Berrange 4351ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4352ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4353ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4354ac1d8878SDaniel P. Berrange 4355ac1d8878SDaniel P. Berrange@example 4356ac1d8878SDaniel P. Berrange # $QEMU \ 4357ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4358ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4359ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4360ac1d8878SDaniel P. Berrange@end example 4361ac1d8878SDaniel P. Berrange 4362a9b4942fSBrijesh 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}] 4363a9b4942fSBrijesh Singh 4364a9b4942fSBrijesh SinghCreate a Secure Encrypted Virtualization (SEV) guest object, which can be used 4365a9b4942fSBrijesh Singhto provide the guest memory encryption support on AMD processors. 4366a9b4942fSBrijesh Singh 4367a9b4942fSBrijesh SinghWhen memory encryption is enabled, one of the physical address bit (aka the 4368a9b4942fSBrijesh SinghC-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 4369a9b4942fSBrijesh Singhis used to provide the C-bit position. The C-bit position is Host family dependent 4370a9b4942fSBrijesh Singhhence user must provide this value. On EPYC, the value should be 47. 4371a9b4942fSBrijesh Singh 4372a9b4942fSBrijesh SinghWhen memory encryption is enabled, we loose certain bits in physical address space. 4373a9b4942fSBrijesh SinghThe @option{reduced-phys-bits} is used to provide the number of bits we loose in 4374a9b4942fSBrijesh Singhphysical address space. Similar to C-bit, the value is Host family dependent. 4375a9b4942fSBrijesh SinghOn EPYC, the value should be 5. 4376a9b4942fSBrijesh Singh 4377a9b4942fSBrijesh SinghThe @option{sev-device} provides the device file to use for communicating with 4378a9b4942fSBrijesh Singhthe SEV firmware running inside AMD Secure Processor. The default device is 4379a9b4942fSBrijesh Singh'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 4380a9b4942fSBrijesh Singhcreated by CCP driver. 4381a9b4942fSBrijesh Singh 4382a9b4942fSBrijesh SinghThe @option{policy} provides the guest policy to be enforced by the SEV firmware 4383a9b4942fSBrijesh Singhand restrict what configuration and operational commands can be performed on this 4384a9b4942fSBrijesh Singhguest by the hypervisor. The policy should be provided by the guest owner and is 4385a9b4942fSBrijesh Singhbound to the guest and cannot be changed throughout the lifetime of the guest. 4386a9b4942fSBrijesh SinghThe default is 0. 4387a9b4942fSBrijesh Singh 4388a9b4942fSBrijesh SinghIf guest @option{policy} allows sharing the key with another SEV guest then 4389a9b4942fSBrijesh Singh@option{handle} can be use to provide handle of the guest from which to share 4390a9b4942fSBrijesh Singhthe key. 4391a9b4942fSBrijesh Singh 4392a9b4942fSBrijesh SinghThe @option{dh-cert-file} and @option{session-file} provides the guest owner's 4393a9b4942fSBrijesh SinghPublic Diffie-Hillman key defined in SEV spec. The PDH and session parameters 4394a9b4942fSBrijesh Singhare used for establishing a cryptographic session with the guest owner to 4395a9b4942fSBrijesh Singhnegotiate keys used for attestation. The file must be encoded in base64. 4396a9b4942fSBrijesh Singh 4397a9b4942fSBrijesh Singhe.g to launch a SEV guest 4398a9b4942fSBrijesh Singh@example 4399a9b4942fSBrijesh Singh # $QEMU \ 4400a9b4942fSBrijesh Singh ...... 4401a9b4942fSBrijesh Singh -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 4402a9b4942fSBrijesh Singh -machine ...,memory-encryption=sev0 4403a9b4942fSBrijesh Singh ..... 4404a9b4942fSBrijesh Singh 4405a9b4942fSBrijesh Singh@end example 4406b9174d4fSDaniel P. Berrange@end table 4407b9174d4fSDaniel P. Berrange 4408b9174d4fSDaniel P. BerrangeETEXI 4409b9174d4fSDaniel P. Berrange 4410b9174d4fSDaniel P. Berrange 44113dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 44123dbf2c7fSStefan WeilSTEXI 44133dbf2c7fSStefan Weil@end table 44143dbf2c7fSStefan WeilETEXI 4415