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 " s390-squash-mcss=on|off (deprecated) controls support for squashing into default css (default=off)\n" 47db588194SBrijesh Singh " memory-encryption=@var{} memory encryption object to use (default=none)\n", 4880f52a66SJan Kiszka QEMU_ARCH_ALL) 495824d651Sblueswir1STEXI 5080f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 5180f52a66SJan Kiszka@findex -machine 52585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 538bfce83aSDaniel P. Berrangeavailable machines. 548bfce83aSDaniel P. Berrange 558bfce83aSDaniel P. BerrangeFor architectures which aim to support live migration compatibility 568bfce83aSDaniel P. Berrangeacross releases, each release will introduce a new versioned machine 578bfce83aSDaniel P. Berrangetype. For example, the 2.8.0 release introduced machine types 588bfce83aSDaniel P. Berrange``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 598bfce83aSDaniel P. Berrange 608bfce83aSDaniel P. BerrangeTo allow live migration of guests from QEMU version 2.8.0, to QEMU 618bfce83aSDaniel P. Berrangeversion 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 628bfce83aSDaniel P. Berrangeand ``pc-q35-2.8'' machines too. To allow users live migrating VMs 638bfce83aSDaniel P. Berrangeto skip multiple intermediate releases when upgrading, new releases 648bfce83aSDaniel P. Berrangeof QEMU will support machine types from many previous versions. 658bfce83aSDaniel P. Berrange 668bfce83aSDaniel P. BerrangeSupported machine properties are: 6780f52a66SJan Kiszka@table @option 6880f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 6980f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 70d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 71bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 72bde4d920SThomas Huthfails to initialize. 736a48ffaaSJan Kiszka@item kernel_irqchip=on|off 7432c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 7579814179STiejun Chen@item gfx_passthru=on|off 7679814179STiejun ChenEnables IGD GFX passthrough support for the chosen machine when available. 77d1048befSDon Slutz@item vmport=on|off|auto 78d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 79d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 80d1048befSDon Slutzis on. 8139d6960aSJan Kiszka@item kvm_shadow_mem=size 8239d6960aSJan KiszkaDefines the size of the KVM shadow MMU. 83ddb97f1dSJason Baron@item dump-guest-core=on|off 84ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 858490fc78SLuiz Capitulino@item mem-merge=on|off 868490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 878490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 888490fc78SLuiz Capitulino(enabled by default). 892eb1cd07STony Krowiak@item aes-key-wrap=on|off 902eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 912eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 922eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 932eb1cd07STony Krowiak@item dea-key-wrap=on|off 942eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 952eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 962eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 9787252e1bSXiao Guangrong@item nvdimm=on|off 9887252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 99274250c3SXiao Feng Ren@item s390-squash-mcss=on|off 100274250c3SXiao Feng RenEnables or disables squashing subchannels into the default css. 101274250c3SXiao Feng RenThe default is off. 102d69969e5SHalil PasicNOTE: This property is deprecated and will be removed in future releases. 103d69969e5SHalil PasicThe ``s390-squash-mcss=on`` property has been obsoleted by allowing the 104d69969e5SHalil Pasiccssid to be chosen freely. Instead of squashing subchannels into the 105d69969e5SHalil Pasicdefault channel subsystem image for guests that do not support multiple 106d69969e5SHalil Pasicchannel subsystems, all devices can be put into the default channel 107d69969e5SHalil Pasicsubsystem image. 10816f72448SPeter Xu@item enforce-config-section=on|off 10916f72448SPeter XuIf @option{enforce-config-section} is set to @var{on}, force migration 11016f72448SPeter Xucode to send configuration section even if the machine-type sets the 11116f72448SPeter Xu@option{migration.send-configuration} property to @var{off}. 11216f72448SPeter XuNOTE: this parameter is deprecated. Please use @option{-global} 11316f72448SPeter Xu@option{migration.send-configuration}=@var{on|off} instead. 114db588194SBrijesh Singh@item memory-encryption=@var{} 115db588194SBrijesh SinghMemory encryption object to use. The default is none. 11680f52a66SJan Kiszka@end table 1175824d651Sblueswir1ETEXI 1185824d651Sblueswir1 11980f52a66SJan KiszkaHXCOMM Deprecated by -machine 12080f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 12180f52a66SJan Kiszka 1225824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 123585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 1245824d651Sblueswir1STEXI 1255824d651Sblueswir1@item -cpu @var{model} 1266616b2adSStefan Weil@findex -cpu 127585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 1285824d651Sblueswir1ETEXI 1295824d651Sblueswir1 1308d4e9146SKONRAD FredericDEF("accel", HAS_ARG, QEMU_OPTION_accel, 1318d4e9146SKONRAD Frederic "-accel [accel=]accelerator[,thread=single|multi]\n" 132d661d9a4SJustin Terry (VM) " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n" 133c97d6d2cSSergio Andres Gomez Del Real " thread=single|multi (enable multi-threaded TCG)", QEMU_ARCH_ALL) 1348d4e9146SKONRAD FredericSTEXI 1358d4e9146SKONRAD Frederic@item -accel @var{name}[,prop=@var{value}[,...]] 1368d4e9146SKONRAD Frederic@findex -accel 1378d4e9146SKONRAD FredericThis is used to enable an accelerator. Depending on the target architecture, 138d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 139bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 140bde4d920SThomas Huthfails to initialize. 1418d4e9146SKONRAD Frederic@table @option 1428d4e9146SKONRAD Frederic@item thread=single|multi 1438d4e9146SKONRAD FredericControls number of TCG threads. When the TCG is multi-threaded there will be one 1448d4e9146SKONRAD Fredericthread per vCPU therefor taking advantage of additional host cores. The default 1458d4e9146SKONRAD Fredericis to enable multi-threading where both the back-end and front-ends support it and 1468d4e9146SKONRAD Fredericno incompatible TCG features have been enabled (e.g. icount/replay). 1478d4e9146SKONRAD Frederic@end table 1488d4e9146SKONRAD FredericETEXI 1498d4e9146SKONRAD Frederic 1505824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 15112b7f57eSMichael Tokarev "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 1526be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1536be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 154ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 15558a04db1SAndre Przywara " cores= number of CPU cores on one socket\n" 15658a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 157ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 158ad96090aSBlue Swirl QEMU_ARCH_ALL) 1595824d651Sblueswir1STEXI 16012b7f57eSMichael Tokarev@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1616616b2adSStefan Weil@findex -smp 1625824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1635824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1645824d651Sblueswir1to 4. 16558a04db1SAndre PrzywaraFor the PC target, the number of @var{cores} per socket, the number 16658a04db1SAndre Przywaraof @var{threads} per cores and the total number of @var{sockets} can be 16758a04db1SAndre Przywaraspecified. Missing values will be computed. If any on the three values is 16858a04db1SAndre Przywaragiven, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 16958a04db1SAndre Przywaraspecifies the maximum number of hotpluggable CPUs. 1705824d651Sblueswir1ETEXI 1715824d651Sblueswir1 172268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 173e0ee9fd0SEduardo Habkost "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1740f203430SHe Chen "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1752d19c656SIgor Mammedov "-numa dist,src=source,dst=destination,val=distance\n" 1762d19c656SIgor Mammedov "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n", 1772d19c656SIgor Mammedov QEMU_ARCH_ALL) 178268a362cSaliguoriSTEXI 179e0ee9fd0SEduardo Habkost@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 180e0ee9fd0SEduardo Habkost@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 1810f203430SHe Chen@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 182419fcdecSIgor Mammedov@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 1836616b2adSStefan Weil@findex -numa 1844b9a5dd7SEduardo HabkostDefine a NUMA node and assign RAM and VCPUs to it. 1850f203430SHe ChenSet the NUMA distance from a source node to a destination node. 1867febe36fSPaolo Bonzini 187419fcdecSIgor MammedovLegacy VCPU assignment uses @samp{cpus} option where 1884b9a5dd7SEduardo Habkost@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 1894b9a5dd7SEduardo Habkost@samp{cpus} option represent a contiguous range of CPU indexes 1904b9a5dd7SEduardo Habkost(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 1914b9a5dd7SEduardo Habkostset of VCPUs can be represented by providing multiple @samp{cpus} 1924b9a5dd7SEduardo Habkostoptions. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 1934b9a5dd7SEduardo Habkostsplit between them. 1944b9a5dd7SEduardo Habkost 1954b9a5dd7SEduardo HabkostFor example, the following option assigns VCPUs 0, 1, 2 and 5 to 1964b9a5dd7SEduardo Habkosta NUMA node: 1974b9a5dd7SEduardo Habkost@example 1984b9a5dd7SEduardo Habkost-numa node,cpus=0-2,cpus=5 1994b9a5dd7SEduardo Habkost@end example 2004b9a5dd7SEduardo Habkost 201419fcdecSIgor Mammedov@samp{cpu} option is a new alternative to @samp{cpus} option 202419fcdecSIgor Mammedovwhich uses @samp{socket-id|core-id|thread-id} properties to assign 203419fcdecSIgor MammedovCPU objects to a @var{node} using topology layout properties of CPU. 204419fcdecSIgor MammedovThe set of properties is machine specific, and depends on used 205419fcdecSIgor Mammedovmachine type/@samp{smp} options. It could be queried with 206419fcdecSIgor Mammedov@samp{hotpluggable-cpus} monitor command. 207419fcdecSIgor Mammedov@samp{node-id} property specifies @var{node} to which CPU object 208419fcdecSIgor Mammedovwill be assigned, it's required for @var{node} to be declared 209419fcdecSIgor Mammedovwith @samp{node} option before it's used with @samp{cpu} option. 210419fcdecSIgor Mammedov 211419fcdecSIgor MammedovFor example: 212419fcdecSIgor Mammedov@example 213419fcdecSIgor Mammedov-M pc \ 214419fcdecSIgor Mammedov-smp 1,sockets=2,maxcpus=2 \ 215419fcdecSIgor Mammedov-numa node,nodeid=0 -numa node,nodeid=1 \ 216419fcdecSIgor Mammedov-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 217419fcdecSIgor Mammedov@end example 218419fcdecSIgor Mammedov 2194b9a5dd7SEduardo Habkost@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 2204b9a5dd7SEduardo Habkostassigns RAM from a given memory backend device to a node. If 2214b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 2224b9a5dd7SEduardo Habkostsplit equally between them. 2234b9a5dd7SEduardo Habkost 2244b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 2254b9a5dd7SEduardo Habkostif one node uses @samp{memdev}, all of them have to use it. 2264b9a5dd7SEduardo Habkost 2270f203430SHe Chen@var{source} and @var{destination} are NUMA node IDs. 2280f203430SHe Chen@var{distance} is the NUMA distance from @var{source} to @var{destination}. 2290f203430SHe ChenThe distance from a node to itself is always 10. If any pair of nodes is 2300f203430SHe Chengiven a distance, then all pairs must be given distances. Although, when 2310f203430SHe Chendistances are only given in one direction for each pair of nodes, then 2320f203430SHe Chenthe distances in the opposite directions are assumed to be the same. If, 2330f203430SHe Chenhowever, an asymmetrical pair of distances is given for even one node 2340f203430SHe Chenpair, then all node pairs must be provided distance values for both 2350f203430SHe Chendirections, even when they are symmetrical. When a node is unreachable 2360f203430SHe Chenfrom another node, set the pair's distance to 255. 2370f203430SHe Chen 2384b9a5dd7SEduardo HabkostNote that the -@option{numa} option doesn't allocate any of the 2394b9a5dd7SEduardo Habkostspecified resources, it just assigns existing resources to NUMA 2404b9a5dd7SEduardo Habkostnodes. This means that one still has to use the @option{-m}, 2414b9a5dd7SEduardo Habkost@option{-smp} options to allocate RAM and VCPUs respectively. 2424b9a5dd7SEduardo Habkost 243268a362cSaliguoriETEXI 244268a362cSaliguori 24510adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 24610adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 24710adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 24810adb8beSMarkus ArmbrusterSTEXI 24910adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 25010adb8beSMarkus Armbruster@findex -add-fd 25110adb8beSMarkus Armbruster 25210adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 25310adb8beSMarkus Armbruster 25410adb8beSMarkus Armbruster@table @option 25510adb8beSMarkus Armbruster@item fd=@var{fd} 25610adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 25710adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 25810adb8beSMarkus Armbruster@item set=@var{set} 25910adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 26010adb8beSMarkus Armbruster@item opaque=@var{opaque} 26110adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 26210adb8beSMarkus Armbruster@end table 26310adb8beSMarkus Armbruster 26410adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 26510adb8beSMarkus Armbruster@example 26610adb8beSMarkus Armbrusterqemu-system-i386 26710adb8beSMarkus Armbruster-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 26810adb8beSMarkus Armbruster-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 26910adb8beSMarkus Armbruster-drive file=/dev/fdset/2,index=0,media=disk 27010adb8beSMarkus Armbruster@end example 27110adb8beSMarkus ArmbrusterETEXI 27210adb8beSMarkus Armbruster 27310adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 27410adb8beSMarkus Armbruster "-set group.id.arg=value\n" 27510adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 27610adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 27710adb8beSMarkus ArmbrusterSTEXI 27810adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 27910adb8beSMarkus Armbruster@findex -set 280e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 28110adb8beSMarkus ArmbrusterETEXI 28210adb8beSMarkus Armbruster 28310adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 2843751d7c4SPaolo Bonzini "-global driver.property=value\n" 2853751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 28610adb8beSMarkus Armbruster " set a global default for a driver property\n", 28710adb8beSMarkus Armbruster QEMU_ARCH_ALL) 28810adb8beSMarkus ArmbrusterSTEXI 28910adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 2903751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 29110adb8beSMarkus Armbruster@findex -global 29210adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 29310adb8beSMarkus Armbruster 29410adb8beSMarkus Armbruster@example 2951c9f3b88SMarkus Armbrusterqemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img 29610adb8beSMarkus Armbruster@end example 29710adb8beSMarkus Armbruster 29810adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 29910adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 30010adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 3013751d7c4SPaolo Bonzini 302ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 303ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 304ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 30510adb8beSMarkus ArmbrusterETEXI 30610adb8beSMarkus Armbruster 30710adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 30810adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 309c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 31010adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 31110adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 31210adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 31310adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 31410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 31510adb8beSMarkus ArmbrusterSTEXI 316c8a6ae8bSAmos 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] 31710adb8beSMarkus Armbruster@findex -boot 31810adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 319d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 32010adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 32110adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 32210adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 323c0d9f7d0SThomas Huth@option{once}. Note that the @option{order} or @option{once} parameter 324c0d9f7d0SThomas Huthshould not be used together with the @option{bootindex} property of 325c0d9f7d0SThomas Huthdevices, since the firmware implementations normally do not support both 326c0d9f7d0SThomas Huthat the same time. 32710adb8beSMarkus Armbruster 32810adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 32910adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 33010adb8beSMarkus Armbruster 33110adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 33210adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 33310adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 33410adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 33510adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 33610adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 33710adb8beSMarkus Armbruster 33810adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 33910adb8beSMarkus Armbrusterwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 34010adb8beSMarkus Armbrusterreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 34110adb8beSMarkus Armbrustersystem support it. 34210adb8beSMarkus Armbruster 343c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 344c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 345c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 346c8a6ae8bSAmos Kong 34710adb8beSMarkus Armbruster@example 34810adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 34910adb8beSMarkus Armbrusterqemu-system-i386 -boot order=nc 35010adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 35110adb8beSMarkus Armbrusterqemu-system-i386 -boot once=d 35210adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 35310adb8beSMarkus Armbrusterqemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 35410adb8beSMarkus Armbruster@end example 35510adb8beSMarkus Armbruster 35610adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 35710adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 35810adb8beSMarkus ArmbrusterETEXI 35910adb8beSMarkus Armbruster 36010adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 36189f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 3626e1d3c1cSIgor Mammedov " configure guest RAM\n" 3630daba1f0SAlexander Graf " size: initial amount of guest memory\n" 364c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 365b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 366b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 3676e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 36810adb8beSMarkus ArmbrusterSTEXI 3699fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 37010adb8beSMarkus Armbruster@findex -m 3719fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 3729fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 3739fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 3749fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 3759fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 3769fcc0794SLuiz Capitulino 3779fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 3789fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 3799fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 3809fcc0794SLuiz Capitulino 3819fcc0794SLuiz Capitulino@example 3829fcc0794SLuiz Capitulinoqemu-system-x86_64 -m 1G,slots=3,maxmem=4G 3839fcc0794SLuiz Capitulino@end example 3849fcc0794SLuiz Capitulino 3859fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 3869fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 38710adb8beSMarkus ArmbrusterETEXI 38810adb8beSMarkus Armbruster 38910adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 39010adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 39110adb8beSMarkus ArmbrusterSTEXI 39210adb8beSMarkus Armbruster@item -mem-path @var{path} 39310adb8beSMarkus Armbruster@findex -mem-path 39410adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 39510adb8beSMarkus ArmbrusterETEXI 39610adb8beSMarkus Armbruster 39710adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 39810adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 39910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 40010adb8beSMarkus ArmbrusterSTEXI 40110adb8beSMarkus Armbruster@item -mem-prealloc 40210adb8beSMarkus Armbruster@findex -mem-prealloc 40310adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 40410adb8beSMarkus ArmbrusterETEXI 40510adb8beSMarkus Armbruster 40610adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 40710adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 40810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 40910adb8beSMarkus ArmbrusterSTEXI 41010adb8beSMarkus Armbruster@item -k @var{language} 41110adb8beSMarkus Armbruster@findex -k 41210adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 41310adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 41432945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 41510adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 41610adb8beSMarkus Armbrusterhosts. 41710adb8beSMarkus Armbruster 41810adb8beSMarkus ArmbrusterThe available layouts are: 41910adb8beSMarkus Armbruster@example 42010adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 42110adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 42210adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 42310adb8beSMarkus Armbruster@end example 42410adb8beSMarkus Armbruster 42510adb8beSMarkus ArmbrusterThe default is @code{en-us}. 42610adb8beSMarkus ArmbrusterETEXI 42710adb8beSMarkus Armbruster 42810adb8beSMarkus Armbruster 42910adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 43010adb8beSMarkus Armbruster "-audio-help print list of audio drivers and their options\n", 43110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 43210adb8beSMarkus ArmbrusterSTEXI 43310adb8beSMarkus Armbruster@item -audio-help 43410adb8beSMarkus Armbruster@findex -audio-help 43510adb8beSMarkus ArmbrusterWill show the audio subsystem help: list of drivers, tunable 43610adb8beSMarkus Armbrusterparameters. 43710adb8beSMarkus ArmbrusterETEXI 43810adb8beSMarkus Armbruster 43910adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 44010adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 44110adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 44210adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 44310adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 44410adb8beSMarkus ArmbrusterSTEXI 44510adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 44610adb8beSMarkus Armbruster@findex -soundhw 44710adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 44810adb8beSMarkus Armbrusteravailable sound hardware. 44910adb8beSMarkus Armbruster 45010adb8beSMarkus Armbruster@example 45110adb8beSMarkus Armbrusterqemu-system-i386 -soundhw sb16,adlib disk.img 45210adb8beSMarkus Armbrusterqemu-system-i386 -soundhw es1370 disk.img 45310adb8beSMarkus Armbrusterqemu-system-i386 -soundhw ac97 disk.img 45410adb8beSMarkus Armbrusterqemu-system-i386 -soundhw hda disk.img 45510adb8beSMarkus Armbrusterqemu-system-i386 -soundhw all disk.img 45610adb8beSMarkus Armbrusterqemu-system-i386 -soundhw help 45710adb8beSMarkus Armbruster@end example 45810adb8beSMarkus Armbruster 45910adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 46010adb8beSMarkus Armbrusterrequire manually specifying clocking. 46110adb8beSMarkus Armbruster 46210adb8beSMarkus Armbruster@example 46310adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 46410adb8beSMarkus Armbruster@end example 46510adb8beSMarkus ArmbrusterETEXI 46610adb8beSMarkus Armbruster 46710adb8beSMarkus ArmbrusterDEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 46810adb8beSMarkus Armbruster "-balloon virtio[,addr=str]\n" 4694060e671SThomas Huth " enable virtio balloon device (deprecated)\n", QEMU_ARCH_ALL) 47010adb8beSMarkus ArmbrusterSTEXI 47110adb8beSMarkus Armbruster@item -balloon virtio[,addr=@var{addr}] 4724060e671SThomas Huth@findex -balloon 4734060e671SThomas HuthEnable virtio balloon device, optionally with PCI address @var{addr}. This 4744060e671SThomas Huthoption is deprecated, use @option{--device virtio-balloon} instead. 47510adb8beSMarkus ArmbrusterETEXI 47610adb8beSMarkus Armbruster 47710adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 47810adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 47910adb8beSMarkus Armbruster " add device (based on driver)\n" 48010adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 48110adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 48210adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 48310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 48410adb8beSMarkus ArmbrusterSTEXI 48510adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 48610adb8beSMarkus Armbruster@findex -device 48710adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 48810adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 48910adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 49010adb8beSMarkus Armbruster@code{-device @var{driver},help}. 491f8490451SCorey Minyard 492f8490451SCorey MinyardSome drivers are: 493540c07d3SCédric Le Goater@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}] 494f8490451SCorey Minyard 495f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 496f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 497f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 498f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 499f8490451SCorey Minyard 500f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 501f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 502f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 503f8490451SCorey Minyardit. 504f8490451SCorey Minyard 5058c6fd7f3SCédric Le Goater@table @option 5068c6fd7f3SCédric Le Goater@item bmc=@var{id} 5078c6fd7f3SCédric Le GoaterThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 5088c6fd7f3SCédric Le Goater@item slave_addr=@var{val} 5098c6fd7f3SCédric Le GoaterDefine slave address to use for the BMC. The default is 0x20. 5108c6fd7f3SCédric Le Goater@item sdrfile=@var{file} 5118c6fd7f3SCédric Le Goaterfile containing raw Sensor Data Records (SDR) data. The default is none. 512540c07d3SCédric Le Goater@item fruareasize=@var{val} 513540c07d3SCédric Le Goatersize of a Field Replaceable Unit (FRU) area. The default is 1024. 514540c07d3SCédric Le Goater@item frudatafile=@var{file} 515540c07d3SCédric Le Goaterfile containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 5168c6fd7f3SCédric Le Goater@end table 5178c6fd7f3SCédric Le Goater 518f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 519f8490451SCorey Minyard 520f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 521f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 522f8490451SCorey Minyardto an external entity that provides the IPMI services. 523f8490451SCorey Minyard 524f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 525f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 526f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 527f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 528f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 529f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 530f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 531f8490451SCorey Minyardexposed to any outside network. 532f8490451SCorey Minyard 533f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 534f8490451SCorey Minyarddetails on the external interface. 535f8490451SCorey Minyard 536f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 537f8490451SCorey Minyard 538f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 539f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 540f8490451SCorey Minyard 541f8490451SCorey Minyard@table @option 542f8490451SCorey Minyard@item bmc=@var{id} 543f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 544f8490451SCorey Minyard@item ioport=@var{val} 545f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 546f8490451SCorey Minyard@item irq=@var{val} 547f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 548f8490451SCorey Minyardset this to 0. 549f8490451SCorey Minyard@end table 550f8490451SCorey Minyard 551f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 552f8490451SCorey Minyard 553f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 554f8490451SCorey Minyard0xe4 and the default interrupt is 5. 555f8490451SCorey Minyard 55610adb8beSMarkus ArmbrusterETEXI 55710adb8beSMarkus Armbruster 55810adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 5598f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 56010adb8beSMarkus Armbruster " set the name of the guest\n" 5618f480de0SDr. David Alan Gilbert " string1 sets the window title and string2 the process name (on Linux)\n" 5628f480de0SDr. David Alan Gilbert " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 5638f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 56410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 56510adb8beSMarkus ArmbrusterSTEXI 56610adb8beSMarkus Armbruster@item -name @var{name} 56710adb8beSMarkus Armbruster@findex -name 56810adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 56910adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 57010adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 57110adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 5728f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 57310adb8beSMarkus ArmbrusterETEXI 57410adb8beSMarkus Armbruster 57510adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 57610adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 57710adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 57810adb8beSMarkus ArmbrusterSTEXI 57910adb8beSMarkus Armbruster@item -uuid @var{uuid} 58010adb8beSMarkus Armbruster@findex -uuid 58110adb8beSMarkus ArmbrusterSet system UUID. 58210adb8beSMarkus ArmbrusterETEXI 58310adb8beSMarkus Armbruster 58410adb8beSMarkus ArmbrusterSTEXI 58510adb8beSMarkus Armbruster@end table 58610adb8beSMarkus ArmbrusterETEXI 58710adb8beSMarkus ArmbrusterDEFHEADING() 58810adb8beSMarkus Armbruster 589de6b4f90SMarkus ArmbrusterDEFHEADING(Block device options:) 59010adb8beSMarkus ArmbrusterSTEXI 59110adb8beSMarkus Armbruster@table @option 59210adb8beSMarkus ArmbrusterETEXI 59310adb8beSMarkus Armbruster 5945824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 595ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 596ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 5975824d651Sblueswir1STEXI 5985824d651Sblueswir1@item -fda @var{file} 599f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 6006616b2adSStefan Weil@findex -fda 6016616b2adSStefan Weil@findex -fdb 60292a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 6035824d651Sblueswir1ETEXI 6045824d651Sblueswir1 6055824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 606ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 607ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 6085824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 609ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 610ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 6115824d651Sblueswir1STEXI 6125824d651Sblueswir1@item -hda @var{file} 613f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 614f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 615f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 6166616b2adSStefan Weil@findex -hda 6176616b2adSStefan Weil@findex -hdb 6186616b2adSStefan Weil@findex -hdc 6196616b2adSStefan Weil@findex -hdd 6205824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 6215824d651Sblueswir1ETEXI 6225824d651Sblueswir1 6235824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 624ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 625ad96090aSBlue Swirl QEMU_ARCH_ALL) 6265824d651Sblueswir1STEXI 6275824d651Sblueswir1@item -cdrom @var{file} 6286616b2adSStefan Weil@findex -cdrom 6295824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 6305824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 6315824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 6325824d651Sblueswir1ETEXI 6335824d651Sblueswir1 63442e5f393SMarkus ArmbrusterDEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 63542e5f393SMarkus Armbruster "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 63642e5f393SMarkus Armbruster " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 63742e5f393SMarkus Armbruster " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n" 63842e5f393SMarkus Armbruster " [,driver specific parameters...]\n" 63942e5f393SMarkus Armbruster " configure a block backend\n", QEMU_ARCH_ALL) 640dfaca464SKevin WolfSTEXI 641dfaca464SKevin Wolf@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 642dfaca464SKevin Wolf@findex -blockdev 643dfaca464SKevin Wolf 644370e8328SKevin WolfDefine a new block driver node. Some of the options apply to all block drivers, 645370e8328SKevin Wolfother options are only accepted for a specific block driver. See below for a 646370e8328SKevin Wolflist of generic options and options for the most common block drivers. 647370e8328SKevin Wolf 648370e8328SKevin WolfOptions that expect a reference to another node (e.g. @code{file}) can be 649370e8328SKevin Wolfgiven in two ways. Either you specify the node name of an already existing node 650370e8328SKevin Wolf(file=@var{node-name}), or you define a new node inline, adding options 651370e8328SKevin Wolffor the referenced node after a dot (file.filename=@var{path},file.aio=native). 652370e8328SKevin Wolf 653370e8328SKevin WolfA block driver node created with @option{-blockdev} can be used for a guest 654370e8328SKevin Wolfdevice by specifying its node name for the @code{drive} property in a 655370e8328SKevin Wolf@option{-device} argument that defines a block device. 656dfaca464SKevin Wolf 657dfaca464SKevin Wolf@table @option 658dfaca464SKevin Wolf@item Valid options for any block driver node: 659dfaca464SKevin Wolf 660dfaca464SKevin Wolf@table @code 661dfaca464SKevin Wolf@item driver 662dfaca464SKevin WolfSpecifies the block driver to use for the given node. 663dfaca464SKevin Wolf@item node-name 664dfaca464SKevin WolfThis defines the name of the block driver node by which it will be referenced 665dfaca464SKevin Wolflater. The name must be unique, i.e. it must not match the name of a different 666dfaca464SKevin Wolfblock driver node, or (if you use @option{-drive} as well) the ID of a drive. 667dfaca464SKevin Wolf 668dfaca464SKevin WolfIf no node name is specified, it is automatically generated. The generated node 669dfaca464SKevin Wolfname is not intended to be predictable and changes between QEMU invocations. 670dfaca464SKevin WolfFor the top level, an explicit node name must be specified. 671dfaca464SKevin Wolf@item read-only 672dfaca464SKevin WolfOpen the node read-only. Guest write attempts will fail. 673dfaca464SKevin Wolf@item cache.direct 674dfaca464SKevin WolfThe host page cache can be avoided with @option{cache.direct=on}. This will 675dfaca464SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform an 676dfaca464SKevin Wolfinternal copy of the data. 677dfaca464SKevin Wolf@item cache.no-flush 678dfaca464SKevin WolfIn case you don't care about data integrity over host failures, you can use 679dfaca464SKevin Wolf@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 680dfaca464SKevin Wolfany data to the disk but can instead keep things in cache. If anything goes 681dfaca464SKevin Wolfwrong, like your host losing power, the disk storage getting disconnected 682dfaca464SKevin Wolfaccidentally, etc. your image will most probably be rendered unusable. 683dfaca464SKevin Wolf@item discard=@var{discard} 684dfaca464SKevin Wolf@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 685dfaca464SKevin Wolfwhether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 686dfaca464SKevin Wolfignored or passed to the filesystem. Some machine types may not support 687dfaca464SKevin Wolfdiscard requests. 688dfaca464SKevin Wolf@item detect-zeroes=@var{detect-zeroes} 689dfaca464SKevin Wolf@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 690dfaca464SKevin Wolfconversion of plain zero writes by the OS to driver specific optimized 691dfaca464SKevin Wolfzero write commands. You may even choose "unmap" if @var{discard} is set 692dfaca464SKevin Wolfto "unmap" to allow a zero write to be converted to an @code{unmap} operation. 693dfaca464SKevin Wolf@end table 694dfaca464SKevin Wolf 695370e8328SKevin Wolf@item Driver-specific options for @code{file} 696370e8328SKevin Wolf 697370e8328SKevin WolfThis is the protocol-level block driver for accessing regular files. 698370e8328SKevin Wolf 699370e8328SKevin Wolf@table @code 700370e8328SKevin Wolf@item filename 701370e8328SKevin WolfThe path to the image file in the local filesystem 702370e8328SKevin Wolf@item aio 703370e8328SKevin WolfSpecifies the AIO backend (threads/native, default: threads) 7041878eaffSFam Zheng@item locking 7051878eaffSFam ZhengSpecifies whether the image file is protected with Linux OFD / POSIX locks. The 7061878eaffSFam Zhengdefault is to use the Linux Open File Descriptor API if available, otherwise no 7071878eaffSFam Zhenglock is applied. (auto/on/off, default: auto) 708370e8328SKevin Wolf@end table 709370e8328SKevin WolfExample: 710370e8328SKevin Wolf@example 711370e8328SKevin Wolf-blockdev driver=file,node-name=disk,filename=disk.img 712370e8328SKevin Wolf@end example 713370e8328SKevin Wolf 714370e8328SKevin Wolf@item Driver-specific options for @code{raw} 715370e8328SKevin Wolf 716370e8328SKevin WolfThis is the image format block driver for raw 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@end table 724370e8328SKevin WolfExample 1: 725370e8328SKevin Wolf@example 726370e8328SKevin Wolf-blockdev driver=file,node-name=disk_file,filename=disk.img 727370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file=disk_file 728370e8328SKevin Wolf@end example 729370e8328SKevin WolfExample 2: 730370e8328SKevin Wolf@example 731370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 732370e8328SKevin Wolf@end example 733370e8328SKevin Wolf 734370e8328SKevin Wolf@item Driver-specific options for @code{qcow2} 735370e8328SKevin Wolf 736370e8328SKevin WolfThis is the image format block driver for qcow2 images. It is usually 737370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 738370e8328SKevin Wolf 739370e8328SKevin Wolf@table @code 740370e8328SKevin Wolf@item file 741370e8328SKevin WolfReference to or definition of the data source block driver node 742370e8328SKevin Wolf(e.g. a @code{file} driver node) 743370e8328SKevin Wolf 744370e8328SKevin Wolf@item backing 745370e8328SKevin WolfReference to or definition of the backing file block device (default is taken 7464f7be280SMax Reitzfrom the image file). It is allowed to pass @code{null} here in order to disable 7474f7be280SMax Reitzthe default backing file. 748370e8328SKevin Wolf 749370e8328SKevin Wolf@item lazy-refcounts 750370e8328SKevin WolfWhether to enable the lazy refcounts feature (on/off; default is taken from the 751370e8328SKevin Wolfimage file) 752370e8328SKevin Wolf 753370e8328SKevin Wolf@item cache-size 754370e8328SKevin WolfThe maximum total size of the L2 table and refcount block caches in bytes 755370e8328SKevin Wolf(default: 1048576 bytes or 8 clusters, whichever is larger) 756370e8328SKevin Wolf 757370e8328SKevin Wolf@item l2-cache-size 758370e8328SKevin WolfThe maximum size of the L2 table cache in bytes 759370e8328SKevin Wolf(default: 4/5 of the total cache size) 760370e8328SKevin Wolf 761370e8328SKevin Wolf@item refcount-cache-size 762370e8328SKevin WolfThe maximum size of the refcount block cache in bytes 763370e8328SKevin Wolf(default: 1/5 of the total cache size) 764370e8328SKevin Wolf 765370e8328SKevin Wolf@item cache-clean-interval 766370e8328SKevin WolfClean unused entries in the L2 and refcount caches. The interval is in seconds. 767370e8328SKevin WolfThe default value is 0 and it disables this feature. 768370e8328SKevin Wolf 769370e8328SKevin Wolf@item pass-discard-request 770370e8328SKevin WolfWhether discard requests to the qcow2 device should be forwarded to the data 771370e8328SKevin Wolfsource (on/off; default: on if discard=unmap is specified, off otherwise) 772370e8328SKevin Wolf 773370e8328SKevin Wolf@item pass-discard-snapshot 774370e8328SKevin WolfWhether discard requests for the data source should be issued when a snapshot 775370e8328SKevin Wolfoperation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 776370e8328SKevin Wolfdefault: on) 777370e8328SKevin Wolf 778370e8328SKevin Wolf@item pass-discard-other 779370e8328SKevin WolfWhether discard requests for the data source should be issued on other 780370e8328SKevin Wolfoccasions where a cluster gets freed (on/off; default: off) 781370e8328SKevin Wolf 782370e8328SKevin Wolf@item overlap-check 783370e8328SKevin WolfWhich overlap checks to perform for writes to the image 784370e8328SKevin Wolf(none/constant/cached/all; default: cached). For details or finer 785370e8328SKevin Wolfgranularity control refer to the QAPI documentation of @code{blockdev-add}. 786370e8328SKevin Wolf@end table 787370e8328SKevin Wolf 788370e8328SKevin WolfExample 1: 789370e8328SKevin Wolf@example 790370e8328SKevin Wolf-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 791370e8328SKevin Wolf-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 792370e8328SKevin Wolf@end example 793370e8328SKevin WolfExample 2: 794370e8328SKevin Wolf@example 795370e8328SKevin Wolf-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 796370e8328SKevin Wolf@end example 797370e8328SKevin Wolf 798370e8328SKevin Wolf@item Driver-specific options for other drivers 799370e8328SKevin WolfPlease refer to the QAPI documentation of the @code{blockdev-add} QMP command. 800370e8328SKevin Wolf 801dfaca464SKevin Wolf@end table 802dfaca464SKevin Wolf 803dfaca464SKevin WolfETEXI 80442e5f393SMarkus Armbruster 8055824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 8065824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 80792196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 808*b0083267SKevin Wolf " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 809d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 810fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 8112f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 8123e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 8133e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 8143e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 8153e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 8162024c1dfSBenoît Canet " [[,iops_size=is]]\n" 81776f4afb4SAlberto Garcia " [[,group=g]]\n" 818ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 8195824d651Sblueswir1STEXI 8205824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 8216616b2adSStefan Weil@findex -drive 8225824d651Sblueswir1 823dfaca464SKevin WolfDefine a new drive. This includes creating a block driver node (the backend) as 824dfaca464SKevin Wolfwell as a guest device, and is mostly a shortcut for defining the corresponding 825dfaca464SKevin Wolf@option{-blockdev} and @option{-device} options. 826dfaca464SKevin Wolf 827dfaca464SKevin Wolf@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 828dfaca464SKevin Wolfaddition, it knows the following options: 8295824d651Sblueswir1 830b3f046c2SKevin Wolf@table @option 8315824d651Sblueswir1@item file=@var{file} 8325824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 8335824d651Sblueswir1this drive. If the filename contains comma, you must double it 8345824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 8350f5314a2SRonnie Sahlberg 8360f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 8370f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 8385824d651Sblueswir1@item if=@var{interface} 8395824d651Sblueswir1This option defines on which type on interface the drive is connected. 840ed1fcd00SCraig JellickAvailable types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 8415824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 8425824d651Sblueswir1These options define where is connected the drive by defining the bus number and 8435824d651Sblueswir1the unit id. 8445824d651Sblueswir1@item index=@var{index} 8455824d651Sblueswir1This option defines where is connected the drive by using an index in the list 8465824d651Sblueswir1of available connectors of a given interface type. 8475824d651Sblueswir1@item media=@var{media} 8485824d651Sblueswir1This option defines the type of the media: disk or cdrom. 8495824d651Sblueswir1@item snapshot=@var{snapshot} 8509d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 8519d85d557SMichael Tokarev(see @option{-snapshot}). 8525824d651Sblueswir1@item cache=@var{cache} 853dfaca464SKevin Wolf@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 854dfaca464SKevin Wolfand controls how the host cache is used to access block data. This is a 855dfaca464SKevin Wolfshortcut that sets the @option{cache.direct} and @option{cache.no-flush} 856dfaca464SKevin Wolfoptions (as in @option{-blockdev}), and additionally @option{cache.writeback}, 857dfaca464SKevin Wolfwhich provides a default for the @option{write-cache} option of block guest 858dfaca464SKevin Wolfdevices (as in @option{-device}). The modes correspond to the following 859dfaca464SKevin Wolfsettings: 860dfaca464SKevin Wolf 861dfaca464SKevin Wolf@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 862dfaca464SKevin Wolf@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 863dfaca464SKevin Wolf@c and the HTML output. 864dfaca464SKevin Wolf@example 865dfaca464SKevin Wolf@ │ cache.writeback cache.direct cache.no-flush 866dfaca464SKevin Wolf─────────────┼───────────────────────────────────────────────── 867dfaca464SKevin Wolfwriteback │ on off off 868dfaca464SKevin Wolfnone │ on on off 869dfaca464SKevin Wolfwritethrough │ off off off 870dfaca464SKevin Wolfdirectsync │ off on off 871dfaca464SKevin Wolfunsafe │ on off on 872dfaca464SKevin Wolf@end example 873dfaca464SKevin Wolf 874dfaca464SKevin WolfThe default mode is @option{cache=writeback}. 875dfaca464SKevin Wolf 8765c6c3a6cSChristoph Hellwig@item aio=@var{aio} 8775c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 8785824d651Sblueswir1@item format=@var{format} 8795824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 880d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 8815824d651Sblueswir1an untrusted format header. 882ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 883ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 884ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 885ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 886ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 887ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 888fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 889fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 890fb0490f6SStefan Hajnoczifile sectors into the image file. 89101f9cfabSStefan Hajnoczi@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 89201f9cfabSStefan HajnocziSpecify bandwidth throttling limits in bytes per second, either for all request 89301f9cfabSStefan Hajnoczitypes or for reads or writes only. Small values can lead to timeouts or hangs 89401f9cfabSStefan Hajnocziinside the guest. A safe minimum for disks is 2 MB/s. 89501f9cfabSStefan Hajnoczi@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 89601f9cfabSStefan HajnocziSpecify bursts in bytes per second, either for all request types or for reads 89701f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 89801f9cfabSStefan Hajnoczitemporarily. 89901f9cfabSStefan Hajnoczi@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 90001f9cfabSStefan HajnocziSpecify request rate limits in requests per second, either for all request 90101f9cfabSStefan Hajnoczitypes or for reads or writes only. 90201f9cfabSStefan Hajnoczi@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 90301f9cfabSStefan HajnocziSpecify bursts in requests per second, either for all request types or for reads 90401f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 90501f9cfabSStefan Hajnoczitemporarily. 90601f9cfabSStefan Hajnoczi@item iops_size=@var{is} 90701f9cfabSStefan HajnocziLet every @var{is} bytes of a request count as a new request for iops 90801f9cfabSStefan Hajnoczithrottling purposes. Use this option to prevent guests from circumventing iops 90901f9cfabSStefan Hajnoczilimits by sending fewer but larger requests. 91001f9cfabSStefan Hajnoczi@item group=@var{g} 91101f9cfabSStefan HajnocziJoin a throttling quota group with given name @var{g}. All drives that are 91201f9cfabSStefan Hajnoczimembers of the same group are accounted for together. Use this option to 91301f9cfabSStefan Hajnocziprevent guests from circumventing throttling limits by using many small disks 91401f9cfabSStefan Hajnocziinstead of a single larger disk. 9155824d651Sblueswir1@end table 9165824d651Sblueswir1 917dfaca464SKevin WolfBy default, the @option{cache.writeback=on} mode is used. It will report data 918a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 919a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 920a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 921a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 922a13e5e05SKevin Wolfdata corruption. 9235824d651Sblueswir1 924dfaca464SKevin WolfFor such guests, you should consider using @option{cache.writeback=off}. This 925a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 926a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 927a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 9285824d651Sblueswir1 929dfaca464SKevin WolfWhen using the @option{-snapshot} option, unsafe caching is always used. 930016f5cf6SAlexander Graf 931fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 932fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 933fb0490f6SStefan Hajnocziis off. 934fb0490f6SStefan Hajnoczi 9355824d651Sblueswir1Instead of @option{-cdrom} you can use: 9365824d651Sblueswir1@example 9373804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=cdrom 9385824d651Sblueswir1@end example 9395824d651Sblueswir1 9405824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 9415824d651Sblueswir1use: 9425824d651Sblueswir1@example 9433804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,media=disk 9443804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,media=disk 9453804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=disk 9463804da9dSStefan Weilqemu-system-i386 -drive file=file,index=3,media=disk 9475824d651Sblueswir1@end example 9485824d651Sblueswir1 949587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 950587ed6beSCorey Bryant@example 951587ed6beSCorey Bryantqemu-system-i386 952587ed6beSCorey Bryant-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 953587ed6beSCorey Bryant-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 954587ed6beSCorey Bryant-drive file=/dev/fdset/2,index=0,media=disk 955587ed6beSCorey Bryant@end example 956587ed6beSCorey Bryant 9575824d651Sblueswir1You can connect a CDROM to the slave of ide0: 9585824d651Sblueswir1@example 9593804da9dSStefan Weilqemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 9605824d651Sblueswir1@end example 9615824d651Sblueswir1 9625824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 9635824d651Sblueswir1@example 9643804da9dSStefan Weilqemu-system-i386 -drive if=ide,index=1,media=cdrom 9655824d651Sblueswir1@end example 9665824d651Sblueswir1 9675824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 9685824d651Sblueswir1@example 9693804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,if=floppy 9703804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,if=floppy 9715824d651Sblueswir1@end example 9725824d651Sblueswir1 9735824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 9745824d651Sblueswir1incremented: 9755824d651Sblueswir1@example 9763804da9dSStefan Weilqemu-system-i386 -drive file=a -drive file=b" 9775824d651Sblueswir1@end example 9785824d651Sblueswir1is interpreted like: 9795824d651Sblueswir1@example 9803804da9dSStefan Weilqemu-system-i386 -hda a -hdb b 9815824d651Sblueswir1@end example 9825824d651Sblueswir1ETEXI 9835824d651Sblueswir1 9845824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 985ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 986ad96090aSBlue Swirl QEMU_ARCH_ALL) 9875824d651Sblueswir1STEXI 9884e257e5eSKevin Wolf@item -mtdblock @var{file} 9896616b2adSStefan Weil@findex -mtdblock 9904e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 9915824d651Sblueswir1ETEXI 9925824d651Sblueswir1 9935824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 994ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 9955824d651Sblueswir1STEXI 9964e257e5eSKevin Wolf@item -sd @var{file} 9976616b2adSStefan Weil@findex -sd 9984e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 9995824d651Sblueswir1ETEXI 10005824d651Sblueswir1 10015824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 1002ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 10035824d651Sblueswir1STEXI 10044e257e5eSKevin Wolf@item -pflash @var{file} 10056616b2adSStefan Weil@findex -pflash 10064e257e5eSKevin WolfUse @var{file} as a parallel flash image. 10075824d651Sblueswir1ETEXI 10085824d651Sblueswir1 10095824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 1010ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 1011ad96090aSBlue Swirl QEMU_ARCH_ALL) 10125824d651Sblueswir1STEXI 10135824d651Sblueswir1@item -snapshot 10146616b2adSStefan Weil@findex -snapshot 10155824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 10165824d651Sblueswir1the raw disk image you use is not written back. You can however force 10175824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 10185824d651Sblueswir1ETEXI 10195824d651Sblueswir1 102074db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 10212c30dd74SAneesh Kumar K.V "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 1022b96feb2cSTobias Schramm " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n" 1023b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1024b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1025b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1026b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1027b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-size=is]]\n", 102874db920cSGautham R Shenoy QEMU_ARCH_ALL) 102974db920cSGautham R Shenoy 103074db920cSGautham R ShenoySTEXI 103174db920cSGautham R Shenoy 1032b96feb2cSTobias 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}] 103374db920cSGautham R Shenoy@findex -fsdev 10347c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 10357c92a3d2SAneesh Kumar K.V@table @option 10367c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 10377c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 1038f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 10397c92a3d2SAneesh Kumar K.V@item id=@var{id} 10407c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 10417c92a3d2SAneesh Kumar K.V@item path=@var{path} 10427c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 10437c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 10447c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 10457c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 10462c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 10477c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1048b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 10492c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 10507c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 10512c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 10522c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 10537c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 10547c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1055d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 1056f67e3ffdSM. Mohan Kumaronly for local fsdriver. Other fsdrivers (like handle, proxy) don't take 1057d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 10587c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 10597c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 10607c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 10617c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 10627c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 10632c74c2cbSM. Mohan Kumar@item readonly 10642c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 10652c74c2cbSM. Mohan Kumarread-write access is given. 106684a87cc4SM. Mohan Kumar@item socket=@var{socket} 106784a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 106884a87cc4SM. Mohan Kumarwith virtfs-proxy-helper 1069f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 1070f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 1071f67e3ffdSM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 1072f67e3ffdSM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 1073b96feb2cSTobias Schramm@item fmode=@var{fmode} 1074b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1075b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1076b96feb2cSTobias Schramm@item dmode=@var{dmode} 1077b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1078b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 107974db920cSGautham R Shenoy@end table 10807c92a3d2SAneesh Kumar K.V 10817c92a3d2SAneesh Kumar K.V-fsdev option is used along with -device driver "virtio-9p-pci". 10827c92a3d2SAneesh Kumar K.V@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 10837c92a3d2SAneesh Kumar K.VOptions for virtio-9p-pci driver are: 10847c92a3d2SAneesh Kumar K.V@table @option 10857c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 10867c92a3d2SAneesh Kumar K.VSpecifies the id value specified along with -fsdev option 10877c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 10887c92a3d2SAneesh Kumar K.VSpecifies the tag name to be used by the guest to mount this export point 10897c92a3d2SAneesh Kumar K.V@end table 10907c92a3d2SAneesh Kumar K.V 109174db920cSGautham R ShenoyETEXI 109274db920cSGautham R Shenoy 10933d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 10942c30dd74SAneesh Kumar K.V "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 1095b96feb2cSTobias Schramm " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n", 10963d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 10973d54abc7SGautham R Shenoy 10983d54abc7SGautham R ShenoySTEXI 10993d54abc7SGautham R Shenoy 1100b96feb2cSTobias 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}] 11013d54abc7SGautham R Shenoy@findex -virtfs 11023d54abc7SGautham R Shenoy 11037c92a3d2SAneesh Kumar K.VThe general form of a Virtual File system pass-through options are: 11047c92a3d2SAneesh Kumar K.V@table @option 11057c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 11067c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 1107f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 11087c92a3d2SAneesh Kumar K.V@item id=@var{id} 11097c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 11107c92a3d2SAneesh Kumar K.V@item path=@var{path} 11117c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 11127c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 11137c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 11147c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 11152c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 11167c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1117b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 11182c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 11197c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 11202c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 11212c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 11227c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 11237c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1124d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 1125f67e3ffdSM. Mohan Kumarfor local fsdriver. Other fsdrivers (like handle, proxy) don't take security 1126d9b36a6eSM. Mohan Kumarmodel as a parameter. 11277c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 11287c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 11297c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 11307c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 11317c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 11322c74c2cbSM. Mohan Kumar@item readonly 11332c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 11342c74c2cbSM. Mohan Kumarread-write access is given. 113584a87cc4SM. Mohan Kumar@item socket=@var{socket} 113684a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 113784a87cc4SM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 113884a87cc4SM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 1139f67e3ffdSM. Mohan Kumar@item sock_fd 1140f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 1141f67e3ffdSM. Mohan Kumardescriptor for interfacing with virtfs-proxy-helper 1142b96feb2cSTobias Schramm@item fmode=@var{fmode} 1143b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1144b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1145b96feb2cSTobias Schramm@item dmode=@var{dmode} 1146b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1147b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 11483d54abc7SGautham R Shenoy@end table 11493d54abc7SGautham R ShenoyETEXI 11503d54abc7SGautham R Shenoy 11519db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 11529db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 11539db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 11549db221aeSAneesh Kumar K.VSTEXI 11559db221aeSAneesh Kumar K.V@item -virtfs_synth 11569db221aeSAneesh Kumar K.V@findex -virtfs_synth 11579db221aeSAneesh Kumar K.VCreate synthetic file system image 11589db221aeSAneesh Kumar K.VETEXI 11599db221aeSAneesh Kumar K.V 116061d70487SMarkus ArmbrusterDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 116161d70487SMarkus Armbruster "-iscsi [user=user][,password=password]\n" 116261d70487SMarkus Armbruster " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 116361d70487SMarkus Armbruster " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 116461d70487SMarkus Armbruster " [,timeout=timeout]\n" 116561d70487SMarkus Armbruster " iSCSI session parameters\n", QEMU_ARCH_ALL) 116661d70487SMarkus Armbruster 11675824d651Sblueswir1STEXI 116844743148SMarkus Armbruster@item -iscsi 116944743148SMarkus Armbruster@findex -iscsi 117044743148SMarkus ArmbrusterConfigure iSCSI session parameters. 117144743148SMarkus ArmbrusterETEXI 117244743148SMarkus Armbruster 117344743148SMarkus ArmbrusterSTEXI 11745824d651Sblueswir1@end table 11755824d651Sblueswir1ETEXI 11765824d651Sblueswir1DEFHEADING() 11775824d651Sblueswir1 1178de6b4f90SMarkus ArmbrusterDEFHEADING(USB options:) 117910adb8beSMarkus ArmbrusterSTEXI 118010adb8beSMarkus Armbruster@table @option 118110adb8beSMarkus ArmbrusterETEXI 118210adb8beSMarkus Armbruster 118310adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 1184a358a3afSThomas Huth "-usb enable the USB driver (if it is not used by default yet)\n", 118510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 118610adb8beSMarkus ArmbrusterSTEXI 118710adb8beSMarkus Armbruster@item -usb 118810adb8beSMarkus Armbruster@findex -usb 1189a358a3afSThomas HuthEnable the USB driver (if it is not used by default yet). 119010adb8beSMarkus ArmbrusterETEXI 119110adb8beSMarkus Armbruster 119210adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 119310adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 119410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 119510adb8beSMarkus ArmbrusterSTEXI 119610adb8beSMarkus Armbruster 119710adb8beSMarkus Armbruster@item -usbdevice @var{devname} 119810adb8beSMarkus Armbruster@findex -usbdevice 1199a358a3afSThomas HuthAdd the USB device @var{devname}. Note that this option is deprecated, 1200a358a3afSThomas Huthplease use @code{-device usb-...} instead. @xref{usb_devices}. 120110adb8beSMarkus Armbruster 120210adb8beSMarkus Armbruster@table @option 120310adb8beSMarkus Armbruster 120410adb8beSMarkus Armbruster@item mouse 120510adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 120610adb8beSMarkus Armbruster 120710adb8beSMarkus Armbruster@item tablet 120810adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 120910adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 121010adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 121110adb8beSMarkus Armbruster 121210adb8beSMarkus Armbruster@item braille 121310adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 121410adb8beSMarkus Armbrusteror fake device. 121510adb8beSMarkus Armbruster 121610adb8beSMarkus Armbruster@end table 121710adb8beSMarkus ArmbrusterETEXI 121810adb8beSMarkus Armbruster 121910adb8beSMarkus ArmbrusterSTEXI 122010adb8beSMarkus Armbruster@end table 122110adb8beSMarkus ArmbrusterETEXI 122210adb8beSMarkus ArmbrusterDEFHEADING() 122310adb8beSMarkus Armbruster 1224de6b4f90SMarkus ArmbrusterDEFHEADING(Display options:) 12255824d651Sblueswir1STEXI 12265824d651Sblueswir1@table @option 12275824d651Sblueswir1ETEXI 12285824d651Sblueswir1 12291472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 12301472a95bSJes Sorensen "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 12314867e47cSElie Tournier " [,window_close=on|off][,gl=on|core|es|off]\n" 1232f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 1233f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 1234f04ec5afSRobert Ho "-display curses\n" 1235f04ec5afSRobert Ho "-display none" 1236f04ec5afSRobert Ho " select display type\n" 1237f04ec5afSRobert Ho "The default display is equivalent to\n" 1238f04ec5afSRobert Ho#if defined(CONFIG_GTK) 1239f04ec5afSRobert Ho "\t\"-display gtk\"\n" 1240f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 1241f04ec5afSRobert Ho "\t\"-display sdl\"\n" 1242f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 1243f04ec5afSRobert Ho "\t\"-display cocoa\"\n" 1244f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 1245f04ec5afSRobert Ho "\t\"-vnc localhost:0,to=99,id=default\"\n" 1246f04ec5afSRobert Ho#else 1247f04ec5afSRobert Ho "\t\"-display none\"\n" 1248f04ec5afSRobert Ho#endif 1249f04ec5afSRobert Ho , QEMU_ARCH_ALL) 12501472a95bSJes SorensenSTEXI 12511472a95bSJes Sorensen@item -display @var{type} 12521472a95bSJes Sorensen@findex -display 12531472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 12541472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 12551472a95bSJes Sorensen@table @option 12561472a95bSJes Sorensen@item sdl 12571472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 12581472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 12591472a95bSJes Sorensen@item curses 12601472a95bSJes SorensenDisplay video output via curses. For graphics device models which 12611472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 12621472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 12631472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 12641472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 12654171d32eSJes Sorensen@item none 12664171d32eSJes SorensenDo not display video output. The guest will still see an emulated 12674171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 12684171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 12694171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 12704171d32eSJes Sorensenthe destination of the serial and parallel port data. 1271881249c7SJan Kiszka@item gtk 1272881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 1273881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 1274881249c7SJan Kiszkaruntime. 12753264ff12SJes Sorensen@item vnc 12763264ff12SJes SorensenStart a VNC server on display <arg> 12771472a95bSJes Sorensen@end table 12781472a95bSJes SorensenETEXI 12791472a95bSJes Sorensen 12805824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 1281ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1282ad96090aSBlue Swirl QEMU_ARCH_ALL) 12835824d651Sblueswir1STEXI 12845824d651Sblueswir1@item -nographic 12856616b2adSStefan Weil@findex -nographic 1286dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1287dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1288dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1289dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1290dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1291dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1292dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1293dc0a3e44SColin Lordswitching between the console and monitor. 12945824d651Sblueswir1ETEXI 12955824d651Sblueswir1 12965824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1297f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1298ad96090aSBlue Swirl QEMU_ARCH_ALL) 12995824d651Sblueswir1STEXI 13005824d651Sblueswir1@item -curses 1301b8f490ebSMarkus Armbruster@findex -curses 1302dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1303dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1304dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1305dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1306dc0a3e44SColin Lordmode. 13075824d651Sblueswir1ETEXI 13085824d651Sblueswir1 13095824d651Sblueswir1DEF("no-frame", 0, QEMU_OPTION_no_frame, 1310ad96090aSBlue Swirl "-no-frame open SDL window without a frame and window decorations\n", 1311ad96090aSBlue Swirl QEMU_ARCH_ALL) 13125824d651Sblueswir1STEXI 13135824d651Sblueswir1@item -no-frame 13146616b2adSStefan Weil@findex -no-frame 13155824d651Sblueswir1Do not use decorations for SDL windows and start them using the whole 13165824d651Sblueswir1available screen space. This makes the using QEMU in a dedicated desktop 13175824d651Sblueswir1workspace more convenient. 13185824d651Sblueswir1ETEXI 13195824d651Sblueswir1 13205824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1321ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1322ad96090aSBlue Swirl QEMU_ARCH_ALL) 13235824d651Sblueswir1STEXI 13245824d651Sblueswir1@item -alt-grab 13256616b2adSStefan Weil@findex -alt-grab 1326de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1327de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 13285824d651Sblueswir1ETEXI 13295824d651Sblueswir1 13300ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1331ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1332ad96090aSBlue Swirl QEMU_ARCH_ALL) 13330ca9f8a4SDustin KirklandSTEXI 13340ca9f8a4SDustin Kirkland@item -ctrl-grab 13356616b2adSStefan Weil@findex -ctrl-grab 1336de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1337de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 13380ca9f8a4SDustin KirklandETEXI 13390ca9f8a4SDustin Kirkland 13405824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1341ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 13425824d651Sblueswir1STEXI 13435824d651Sblueswir1@item -no-quit 13446616b2adSStefan Weil@findex -no-quit 13455824d651Sblueswir1Disable SDL window close capability. 13465824d651Sblueswir1ETEXI 13475824d651Sblueswir1 13485824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1349f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 13505824d651Sblueswir1STEXI 13515824d651Sblueswir1@item -sdl 13526616b2adSStefan Weil@findex -sdl 13535824d651Sblueswir1Enable SDL. 13545824d651Sblueswir1ETEXI 13555824d651Sblueswir1 135629b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 135727af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 135827af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 135927af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1360fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 136127af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 136227af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 136327af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 136427af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 136527af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 136627af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 136727af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 136827af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 13695ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 13705ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 13717b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 137227af7788SYonit Halperin " enable spice\n" 137327af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 137427af7788SYonit Halperin QEMU_ARCH_ALL) 137529b0040bSGerd HoffmannSTEXI 137629b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 137729b0040bSGerd Hoffmann@findex -spice 137829b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 137929b0040bSGerd Hoffmann 138029b0040bSGerd Hoffmann@table @option 138129b0040bSGerd Hoffmann 138229b0040bSGerd Hoffmann@item port=<nr> 1383c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 138429b0040bSGerd Hoffmann 1385333b0eebSGerd Hoffmann@item addr=<addr> 1386333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1387333b0eebSGerd Hoffmann 1388333b0eebSGerd Hoffmann@item ipv4 1389f9cfd655SMarkus Armbruster@itemx ipv6 1390f9cfd655SMarkus Armbruster@itemx unix 1391333b0eebSGerd HoffmannForce using the specified IP version. 1392333b0eebSGerd Hoffmann 139329b0040bSGerd Hoffmann@item password=<secret> 139429b0040bSGerd HoffmannSet the password you need to authenticate. 139529b0040bSGerd Hoffmann 139648b3ed0aSMarc-André Lureau@item sasl 139748b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 139848b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 139948b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 140048b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 140148b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 140248b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 140348b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 140448b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 140548b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 140648b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 140748b3ed0aSMarc-André Lureaucredentials. 140848b3ed0aSMarc-André Lureau 140929b0040bSGerd Hoffmann@item disable-ticketing 141029b0040bSGerd HoffmannAllow client connects without authentication. 141129b0040bSGerd Hoffmann 1412d4970b07SHans de Goede@item disable-copy-paste 1413d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1414d4970b07SHans de Goede 14155ad24e5fSHans de Goede@item disable-agent-file-xfer 14165ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 14175ad24e5fSHans de Goede 1418c448e855SGerd Hoffmann@item tls-port=<nr> 1419c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1420c448e855SGerd Hoffmann 1421c448e855SGerd Hoffmann@item x509-dir=<dir> 1422c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1423c448e855SGerd Hoffmann 1424c448e855SGerd Hoffmann@item x509-key-file=<file> 1425f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1426f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1427f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1428f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1429c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1430c448e855SGerd Hoffmann 1431c448e855SGerd Hoffmann@item tls-ciphers=<list> 1432c448e855SGerd HoffmannSpecify which ciphers to use. 1433c448e855SGerd Hoffmann 1434d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1435f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 143617b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 143717b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 143817b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 143917b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 144017b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 144117b6dea0SGerd Hoffmann 14429f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 14439f04e09eSYonit HalperinConfigure image compression (lossless). 14449f04e09eSYonit HalperinDefault is auto_glz. 14459f04e09eSYonit Halperin 14469f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1447f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 14489f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 14499f04e09eSYonit HalperinDefault is auto. 14509f04e09eSYonit Halperin 145184a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 145293ca519eSLi ZhijianConfigure video stream detection. Default is off. 145384a23f25SGerd Hoffmann 145484a23f25SGerd Hoffmann@item agent-mouse=[on|off] 145584a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 145684a23f25SGerd Hoffmann 145784a23f25SGerd Hoffmann@item playback-compression=[on|off] 145884a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 145984a23f25SGerd Hoffmann 14608c957053SYonit Halperin@item seamless-migration=[on|off] 14618c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 14628c957053SYonit Halperin 1463474114b7SGerd Hoffmann@item gl=[on|off] 1464474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1465474114b7SGerd Hoffmann 14667b525508SMarc-André Lureau@item rendernode=<file> 14677b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 14687b525508SMarc-André Lureauthe first available. (Since 2.9) 14697b525508SMarc-André Lureau 147029b0040bSGerd Hoffmann@end table 147129b0040bSGerd HoffmannETEXI 147229b0040bSGerd Hoffmann 14735824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1474ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1475ad96090aSBlue Swirl QEMU_ARCH_ALL) 14765824d651Sblueswir1STEXI 14775824d651Sblueswir1@item -portrait 14786616b2adSStefan Weil@findex -portrait 14795824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 14805824d651Sblueswir1ETEXI 14815824d651Sblueswir1 14829312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 14839312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 14849312805dSVasily Khoruzhick QEMU_ARCH_ALL) 14859312805dSVasily KhoruzhickSTEXI 14866265c43bSMarkus Armbruster@item -rotate @var{deg} 14879312805dSVasily Khoruzhick@findex -rotate 14889312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 14899312805dSVasily KhoruzhickETEXI 14909312805dSVasily Khoruzhick 14915824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1492a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1493ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 14945824d651Sblueswir1STEXI 1495e4558dcaSmalc@item -vga @var{type} 14966616b2adSStefan Weil@findex -vga 14975824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1498b3f046c2SKevin Wolf@table @option 14995824d651Sblueswir1@item cirrus 15005824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 15015824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 15025824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 150341eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 15045824d651Sblueswir1@item std 15055824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 15065824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 15075824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 150841eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 15095824d651Sblueswir1@item vmware 15105824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 15115824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 15125824d651Sblueswir1card. 1513a19cbfb3SGerd Hoffmann@item qxl 1514a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1515a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1516a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 151733632788SMark Cave-Ayland@item tcx 151833632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 151933632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 152033632788SMark Cave-Aylandfixed resolution of 1024x768. 152133632788SMark Cave-Ayland@item cg3 152233632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 152333632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 152433632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1525a94f0c5cSGerd Hoffmann@item virtio 1526a94f0c5cSGerd HoffmannVirtio VGA card. 15275824d651Sblueswir1@item none 15285824d651Sblueswir1Disable VGA card. 15295824d651Sblueswir1@end table 15305824d651Sblueswir1ETEXI 15315824d651Sblueswir1 15325824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1533ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 15345824d651Sblueswir1STEXI 15355824d651Sblueswir1@item -full-screen 15366616b2adSStefan Weil@findex -full-screen 15375824d651Sblueswir1Start in full screen. 15385824d651Sblueswir1ETEXI 15395824d651Sblueswir1 15405824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1541ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1542ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 15435824d651Sblueswir1STEXI 154495d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 15456616b2adSStefan Weil@findex -g 154695d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 15475824d651Sblueswir1ETEXI 15485824d651Sblueswir1 15495824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1550f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 15515824d651Sblueswir1STEXI 15525824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 15536616b2adSStefan Weil@findex -vnc 1554dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1555dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1556dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1557dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1558dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1559a358a3afSThomas Huth(option @option{-device usb-tablet}). When using the VNC display, you 1560dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1561dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 15625824d651Sblueswir1 1563b3f046c2SKevin Wolf@table @option 15645824d651Sblueswir1 156599a9a52aSRobert Ho@item to=@var{L} 156699a9a52aSRobert Ho 156799a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 156899a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 156999a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 157099a9a52aSRobert Hoapplication. By default, to=0. 157199a9a52aSRobert Ho 15725824d651Sblueswir1@item @var{host}:@var{d} 15735824d651Sblueswir1 15745824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 15755824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 15765824d651Sblueswir1be omitted in which case the server will accept connections from any host. 15775824d651Sblueswir1 15784e257e5eSKevin Wolf@item unix:@var{path} 15795824d651Sblueswir1 15805824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 15815824d651Sblueswir1location of a unix socket to listen for connections on. 15825824d651Sblueswir1 15835824d651Sblueswir1@item none 15845824d651Sblueswir1 15855824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 15865824d651Sblueswir1can be used to later start the VNC server. 15875824d651Sblueswir1 15885824d651Sblueswir1@end table 15895824d651Sblueswir1 15905824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 15915824d651Sblueswir1separated by commas. Valid options are 15925824d651Sblueswir1 1593b3f046c2SKevin Wolf@table @option 15945824d651Sblueswir1 15955824d651Sblueswir1@item reverse 15965824d651Sblueswir1 15975824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 15985824d651Sblueswir1client is specified by the @var{display}. For reverse network 15995824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 16005824d651Sblueswir1is a TCP port number, not a display number. 16015824d651Sblueswir1 16027536ee4bSTim Hardeck@item websocket 16037536ee4bSTim Hardeck 16047536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1605275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 1606275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 1607275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 1608275e0d61SDaniel P. Berrange 1609275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 1610275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 1611275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 1612275e0d61SDaniel P. Berrange 16133e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 16143e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 16153e305e4aSDaniel P. Berrangerequires encrypted client connections. 16167536ee4bSTim Hardeck 16175824d651Sblueswir1@item password 16185824d651Sblueswir1 16195824d651Sblueswir1Require that password based authentication is used for client connections. 162086ee5bc3SMichal Novotny 162186ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 162286ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 162386ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 162486ee5bc3SMichal Novotny"vnc" or "spice". 162586ee5bc3SMichal Novotny 162686ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 162786ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 162886ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 162986ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 163086ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 163186ee5bc3SMichal Novotnydate and time). 163286ee5bc3SMichal Novotny 163386ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 163486ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 16355824d651Sblueswir1 16363e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 16373e305e4aSDaniel P. Berrange 16383e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 16393e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 16403e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 16413e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 16423e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 16433e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 16443e305e4aSDaniel P. Berrange 16453e305e4aSDaniel P. BerrangeThe @option{tls-creds} parameter obsoletes the @option{tls}, 16463e305e4aSDaniel P. Berrange@option{x509}, and @option{x509verify} options, and as such 16473e305e4aSDaniel P. Berrangeit is not permitted to set both new and old type options at 16483e305e4aSDaniel P. Berrangethe same time. 16493e305e4aSDaniel P. Berrange 16505824d651Sblueswir1@item tls 16515824d651Sblueswir1 16525824d651Sblueswir1Require that client use TLS when communicating with the VNC server. This 16535824d651Sblueswir1uses anonymous TLS credentials so is susceptible to a man-in-the-middle 16545824d651Sblueswir1attack. It is recommended that this option be combined with either the 16554e257e5eSKevin Wolf@option{x509} or @option{x509verify} options. 16565824d651Sblueswir1 16573e305e4aSDaniel P. BerrangeThis option is now deprecated in favor of using the @option{tls-creds} 16583e305e4aSDaniel P. Berrangeargument. 16593e305e4aSDaniel P. Berrange 16605824d651Sblueswir1@item x509=@var{/path/to/certificate/dir} 16615824d651Sblueswir1 16625824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 16635824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 16645824d651Sblueswir1to the client. It is recommended that a password be set on the VNC server 16655824d651Sblueswir1to provide authentication of the client when this is used. The path following 16665824d651Sblueswir1this option specifies where the x509 certificates are to be loaded from. 16675824d651Sblueswir1See the @ref{vnc_security} section for details on generating certificates. 16685824d651Sblueswir1 16693e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 16703e305e4aSDaniel P. Berrangeargument. 16713e305e4aSDaniel P. Berrange 16725824d651Sblueswir1@item x509verify=@var{/path/to/certificate/dir} 16735824d651Sblueswir1 16745824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 16755824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 16765824d651Sblueswir1to the client, and request that the client send its own x509 certificate. 16775824d651Sblueswir1The server will validate the client's certificate against the CA certificate, 16785824d651Sblueswir1and reject clients when validation fails. If the certificate authority is 16795824d651Sblueswir1trusted, this is a sufficient authentication mechanism. You may still wish 16805824d651Sblueswir1to set a password on the VNC server as a second authentication layer. The 16815824d651Sblueswir1path following this option specifies where the x509 certificates are to 16825824d651Sblueswir1be loaded from. See the @ref{vnc_security} section for details on generating 16835824d651Sblueswir1certificates. 16845824d651Sblueswir1 16853e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 16863e305e4aSDaniel P. Berrangeargument. 16873e305e4aSDaniel P. Berrange 16885824d651Sblueswir1@item sasl 16895824d651Sblueswir1 16905824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 16915824d651Sblueswir1The exact choice of authentication method used is controlled from the 16925824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 16935824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 16945824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 16955824d651Sblueswir1to make it search alternate locations for the service config. 16965824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 16975824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 16985824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 16995824d651Sblueswir1ensures a data encryption preventing compromise of authentication 17005824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 17015824d651Sblueswir1SASL authentication. 17025824d651Sblueswir1 17035824d651Sblueswir1@item acl 17045824d651Sblueswir1 17055824d651Sblueswir1Turn on access control lists for checking of the x509 client certificate 17065824d651Sblueswir1and SASL party. For x509 certs, the ACL check is made against the 17075824d651Sblueswir1certificate's distinguished name. This is something that looks like 17085824d651Sblueswir1@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 17095824d651Sblueswir1made against the username, which depending on the SASL plugin, may 17105824d651Sblueswir1include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 17115824d651Sblueswir1When the @option{acl} flag is set, the initial access list will be 17125824d651Sblueswir1empty, with a @code{deny} policy. Thus no one will be allowed to 17135824d651Sblueswir1use the VNC server until the ACLs have been loaded. This can be 17145824d651Sblueswir1achieved using the @code{acl} monitor command. 17155824d651Sblueswir1 17166f9c78c1SCorentin Chary@item lossy 17176f9c78c1SCorentin Chary 17186f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 17196f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 17206f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 17216f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 17226f9c78c1SCorentin Chary 172380e0c8c3SCorentin Chary@item non-adaptive 172480e0c8c3SCorentin Chary 172580e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 172680e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 172780e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 172861cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 17299d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 173080e0c8c3SCorentin Charylike Tight. 173180e0c8c3SCorentin Chary 17328cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 17338cf36489SGerd Hoffmann 17348cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 17358cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 17368cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 17378cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 17388cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 17398cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 17408cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 17418cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 17428cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 1743b65ee4faSStefan Weilspec but is traditional QEMU behavior. 17448cf36489SGerd Hoffmann 1745c5ce8333SGerd Hoffmann@item key-delay-ms 1746c5ce8333SGerd Hoffmann 1747c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 1748d3b0db6dSAlexander GrafDefault is 10. Keyboards are low-bandwidth devices, so this slowdown 1749c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 1750c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 1751c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 1752c5ce8333SGerd Hoffmann 17535824d651Sblueswir1@end table 17545824d651Sblueswir1ETEXI 17555824d651Sblueswir1 17565824d651Sblueswir1STEXI 17575824d651Sblueswir1@end table 17585824d651Sblueswir1ETEXI 1759a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 17605824d651Sblueswir1 1761de6b4f90SMarkus ArmbrusterARCHHEADING(i386 target only:, QEMU_ARCH_I386) 17625824d651Sblueswir1STEXI 17635824d651Sblueswir1@table @option 17645824d651Sblueswir1ETEXI 17655824d651Sblueswir1 17665824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1767ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1768ad96090aSBlue Swirl QEMU_ARCH_I386) 17695824d651Sblueswir1STEXI 17705824d651Sblueswir1@item -win2k-hack 17716616b2adSStefan Weil@findex -win2k-hack 17725824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 17735824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 17745824d651Sblueswir1slows down the IDE transfers). 17755824d651Sblueswir1ETEXI 17765824d651Sblueswir1 17771ed2fc1fSJan KiszkaHXCOMM Deprecated by -rtc 1778ad96090aSBlue SwirlDEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 17795824d651Sblueswir1 17805824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1781ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1782ad96090aSBlue Swirl QEMU_ARCH_I386) 17835824d651Sblueswir1STEXI 17845824d651Sblueswir1@item -no-fd-bootchk 17856616b2adSStefan Weil@findex -no-fd-bootchk 17864eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 17875824d651Sblueswir1be needed to boot from old floppy disks. 17885824d651Sblueswir1ETEXI 17895824d651Sblueswir1 17905824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1791f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 17925824d651Sblueswir1STEXI 17935824d651Sblueswir1@item -no-acpi 17946616b2adSStefan Weil@findex -no-acpi 17955824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 17965824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 17975824d651Sblueswir1only). 17985824d651Sblueswir1ETEXI 17995824d651Sblueswir1 18005824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1801ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 18025824d651Sblueswir1STEXI 18035824d651Sblueswir1@item -no-hpet 18046616b2adSStefan Weil@findex -no-hpet 18055824d651Sblueswir1Disable HPET support. 18065824d651Sblueswir1ETEXI 18075824d651Sblueswir1 18085824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1809104bf02eSMichael 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" 1810ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 18115824d651Sblueswir1STEXI 18125824d651Sblueswir1@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}]...] 18136616b2adSStefan Weil@findex -acpitable 18145824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 1815104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 1816104bf02eSMichael TokarevACPI headers (possible overridden by other options). 1817104bf02eSMichael TokarevFor data=, only data 1818104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 1819104bf02eSMichael Tokarevcommand line. 1820ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 1821ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 1822ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 1823ae123749SLaszlo Ersekspec. 18245824d651Sblueswir1ETEXI 18255824d651Sblueswir1 1826b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1827b6f6e3d3Saliguori "-smbios file=binary\n" 1828ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 1829b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1830b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 1831ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 1832b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1833b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 1834b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 1835b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1836b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 1837b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 1838b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1839b155eb1dSGabriel L. Somlo " [,sku=str]\n" 1840b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 1841b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1842b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 1843b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 1844b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 18453ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 1846b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 1847c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1848b6f6e3d3SaliguoriSTEXI 1849b6f6e3d3Saliguori@item -smbios file=@var{binary} 18506616b2adSStefan Weil@findex -smbios 1851b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 1852b6f6e3d3Saliguori 185384351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1854b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 1855b6f6e3d3Saliguori 1856b6f6e3d3Saliguori@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}] 1857b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 1858b155eb1dSGabriel L. Somlo 1859b155eb1dSGabriel 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}] 1860b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 1861b155eb1dSGabriel L. Somlo 1862b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1863b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 1864b155eb1dSGabriel L. Somlo 1865b155eb1dSGabriel 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}] 1866b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 1867b155eb1dSGabriel L. Somlo 18683ebd6cc8SGabriel 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}] 1869b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 1870b6f6e3d3SaliguoriETEXI 1871b6f6e3d3Saliguori 18725824d651Sblueswir1STEXI 18735824d651Sblueswir1@end table 18745824d651Sblueswir1ETEXI 1875c70a01e4SMarkus ArmbrusterDEFHEADING() 18765824d651Sblueswir1 1877de6b4f90SMarkus ArmbrusterDEFHEADING(Network options:) 18785824d651Sblueswir1STEXI 18795824d651Sblueswir1@table @option 18805824d651Sblueswir1ETEXI 18815824d651Sblueswir1 1882ad196a9dSJan KiszkaHXCOMM Legacy slirp options (now moved to -net user): 1883ad196a9dSJan Kiszka#ifdef CONFIG_SLIRP 1884ad96090aSBlue SwirlDEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1885ad96090aSBlue SwirlDEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1886ad96090aSBlue SwirlDEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1887ad196a9dSJan Kiszka#ifndef _WIN32 1888ad96090aSBlue SwirlDEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1889ad196a9dSJan Kiszka#endif 1890ad196a9dSJan Kiszka#endif 1891ad196a9dSJan Kiszka 18926a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 18935824d651Sblueswir1#ifdef CONFIG_SLIRP 18940b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 18950b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 18960b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 1897f18d1375SBenjamin Drung " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 1898f18d1375SBenjamin Drung " [,tftp=dir][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1899ad196a9dSJan Kiszka#ifndef _WIN32 1900c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 1901ad196a9dSJan Kiszka#endif 19026a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 19036a8b4a5bSThomas Huth " its DHCP server and optional services\n" 19045824d651Sblueswir1#endif 19055824d651Sblueswir1#ifdef _WIN32 19066a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 19076a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 19085824d651Sblueswir1#else 19096a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 1910584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 19116a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 191269e87b32SJason Wang " [,poll-us=n]\n" 19136a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 1914584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 1915a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1916a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1917a7c36ee4SCorey Bryant " to deconfigure it\n" 1918ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 1919a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1920a7c36ee4SCorey Bryant " configure it\n" 19215824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 19222ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1923ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1924f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1925ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1926ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 192782b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 19285430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 19295430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 193082b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 19312ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1932ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 193369e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 193469e87b32SJason Wang " spent on busy polling for vhost net\n" 19356a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 19366a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 19376a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 19386a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 19390df0ff6dSMark McLoughlin#endif 19403fb69aa1SAnton Ivanov#ifdef __linux__ 19416a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 19426a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 19436a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 19446a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 19456a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 19466a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 19473fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 19482f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 19493fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 19503fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 19513fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 19523fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 19533fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 19543fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 19553952651aSGonglei " use 'srcport=' to specify source udp port\n" 19563fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 19573fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 19583fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 19593fb69aa1SAnton Ivanov " well as a weak security measure\n" 19603fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 19613fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 19623fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 19633fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 19643fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 19653fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 19663fb69aa1SAnton Ivanov#endif 19676a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 19686a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 19696a8b4a5bSThomas Huth " using a socket connection\n" 19706a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 19716a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 19723a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 19736a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 19746a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 19756a8b4a5bSThomas Huth " using an UDP tunnel\n" 19765824d651Sblueswir1#ifdef CONFIG_VDE 19776a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 19786a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 19796a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 19805824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 19815824d651Sblueswir1 " ownership and permissions for communication port.\n" 19825824d651Sblueswir1#endif 198358952137SVincenzo Maffione#ifdef CONFIG_NETMAP 19846a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 198558952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 198658952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 198758952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 198858952137SVincenzo Maffione#endif 1989253dc14cSThomas Huth#ifdef CONFIG_POSIX 19906a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 19916a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 1992253dc14cSThomas Huth#endif 199318d65d22SThomas Huth "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 1994af1a5c3eSThomas Huth " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 199578cd6f7bSThomas HuthDEF("nic", HAS_ARG, QEMU_OPTION_nic, 199678cd6f7bSThomas Huth "--nic [tap|bridge|" 199778cd6f7bSThomas Huth#ifdef CONFIG_SLIRP 199878cd6f7bSThomas Huth "user|" 199978cd6f7bSThomas Huth#endif 200078cd6f7bSThomas Huth#ifdef __linux__ 200178cd6f7bSThomas Huth "l2tpv3|" 200278cd6f7bSThomas Huth#endif 200378cd6f7bSThomas Huth#ifdef CONFIG_VDE 200478cd6f7bSThomas Huth "vde|" 200578cd6f7bSThomas Huth#endif 200678cd6f7bSThomas Huth#ifdef CONFIG_NETMAP 200778cd6f7bSThomas Huth "netmap|" 200878cd6f7bSThomas Huth#endif 200978cd6f7bSThomas Huth#ifdef CONFIG_POSIX 201078cd6f7bSThomas Huth "vhost-user|" 201178cd6f7bSThomas Huth#endif 201278cd6f7bSThomas Huth "socket][,option][,...][mac=macaddr]\n" 201378cd6f7bSThomas Huth " initialize an on-board / default host NIC (using MAC address\n" 201478cd6f7bSThomas Huth " macaddr) and connect it to the given host network backend\n" 201578cd6f7bSThomas Huth "--nic none use it alone to have zero network devices (the default is to\n" 201678cd6f7bSThomas Huth " provided a 'user' network connection)\n", 201778cd6f7bSThomas Huth QEMU_ARCH_ALL) 20186a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 2019af1a5c3eSThomas Huth "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 20200e60a82dSThomas Huth " configure or create an on-board (or machine default) NIC and\n" 2021af1a5c3eSThomas Huth " connect it to hub 0 (please use -nic unless you need a hub)\n" 20226a8b4a5bSThomas Huth "-net [" 2023a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 2024a1ea458fSMark McLoughlin "user|" 2025a1ea458fSMark McLoughlin#endif 2026a1ea458fSMark McLoughlin "tap|" 2027a7c36ee4SCorey Bryant "bridge|" 2028a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 2029a1ea458fSMark McLoughlin "vde|" 2030a1ea458fSMark McLoughlin#endif 203158952137SVincenzo Maffione#ifdef CONFIG_NETMAP 203258952137SVincenzo Maffione "netmap|" 203358952137SVincenzo Maffione#endif 2034af1a5c3eSThomas Huth "socket][,option][,option][,...]\n" 20356a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 20366a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 20375824d651Sblueswir1STEXI 2038abbbb035SThomas Huth@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 2039abbbb035SThomas Huth@findex -nic 2040abbbb035SThomas HuthThis option is a shortcut for configuring both the on-board (default) guest 2041abbbb035SThomas HuthNIC hardware and the host network backend in one go. The host backend options 2042abbbb035SThomas Huthare the same as with the corresponding @option{-netdev} options below. 2043abbbb035SThomas HuthThe guest NIC model can be set with @option{model=@var{modelname}}. 2044abbbb035SThomas HuthUse @option{model=help} to list the available device types. 2045abbbb035SThomas HuthThe hardware MAC address can be set with @option{mac=@var{macaddr}}. 2046abbbb035SThomas Huth 2047abbbb035SThomas HuthThe following two example do exactly the same, to show how @option{-nic} can 2048abbbb035SThomas Huthbe used to shorten the command line length (note that the e1000 is the default 2049abbbb035SThomas Huthon i386, so the @option{model=e1000} parameter could even be omitted here, too): 2050abbbb035SThomas Huth@example 2051abbbb035SThomas Huthqemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 2052abbbb035SThomas Huthqemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 2053abbbb035SThomas Huth@end example 2054abbbb035SThomas Huth 2055abbbb035SThomas Huth@item -nic none 2056abbbb035SThomas HuthIndicate that no network devices should be configured. It is used to override 2057abbbb035SThomas Huththe default configuration (default NIC with ``user'' host network backend) 2058abbbb035SThomas Huthwhich is activated if no other networking options are provided. 20595824d651Sblueswir1 206008d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 2061b8f490ebSMarkus Armbruster@findex -netdev 2062abbbb035SThomas HuthConfigure user mode host network backend which requires no administrator 2063ad196a9dSJan Kiszkaprivilege to run. Valid options are: 20645824d651Sblueswir1 2065b3f046c2SKevin Wolf@table @option 206608d12022SStefan Hajnoczi@item id=@var{id} 2067ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 2068ad196a9dSJan Kiszka 2069abbbb035SThomas Huth@item ipv4=on|off and ipv6=on|off 2070abbbb035SThomas HuthSpecify that either IPv4 or IPv6 must be enabled. If neither is specified 2071abbbb035SThomas Huthboth protocols are enabled. 20720b11c036SSamuel Thibault 2073c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 2074c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 2075c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 2076b0b36e5dSBrad Hards10.0.2.0/24. 2077c92ef6a2SJan Kiszka 2078c92ef6a2SJan Kiszka@item host=@var{addr} 2079c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 2080c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 2081ad196a9dSJan Kiszka 2082d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 2083d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 2084d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 2085d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 2086d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 20877aac531eSYann Bordenave 2088d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 20897aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 20907aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 20917aac531eSYann Bordenave 2092c54ed5bcSJan Kiszka@item restrict=on|off 2093caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 2094ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 2095caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 2096ad196a9dSJan Kiszka 2097ad196a9dSJan Kiszka@item hostname=@var{name} 209863d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 2099ad196a9dSJan Kiszka 2100c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 2101c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 2102b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2103c92ef6a2SJan Kiszka 2104c92ef6a2SJan Kiszka@item dns=@var{addr} 2105c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 2106c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 2107c92ef6a2SJan Kiszkai.e. x.x.x.3. 2108c92ef6a2SJan Kiszka 2109d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 21107aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 21117aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 21127aac531eSYann Bordenavenetwork, i.e. xxxx::3. 21137aac531eSYann Bordenave 211463d2960bSKlaus Stengel@item dnssearch=@var{domain} 211563d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 211663d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 211763d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 211863d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 211963d2960bSKlaus Stengelcan not be resolved. 212063d2960bSKlaus Stengel 212163d2960bSKlaus StengelExample: 212263d2960bSKlaus Stengel@example 2123abbbb035SThomas Huthqemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 212463d2960bSKlaus Stengel@end example 212563d2960bSKlaus Stengel 2126f18d1375SBenjamin Drung@item domainname=@var{domain} 2127f18d1375SBenjamin DrungSpecifies the client domain name reported by the built-in DHCP server. 2128f18d1375SBenjamin Drung 2129ad196a9dSJan Kiszka@item tftp=@var{dir} 2130ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 2131ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 2132ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 2133c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 2134ad196a9dSJan Kiszka 2135ad196a9dSJan Kiszka@item bootfile=@var{file} 2136ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 2137ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 2138ad196a9dSJan Kiszkaa guest from a local directory. 2139ad196a9dSJan Kiszka 2140ad196a9dSJan KiszkaExample (using pxelinux): 2141ad196a9dSJan Kiszka@example 2142abbbb035SThomas Huthqemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \ 2143abbbb035SThomas Huth -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2144ad196a9dSJan Kiszka@end example 2145ad196a9dSJan Kiszka 2146c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 2147ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 2148ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 2149c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 2150c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 2151ad196a9dSJan Kiszka 2152ad196a9dSJan KiszkaIn the guest Windows OS, the line: 2153ad196a9dSJan Kiszka@example 2154ad196a9dSJan Kiszka10.0.2.4 smbserver 2155ad196a9dSJan Kiszka@end example 2156ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2157ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2158ad196a9dSJan Kiszka 2159ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2160ad196a9dSJan Kiszka 2161e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 2162ad196a9dSJan Kiszka 21633c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2164c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 2165c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 2166c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 21673c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 21683c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 2169c92ef6a2SJan Kiszkaused. This option can be given multiple times. 2170ad196a9dSJan Kiszka 2171ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 2172ad196a9dSJan Kiszkascreen 0, use the following: 2173ad196a9dSJan Kiszka 2174ad196a9dSJan Kiszka@example 2175ad196a9dSJan Kiszka# on the host 2176abbbb035SThomas Huthqemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 2177ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 2178ad196a9dSJan Kiszkaxterm -display :1 2179ad196a9dSJan Kiszka@end example 2180ad196a9dSJan Kiszka 2181ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 2182ad196a9dSJan Kiszkathe guest, use the following: 2183ad196a9dSJan Kiszka 2184ad196a9dSJan Kiszka@example 2185ad196a9dSJan Kiszka# on the host 2186abbbb035SThomas Huthqemu-system-i386 -nic user,hostfwd=tcp::5555-:23 2187ad196a9dSJan Kiszkatelnet localhost 5555 2188ad196a9dSJan Kiszka@end example 2189ad196a9dSJan Kiszka 2190ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 2191ad196a9dSJan Kiszkaconnect to the guest telnet server. 2192ad196a9dSJan Kiszka 2193c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2194f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 21953c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 2196b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 2197b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 2198b412eb61SAlexander Graf 219943ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 2200b412eb61SAlexander Graflifetime, like in the following example: 2201b412eb61SAlexander Graf 2202b412eb61SAlexander Graf@example 2203b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2204b412eb61SAlexander Graf# the guest accesses it 2205abbbb035SThomas Huthqemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 2206b412eb61SAlexander Graf@end example 2207b412eb61SAlexander Graf 2208b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 220943ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 2210b412eb61SAlexander Graf 2211b412eb61SAlexander Graf@example 2212b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2213b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 2214abbbb035SThomas Huthqemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2215b412eb61SAlexander Graf@end example 2216ad196a9dSJan Kiszka 2217ad196a9dSJan Kiszka@end table 2218ad196a9dSJan Kiszka 2219ad196a9dSJan KiszkaNote: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 2220ad196a9dSJan Kiszkaprocessed and applied to -net user. Mixing them with the new configuration 2221ad196a9dSJan Kiszkasyntax gives undefined results. Their use for new applications is discouraged 2222ad196a9dSJan Kiszkaas they will be removed from future versions. 22235824d651Sblueswir1 2224584613eaSAlexey 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}] 2225abbbb035SThomas HuthConfigure a host TAP network backend with ID @var{id}. 2226a7c36ee4SCorey Bryant 2227a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 22285824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2229a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 2230a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 2231a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2232a7c36ee4SCorey Bryantto disable script execution. 2233a7c36ee4SCorey Bryant 2234a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 2235584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 2236584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 2237584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 2238a7c36ee4SCorey Bryant 2239a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 2240a7c36ee4SCorey Bryantopened host TAP interface. 2241a7c36ee4SCorey Bryant 2242a7c36ee4SCorey BryantExamples: 22435824d651Sblueswir1 22445824d651Sblueswir1@example 2245a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 2246abbbb035SThomas Huthqemu-system-i386 linux.img -nic tap 22475824d651Sblueswir1@end example 22485824d651Sblueswir1 22495824d651Sblueswir1@example 2250a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 2251a7c36ee4SCorey Bryant#to a TAP device 22523804da9dSStefan Weilqemu-system-i386 linux.img \ 225374f78b99SThomas Huth -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 225474f78b99SThomas Huth -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 22555824d651Sblueswir1@end example 22565824d651Sblueswir1 2257a7c36ee4SCorey Bryant@example 2258a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2259a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2260abbbb035SThomas Huthqemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \ 2261abbbb035SThomas Huth -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 2262a7c36ee4SCorey Bryant@end example 2263a7c36ee4SCorey Bryant 226408d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2265a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 2266a7c36ee4SCorey Bryant 2267a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 2268a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 2269420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 2270a7c36ee4SCorey Bryantdevice is @file{br0}. 2271a7c36ee4SCorey Bryant 2272a7c36ee4SCorey BryantExamples: 2273a7c36ee4SCorey Bryant 2274a7c36ee4SCorey Bryant@example 2275a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2276a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2277abbbb035SThomas Huthqemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 2278a7c36ee4SCorey Bryant@end example 2279a7c36ee4SCorey Bryant 2280a7c36ee4SCorey Bryant@example 2281a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2282a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 2283abbbb035SThomas Huthqemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 2284a7c36ee4SCorey Bryant@end example 2285a7c36ee4SCorey Bryant 228608d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 22875824d651Sblueswir1 2288abbbb035SThomas HuthThis host network backend can be used to connect the guest's network to 2289abbbb035SThomas Huthanother QEMU virtual machine using a TCP socket connection. If @option{listen} 2290abbbb035SThomas Huthis specified, QEMU waits for incoming connections on @var{port} 22915824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 22925824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 22935824d651Sblueswir1specifies an already opened TCP socket. 22945824d651Sblueswir1 22955824d651Sblueswir1Example: 22965824d651Sblueswir1@example 22975824d651Sblueswir1# launch a first QEMU instance 22983804da9dSStefan Weilqemu-system-i386 linux.img \ 2299abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2300abbbb035SThomas Huth -netdev socket,id=n1,listen=:1234 2301abbbb035SThomas Huth# connect the network of this instance to the network of the first instance 23023804da9dSStefan Weilqemu-system-i386 linux.img \ 2303abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2304abbbb035SThomas Huth -netdev socket,id=n2,connect=127.0.0.1:1234 23055824d651Sblueswir1@end example 23065824d651Sblueswir1 230708d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 23085824d651Sblueswir1 2309abbbb035SThomas HuthConfigure a socket host network backend to share the guest's network traffic 2310abbbb035SThomas Huthwith another QEMU virtual machines using a UDP multicast socket, effectively 2311abbbb035SThomas Huthmaking a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 23125824d651Sblueswir1NOTES: 23135824d651Sblueswir1@enumerate 23145824d651Sblueswir1@item 23155824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 23165824d651Sblueswir1correct multicast setup for these hosts). 23175824d651Sblueswir1@item 23185824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 23195824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 23205824d651Sblueswir1@item 23215824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 23225824d651Sblueswir1@end enumerate 23235824d651Sblueswir1 23245824d651Sblueswir1Example: 23255824d651Sblueswir1@example 23265824d651Sblueswir1# launch one QEMU instance 23273804da9dSStefan Weilqemu-system-i386 linux.img \ 2328abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2329abbbb035SThomas Huth -netdev socket,id=n1,mcast=230.0.0.1:1234 23305824d651Sblueswir1# launch another QEMU instance on same "bus" 23313804da9dSStefan Weilqemu-system-i386 linux.img \ 2332abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2333abbbb035SThomas Huth -netdev socket,id=n2,mcast=230.0.0.1:1234 23345824d651Sblueswir1# launch yet another QEMU instance on same "bus" 23353804da9dSStefan Weilqemu-system-i386 linux.img \ 2336abbbb035SThomas Huth -device e1000,netdev=n3,macaddr=52:54:00:12:34:58 \ 2337abbbb035SThomas Huth -netdev socket,id=n3,mcast=230.0.0.1:1234 23385824d651Sblueswir1@end example 23395824d651Sblueswir1 23405824d651Sblueswir1Example (User Mode Linux compat.): 23415824d651Sblueswir1@example 2342abbbb035SThomas Huth# launch QEMU instance (note mcast address selected is UML's default) 23433804da9dSStefan Weilqemu-system-i386 linux.img \ 2344abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2345abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102 23465824d651Sblueswir1# launch UML 23475824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 23485824d651Sblueswir1@end example 23495824d651Sblueswir1 23503a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 23513a75e74cSMike Ryan@example 23523804da9dSStefan Weilqemu-system-i386 linux.img \ 2353abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2354abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 23553a75e74cSMike Ryan@end example 23563a75e74cSMike Ryan 23573fb69aa1SAnton 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}] 2358abbbb035SThomas HuthConfigure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a 2359abbbb035SThomas Huthpopular protocol to transport Ethernet (and other Layer 2) data frames between 23603fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 23613fb69aa1SAnton Ivanov(from version 3.3 onwards). 23623fb69aa1SAnton Ivanov 23633fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 23643fb69aa1SAnton Ivanov 23651e9a7379SMarkus Armbruster@table @option 23663fb69aa1SAnton Ivanov@item src=@var{srcaddr} 23673fb69aa1SAnton Ivanov source address (mandatory) 23683fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 23693fb69aa1SAnton Ivanov destination address (mandatory) 23703fb69aa1SAnton Ivanov@item udp 23713fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 23723fb69aa1SAnton Ivanov@item srcport=@var{srcport} 23733fb69aa1SAnton Ivanov source udp port. 23743fb69aa1SAnton Ivanov@item dstport=@var{dstport} 23753fb69aa1SAnton Ivanov destination udp port. 23763fb69aa1SAnton Ivanov@item ipv6 23773fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 23783fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2379f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 23803fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 23813fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 23823fb69aa1SAnton Ivanovbit. 23833fb69aa1SAnton Ivanov@item cookie64 23843fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 23853fb69aa1SAnton Ivanov@item counter=off 23863fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 23873fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 23883fb69aa1SAnton Ivanov@item pincounter=on 23893fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 23903fb69aa1SAnton Ivanovnetworks which have packet reorder. 23913fb69aa1SAnton Ivanov@item offset=@var{offset} 23923fb69aa1SAnton Ivanov Add an extra offset between header and data 23931e9a7379SMarkus Armbruster@end table 23943fb69aa1SAnton Ivanov 23953fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 23963fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 23973fb69aa1SAnton Ivanov@example 23983fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 23993fb69aa1SAnton Ivanov# on 1.2.3.4 24003fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 24013fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 24023fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 24033fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 24043fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 24053fb69aa1SAnton Ivanovifconfig vmtunnel0 up 24063fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 24073fb69aa1SAnton Ivanov 24083fb69aa1SAnton Ivanov 24093fb69aa1SAnton Ivanov# on 4.3.2.1 24103fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 24113fb69aa1SAnton Ivanov 2412abbbb035SThomas Huthqemu-system-i386 linux.img -device e1000,netdev=n1 \ 2413abbbb035SThomas 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 24143fb69aa1SAnton Ivanov 24153fb69aa1SAnton Ivanov@end example 24163fb69aa1SAnton Ivanov 241708d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2418abbbb035SThomas HuthConfigure VDE backend to connect to PORT @var{n} of a vde switch running on host and 24195824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 24205824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2421c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 24225824d651Sblueswir1with vde support enabled. 24235824d651Sblueswir1 24245824d651Sblueswir1Example: 24255824d651Sblueswir1@example 24265824d651Sblueswir1# launch vde switch 24275824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 24285824d651Sblueswir1# launch QEMU instance 2429abbbb035SThomas Huthqemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch 24305824d651Sblueswir1@end example 24315824d651Sblueswir1 2432b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 243303ce5744SNikolay Nikolaev 243403ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 243503ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 243603ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 243703ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2438b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2439b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 244003ce5744SNikolay Nikolaev 244103ce5744SNikolay NikolaevExample: 244203ce5744SNikolay Nikolaev@example 244303ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 244403ce5744SNikolay Nikolaev -numa node,memdev=mem \ 244579cad2faSVincenzo Maffione -chardev socket,id=chr0,path=/path/to/socket \ 244603ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 244703ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 244803ce5744SNikolay Nikolaev@end example 244903ce5744SNikolay Nikolaev 2450abbbb035SThomas Huth@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 245178cd6f7bSThomas Huth 2452abbbb035SThomas HuthCreate a hub port on the emulated hub with ID @var{hubid}. 245378cd6f7bSThomas Huth 2454abbbb035SThomas HuthThe hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 2455af1a5c3eSThomas Huthsingle netdev. Alternatively, you can also connect the hubport to another 2456af1a5c3eSThomas Huthnetdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 2457abbbb035SThomas Huth 2458af1a5c3eSThomas Huth@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 2459abbbb035SThomas Huth@findex -net 2460abbbb035SThomas HuthLegacy option to configure or create an on-board (or machine default) Network 2461af1a5c3eSThomas HuthInterface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 2462af1a5c3eSThomas Huththe default hub), or to the netdev @var{nd}. 2463abbbb035SThomas HuthThe NIC is an e1000 by default on the PC target. Optionally, the MAC address 2464abbbb035SThomas Huthcan be changed to @var{mac}, the device address set to @var{addr} (PCI cards 2465abbbb035SThomas Huthonly), and a @var{name} can be assigned for use in monitor commands. 2466abbbb035SThomas HuthOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2467abbbb035SThomas Huththat the card should have; this option currently only affects virtio cards; set 2468abbbb035SThomas Huth@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2469abbbb035SThomas HuthNIC is created. QEMU can emulate several different models of network card. 2470abbbb035SThomas HuthUse @code{-net nic,model=help} for a list of available devices for your target. 2471abbbb035SThomas Huth 2472af1a5c3eSThomas Huth@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 2473abbbb035SThomas HuthConfigure a host network backend (with the options corresponding to the same 2474af1a5c3eSThomas Huth@option{-netdev} option) and connect it to the emulated hub 0 (the default 2475af1a5c3eSThomas Huthhub). Use @var{name} to specify the name of the hub port. 24765824d651Sblueswir1ETEXI 24775824d651Sblueswir1 2478c70a01e4SMarkus ArmbrusterSTEXI 2479c70a01e4SMarkus Armbruster@end table 2480c70a01e4SMarkus ArmbrusterETEXI 24817273a2dbSMatthew BoothDEFHEADING() 24827273a2dbSMatthew Booth 2483de6b4f90SMarkus ArmbrusterDEFHEADING(Character device options:) 24847273a2dbSMatthew Booth 24857273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2486517b3d40SLin Ma "-chardev help\n" 2487d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24885dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2489d0d7708bSDaniel P. Berrange " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n" 2490a8fb5427SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n" 2491d0d7708bSDaniel P. Berrange "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n" 2492d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 24937273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 249497331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2495d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2496d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24977273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2498d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2499d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2500d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2501d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25027273a2dbSMatthew Booth#ifdef _WIN32 2503d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2504d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25057273a2dbSMatthew Booth#else 2506d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2507d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 25087273a2dbSMatthew Booth#endif 25097273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2510d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25117273a2dbSMatthew Booth#endif 25127273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 25137273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2514d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2515d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25167273a2dbSMatthew Booth#endif 25177273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2518d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2519d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25207273a2dbSMatthew Booth#endif 2521cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2522d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2523d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2524cbcc6336SAlon Levy#endif 2525ad96090aSBlue Swirl , QEMU_ARCH_ALL 25267273a2dbSMatthew Booth) 25277273a2dbSMatthew Booth 25287273a2dbSMatthew BoothSTEXI 2529dddba068SMarkus Armbruster 2530dddba068SMarkus ArmbrusterThe general form of a character device option is: 2531dddba068SMarkus Armbruster@table @option 253297331287SJan Kiszka@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 25336616b2adSStefan Weil@findex -chardev 25347273a2dbSMatthew BoothBackend is one of: 25357273a2dbSMatthew Booth@option{null}, 25367273a2dbSMatthew Booth@option{socket}, 25377273a2dbSMatthew Booth@option{udp}, 25387273a2dbSMatthew Booth@option{msmouse}, 25397273a2dbSMatthew Booth@option{vc}, 25404f57378fSMarkus Armbruster@option{ringbuf}, 25417273a2dbSMatthew Booth@option{file}, 25427273a2dbSMatthew Booth@option{pipe}, 25437273a2dbSMatthew Booth@option{console}, 25447273a2dbSMatthew Booth@option{serial}, 25457273a2dbSMatthew Booth@option{pty}, 25467273a2dbSMatthew Booth@option{stdio}, 25477273a2dbSMatthew Booth@option{braille}, 25487273a2dbSMatthew Booth@option{tty}, 254988a946d3SGerd Hoffmann@option{parallel}, 2550cbcc6336SAlon Levy@option{parport}, 255116fdc56aSThomas Huth@option{spicevmc}, 25525a49d3e9SMarc-André Lureau@option{spiceport}. 25537273a2dbSMatthew BoothThe specific backend will determine the applicable options. 25547273a2dbSMatthew Booth 2555dddba068SMarkus ArmbrusterUse @code{-chardev help} to print all available chardev backend types. 2556517b3d40SLin Ma 25577273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 25587273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 25597273a2dbSMatthew Booth 256097331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2561a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2562a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2563a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2564a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2565a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2566a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2567a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2568a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2569a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2570a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2571a40db1b3SPeter Maydell 2572a40db1b3SPeter Maydell@example 2573a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2574bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2575a40db1b3SPeter Maydell-serial chardev:char0 \ 2576a40db1b3SPeter Maydell-serial chardev:char0 2577a40db1b3SPeter Maydell@end example 2578a40db1b3SPeter Maydell 2579a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2580a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2581a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2582a40db1b3SPeter Maydell 2583a40db1b3SPeter Maydell@example 2584a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2585bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2586a40db1b3SPeter Maydell-parallel chardev:char0 \ 2587a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2588a40db1b3SPeter Maydell-serial chardev:char1 \ 2589a40db1b3SPeter Maydell-serial chardev:char1 2590a40db1b3SPeter Maydell@end example 2591a40db1b3SPeter Maydell 2592a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2593a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2594a40db1b3SPeter Maydellmultiplexer}. 2595a40db1b3SPeter Maydell 2596a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2597a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2598a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2599a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2600a40db1b3SPeter Maydellstdio. 2601a40db1b3SPeter Maydell 2602a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2603a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 260497331287SJan Kiszka 2605d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2606d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2607d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2608d0d7708bSDaniel P. Berrangeopened. 2609d0d7708bSDaniel P. Berrange 2610dddba068SMarkus Armbruster@end table 26117273a2dbSMatthew Booth 2612dddba068SMarkus ArmbrusterThe available backends are: 2613dddba068SMarkus Armbruster 2614dddba068SMarkus Armbruster@table @option 26157273a2dbSMatthew Booth@item -chardev null,id=@var{id} 26167273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 26177273a2dbSMatthew Boothreceives. The null backend does not take any options. 26187273a2dbSMatthew Booth 261916fdc56aSThomas Huth@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,reconnect=@var{seconds}][,tls-creds=@var{id}] 26207273a2dbSMatthew Booth 26217273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 26227273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 26237273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 26247273a2dbSMatthew Booth 26257273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 26267273a2dbSMatthew Booth 26277273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 26287273a2dbSMatthew Boothconnect to a listening socket. 26297273a2dbSMatthew Booth 26307273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 26317273a2dbSMatthew Boothescape sequences. 26327273a2dbSMatthew Booth 26335dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 26345dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 26355dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 26365dd1f02bSCorey Minyard 2637a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2638a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2639a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2640a8fb5427SDaniel P. Berrangeargument. 2641a8fb5427SDaniel P. Berrange 26427273a2dbSMatthew BoothTCP and unix socket options are given below: 26437273a2dbSMatthew Booth 26447273a2dbSMatthew Booth@table @option 26457273a2dbSMatthew Booth 26468d533561SAurelien Jarno@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 26477273a2dbSMatthew Booth 26487273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 26497273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 26507273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 26517273a2dbSMatthew Booth 26527273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 26537273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 26547273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 26557273a2dbSMatthew Booth@option{port} is required. 26567273a2dbSMatthew Booth 26577273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 26587273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 26597273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 26607273a2dbSMatthew Boothas a port number. 26617273a2dbSMatthew Booth 26627273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 26637273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 26647273a2dbSMatthew Booth 26657273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 26667273a2dbSMatthew Booth 26677273a2dbSMatthew Booth@item unix options: path=@var{path} 26687273a2dbSMatthew Booth 26697273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 26707273a2dbSMatthew Boothrequired. 26717273a2dbSMatthew Booth 26727273a2dbSMatthew Booth@end table 26737273a2dbSMatthew Booth 26747273a2dbSMatthew Booth@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 26757273a2dbSMatthew Booth 26767273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 26777273a2dbSMatthew Booth 26787273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 26797273a2dbSMatthew Boothdefaults to @code{localhost}. 26807273a2dbSMatthew Booth 26817273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 26827273a2dbSMatthew Boothis required. 26837273a2dbSMatthew Booth 26847273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 26857273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 26867273a2dbSMatthew Booth 26877273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 26887273a2dbSMatthew Boothavailable local port will be used. 26897273a2dbSMatthew Booth 26907273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 26917273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 26927273a2dbSMatthew Booth 26937273a2dbSMatthew Booth@item -chardev msmouse,id=@var{id} 26947273a2dbSMatthew Booth 26957273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 26967273a2dbSMatthew Boothtake any options. 26977273a2dbSMatthew Booth 26987273a2dbSMatthew Booth@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 26997273a2dbSMatthew Booth 27007273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 27017273a2dbSMatthew Boothsize. 27027273a2dbSMatthew Booth 27037273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 27047273a2dbSMatthew Booththe console, in pixels. 27057273a2dbSMatthew Booth 27067273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 27077273a2dbSMatthew Boothconsole with the given dimensions. 27087273a2dbSMatthew Booth 27094f57378fSMarkus Armbruster@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 271051767e7cSLei Li 27113949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 2712e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 271351767e7cSLei Li 27147273a2dbSMatthew Booth@item -chardev file,id=@var{id},path=@var{path} 27157273a2dbSMatthew Booth 27167273a2dbSMatthew BoothLog all traffic received from the guest to a file. 27177273a2dbSMatthew Booth 27187273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 27197273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 27207273a2dbSMatthew Boothis required. 27217273a2dbSMatthew Booth 27227273a2dbSMatthew Booth@item -chardev pipe,id=@var{id},path=@var{path} 27237273a2dbSMatthew Booth 27247273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 27257273a2dbSMatthew BoothWindows hosts and other hosts: 27267273a2dbSMatthew Booth 27277273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 27287273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 27297273a2dbSMatthew Booth 27307273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 27317273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 27327273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 27337273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 27347273a2dbSMatthew Boothbe present. 27357273a2dbSMatthew Booth 27367273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 27377273a2dbSMatthew Boothrequired. 27387273a2dbSMatthew Booth 27397273a2dbSMatthew Booth@item -chardev console,id=@var{id} 27407273a2dbSMatthew Booth 27417273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 27427273a2dbSMatthew Boothtake any options. 27437273a2dbSMatthew Booth 27447273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 27457273a2dbSMatthew Booth 27467273a2dbSMatthew Booth@item -chardev serial,id=@var{id},path=@option{path} 27477273a2dbSMatthew Booth 27487273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 27497273a2dbSMatthew Booth 2750d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 2751d59044efSGerd Hoffmannnot only serial lines. 27527273a2dbSMatthew Booth 27537273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 27547273a2dbSMatthew Booth 27557273a2dbSMatthew Booth@item -chardev pty,id=@var{id} 27567273a2dbSMatthew Booth 27577273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 27587273a2dbSMatthew Boothnot take any options. 27597273a2dbSMatthew Booth 27607273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 27617273a2dbSMatthew Booth 2762b7fdb3abSAurelien Jarno@item -chardev stdio,id=@var{id}[,signal=on|off] 2763b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 2764b7fdb3abSAurelien Jarno 2765b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 2766b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2767b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 2768b7fdb3abSAurelien Jarno 27697273a2dbSMatthew Booth@item -chardev braille,id=@var{id} 27707273a2dbSMatthew Booth 27717273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 27727273a2dbSMatthew Booth 27737273a2dbSMatthew Booth@item -chardev tty,id=@var{id},path=@var{path} 27747273a2dbSMatthew Booth 27757273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2776d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 27777273a2dbSMatthew Booth 27787273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 27797273a2dbSMatthew Booth 278088a946d3SGerd Hoffmann@item -chardev parallel,id=@var{id},path=@var{path} 2781f9cfd655SMarkus Armbruster@itemx -chardev parport,id=@var{id},path=@var{path} 27827273a2dbSMatthew Booth 278388a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 27847273a2dbSMatthew Booth 27857273a2dbSMatthew BoothConnect to a local parallel port. 27867273a2dbSMatthew Booth 27877273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 27887273a2dbSMatthew Boothrequired. 27897273a2dbSMatthew Booth 2790cbcc6336SAlon Levy@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 2791cbcc6336SAlon Levy 27923a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 27933a846906SStefan Hajnoczi 2794cbcc6336SAlon Levy@option{debug} debug level for spicevmc 2795cbcc6336SAlon Levy 2796cbcc6336SAlon Levy@option{name} name of spice channel to connect to 2797cbcc6336SAlon Levy 2798cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 2799cbcc6336SAlon Levy 28005a49d3e9SMarc-André Lureau@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 28015a49d3e9SMarc-André Lureau 28025a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 28035a49d3e9SMarc-André Lureau 28045a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 28055a49d3e9SMarc-André Lureau 28065a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 28075a49d3e9SMarc-André Lureau 28085a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 28095a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 28107273a2dbSMatthew BoothETEXI 28117273a2dbSMatthew Booth 2812c70a01e4SMarkus ArmbrusterSTEXI 2813c70a01e4SMarkus Armbruster@end table 2814c70a01e4SMarkus ArmbrusterETEXI 28157273a2dbSMatthew BoothDEFHEADING() 28167273a2dbSMatthew Booth 2817de6b4f90SMarkus ArmbrusterDEFHEADING(Bluetooth(R) options:) 2818c70a01e4SMarkus ArmbrusterSTEXI 2819c70a01e4SMarkus Armbruster@table @option 2820c70a01e4SMarkus ArmbrusterETEXI 28217273a2dbSMatthew Booth 28225824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 28235824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 28245824d651Sblueswir1 "-bt hci,host[:id]\n" \ 28255824d651Sblueswir1 " use host's HCI with the given name\n" \ 28265824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 28275824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 28285824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 28295824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 28305824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 2831ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2832ad96090aSBlue Swirl QEMU_ARCH_ALL) 28335824d651Sblueswir1STEXI 28345824d651Sblueswir1@item -bt hci[...] 28356616b2adSStefan Weil@findex -bt 28365824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 28375824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 28385824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 28395824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 28405824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 28415824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 28425824d651Sblueswir1machines have none. 28435824d651Sblueswir1 28445824d651Sblueswir1@anchor{bt-hcis} 28455824d651Sblueswir1The following three types are recognized: 28465824d651Sblueswir1 2847b3f046c2SKevin Wolf@table @option 28485824d651Sblueswir1@item -bt hci,null 28495824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 28505824d651Sblueswir1and will not respond to any HCI commands or emit events. 28515824d651Sblueswir1 28525824d651Sblueswir1@item -bt hci,host[:@var{id}] 28535824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 28545824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 28555824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 28565824d651Sblueswir1capable systems like Linux. 28575824d651Sblueswir1 28585824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 28595824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 28605824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 28615824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 28625824d651Sblueswir1with other devices in the same network (scatternet). 28635824d651Sblueswir1@end table 28645824d651Sblueswir1 28655824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 28665824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 28675824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 28685824d651Sblueswir1allows the host and target machines to participate in a common scatternet 28695824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 28705824d651Sblueswir1be used as following: 28715824d651Sblueswir1 28725824d651Sblueswir1@example 28733804da9dSStefan Weilqemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 28745824d651Sblueswir1@end example 28755824d651Sblueswir1 28765824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 28775824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 28785824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 28795824d651Sblueswir1currently: 28805824d651Sblueswir1 2881b3f046c2SKevin Wolf@table @option 28825824d651Sblueswir1@item keyboard 28835824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 28845824d651Sblueswir1@end table 28855824d651Sblueswir1ETEXI 28865824d651Sblueswir1 2887c70a01e4SMarkus ArmbrusterSTEXI 2888c70a01e4SMarkus Armbruster@end table 2889c70a01e4SMarkus ArmbrusterETEXI 28905824d651Sblueswir1DEFHEADING() 28915824d651Sblueswir1 2892d1a0cf73SStefan Berger#ifdef CONFIG_TPM 2893de6b4f90SMarkus ArmbrusterDEFHEADING(TPM device options:) 2894d1a0cf73SStefan Berger 2895d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 289692dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 289792dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 289892dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 2899f4ede81eSAmarnath Valluri " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 2900f4ede81eSAmarnath Valluri "-tpmdev emulator,id=id,chardev=dev\n" 2901f4ede81eSAmarnath Valluri " configure the TPM device using chardev backend\n", 2902d1a0cf73SStefan Berger QEMU_ARCH_ALL) 2903d1a0cf73SStefan BergerSTEXI 2904d1a0cf73SStefan Berger 2905d1a0cf73SStefan BergerThe general form of a TPM device option is: 2906d1a0cf73SStefan Berger@table @option 2907d1a0cf73SStefan Berger 2908d1a0cf73SStefan Berger@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 2909d1a0cf73SStefan Berger@findex -tpmdev 2910d1a0cf73SStefan Berger 2911d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 291228c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 291328c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 2914d1a0cf73SStefan Berger 29152252aaf0SMarkus ArmbrusterUse @code{-tpmdev help} to print all available TPM backend types. 2916d1a0cf73SStefan Berger 29172252aaf0SMarkus Armbruster@end table 29182252aaf0SMarkus Armbruster 29192252aaf0SMarkus ArmbrusterThe available backends are: 29202252aaf0SMarkus Armbruster 29212252aaf0SMarkus Armbruster@table @option 2922d1a0cf73SStefan Berger 292392dcc234SStefan Berger@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 29244549a8b7SStefan Berger 29254549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 29264549a8b7SStefan Bergerdriver. 29274549a8b7SStefan Berger 29284549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 29294549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 29304549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 29314549a8b7SStefan Berger 293292dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 293392dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 293492dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 293592dcc234SStefan Bergersysfs entry to use. 293692dcc234SStefan Berger 29374549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 29384549a8b7SStefan Berger 29394549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 29404549a8b7SStefan Bergerused by any other application on the host. 29414549a8b7SStefan Berger 29424549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 29434549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 29444549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 29454549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 29464549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 29474549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 29484549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 29494549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 29504549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 29514549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 29524549a8b7SStefan Berger 29534549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 29544549a8b7SStefan Berger@example 29554549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 29564549a8b7SStefan Berger@end example 29574549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 29584549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 29594549a8b7SStefan Berger 2960f4ede81eSAmarnath Valluri@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 2961f4ede81eSAmarnath Valluri 2962f4ede81eSAmarnath Valluri(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 2963f4ede81eSAmarnath Vallurichardev backend. 2964f4ede81eSAmarnath Valluri 2965f4ede81eSAmarnath Valluri@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 2966f4ede81eSAmarnath Valluri 2967f4ede81eSAmarnath ValluriTo create a TPM emulator backend device with chardev socket backend: 2968f4ede81eSAmarnath Valluri@example 2969f4ede81eSAmarnath Valluri 2970f4ede81eSAmarnath Valluri-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 2971f4ede81eSAmarnath Valluri 2972f4ede81eSAmarnath Valluri@end example 2973f4ede81eSAmarnath Valluri 2974d1a0cf73SStefan BergerETEXI 2975d1a0cf73SStefan Berger 29762252aaf0SMarkus ArmbrusterSTEXI 29772252aaf0SMarkus Armbruster@end table 29782252aaf0SMarkus ArmbrusterETEXI 2979d1a0cf73SStefan BergerDEFHEADING() 2980d1a0cf73SStefan Berger 2981d1a0cf73SStefan Berger#endif 2982d1a0cf73SStefan Berger 2983de6b4f90SMarkus ArmbrusterDEFHEADING(Linux/Multiboot boot specific:) 29845824d651Sblueswir1STEXI 29857677f05dSAlexander Graf 29867677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 29877677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 29885824d651Sblueswir1for easier testing of various kernels. 29895824d651Sblueswir1 29905824d651Sblueswir1@table @option 29915824d651Sblueswir1ETEXI 29925824d651Sblueswir1 29935824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2994ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 29955824d651Sblueswir1STEXI 29965824d651Sblueswir1@item -kernel @var{bzImage} 29976616b2adSStefan Weil@findex -kernel 29987677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 29997677f05dSAlexander Grafor in multiboot format. 30005824d651Sblueswir1ETEXI 30015824d651Sblueswir1 30025824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 3003ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 30045824d651Sblueswir1STEXI 30055824d651Sblueswir1@item -append @var{cmdline} 30066616b2adSStefan Weil@findex -append 30075824d651Sblueswir1Use @var{cmdline} as kernel command line 30085824d651Sblueswir1ETEXI 30095824d651Sblueswir1 30105824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 3011ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 30125824d651Sblueswir1STEXI 30135824d651Sblueswir1@item -initrd @var{file} 30146616b2adSStefan Weil@findex -initrd 30155824d651Sblueswir1Use @var{file} as initial ram disk. 30167677f05dSAlexander Graf 30177677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 30187677f05dSAlexander Graf 30197677f05dSAlexander GrafThis syntax is only available with multiboot. 30207677f05dSAlexander Graf 30217677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 30227677f05dSAlexander Graffirst module. 30235824d651Sblueswir1ETEXI 30245824d651Sblueswir1 3025412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 3026379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 3027412beee6SGrant LikelySTEXI 3028412beee6SGrant Likely@item -dtb @var{file} 3029412beee6SGrant Likely@findex -dtb 3030412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 3031412beee6SGrant Likelyon boot. 3032412beee6SGrant LikelyETEXI 3033412beee6SGrant Likely 30345824d651Sblueswir1STEXI 30355824d651Sblueswir1@end table 30365824d651Sblueswir1ETEXI 30375824d651Sblueswir1DEFHEADING() 30385824d651Sblueswir1 3039de6b4f90SMarkus ArmbrusterDEFHEADING(Debug/Expert options:) 30405824d651Sblueswir1STEXI 30415824d651Sblueswir1@table @option 30425824d651Sblueswir1ETEXI 30435824d651Sblueswir1 304481b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 304581b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 304663d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 30476407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 304863d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 304981b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 305081b2b810SGabriel L. SomloSTEXI 305163d3145aSMarkus Armbruster 305281b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 305381b2b810SGabriel L. Somlo@findex -fw_cfg 305463d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 30556407d76eSGabriel L. Somlo 30566407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 305763d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 305863d3145aSMarkus Armbruster 305963d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 306063d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 306163d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 306263d3145aSMarkus Armbruster 306363d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 306463d3145aSMarkus Armbruster 306563d3145aSMarkus ArmbrusterExample: 306663d3145aSMarkus Armbruster@example 306763d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 306863d3145aSMarkus Armbruster@end example 306963d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 307063d3145aSMarkus Armbrusterfrom ./my_blob.bin. 307163d3145aSMarkus Armbruster 307281b2b810SGabriel L. SomloETEXI 307381b2b810SGabriel L. Somlo 30745824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3075ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 3076ad96090aSBlue Swirl QEMU_ARCH_ALL) 30775824d651Sblueswir1STEXI 30785824d651Sblueswir1@item -serial @var{dev} 30796616b2adSStefan Weil@findex -serial 30805824d651Sblueswir1Redirect the virtual serial port to host character device 30815824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 30825824d651Sblueswir1@code{stdio} in non graphical mode. 30835824d651Sblueswir1 30845824d651Sblueswir1This option can be used several times to simulate up to 4 serial 30855824d651Sblueswir1ports. 30865824d651Sblueswir1 30875824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 30885824d651Sblueswir1 30895824d651Sblueswir1Available character devices are: 3090b3f046c2SKevin Wolf@table @option 30914e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 30925824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 30935824d651Sblueswir1@example 30945824d651Sblueswir1vc:800x600 30955824d651Sblueswir1@end example 30965824d651Sblueswir1It is also possible to specify width or height in characters: 30975824d651Sblueswir1@example 30985824d651Sblueswir1vc:80Cx24C 30995824d651Sblueswir1@end example 31005824d651Sblueswir1@item pty 31015824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 31025824d651Sblueswir1@item none 31035824d651Sblueswir1No device is allocated. 31045824d651Sblueswir1@item null 31055824d651Sblueswir1void device 310688e020e5SIngo van Lil@item chardev:@var{id} 310788e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 31085824d651Sblueswir1@item /dev/XXX 31095824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 31105824d651Sblueswir1parameters are set according to the emulated ones. 31115824d651Sblueswir1@item /dev/parport@var{N} 31125824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 31135824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 31145824d651Sblueswir1@item file:@var{filename} 31155824d651Sblueswir1Write output to @var{filename}. No character can be read. 31165824d651Sblueswir1@item stdio 31175824d651Sblueswir1[Unix only] standard input/output 31185824d651Sblueswir1@item pipe:@var{filename} 31195824d651Sblueswir1name pipe @var{filename} 31205824d651Sblueswir1@item COM@var{n} 31215824d651Sblueswir1[Windows only] Use host serial port @var{n} 31225824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 31235824d651Sblueswir1This implements UDP Net Console. 31245824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 31255824d651Sblueswir1they default to @code{0.0.0.0}. 31265824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 31275824d651Sblueswir1 31285824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3129b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3130b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 31315824d651Sblueswir1will appear in the netconsole session. 31325824d651Sblueswir1 31335824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3134b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 31355824d651Sblueswir1source port each time by using something like @code{-serial 3136b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 31375824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 31385824d651Sblueswir1characters via udp. If you have a patched version of netcat which 31395824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3140bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3141b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 31425824d651Sblueswir1@table @code 3143071c9394SStefan Weil@item QEMU Options: 31445824d651Sblueswir1-serial udp::4555@@:4556 31455824d651Sblueswir1@item netcat options: 31465824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 31475824d651Sblueswir1@item telnet options: 31485824d651Sblueswir1localhost 5555 31495824d651Sblueswir1@end table 31505824d651Sblueswir1 31515dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 31525824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 31535824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 31545824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 31555824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 31565824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 31575824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 31585dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 31595dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 31605dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 31615824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 31625824d651Sblueswir1connect to the corresponding character device. 31635824d651Sblueswir1@table @code 31645824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 31655824d651Sblueswir1-serial tcp:192.168.0.2:4444 31665824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 31675824d651Sblueswir1-serial tcp::4444,server 31685824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 31695824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 31705824d651Sblueswir1@end table 31715824d651Sblueswir1 31725824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 31735824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 31745824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 31755824d651Sblueswir1difference is that the port acts like a telnet server or client using 31765824d651Sblueswir1telnet option negotiation. This will also allow you to send the 31775824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 31785824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 31795824d651Sblueswir1type "send break" followed by pressing the enter key. 31805824d651Sblueswir1 31815dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 31825824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 31835824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 31845824d651Sblueswir1@var{path} is used for connections. 31855824d651Sblueswir1 31865824d651Sblueswir1@item mon:@var{dev_string} 31875824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 31885824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 318902c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 31905824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 31915824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 31925824d651Sblueswir1listening on port 4444 would be: 31935824d651Sblueswir1@table @code 31945824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 31955824d651Sblueswir1@end table 3196be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 319702c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 31985824d651Sblueswir1 31995824d651Sblueswir1@item braille 32005824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 32015824d651Sblueswir1or fake device. 32025824d651Sblueswir1 3203be8b28a9SKevin Wolf@item msmouse 3204be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 32055824d651Sblueswir1@end table 32065824d651Sblueswir1ETEXI 32075824d651Sblueswir1 32085824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3209ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3210ad96090aSBlue Swirl QEMU_ARCH_ALL) 32115824d651Sblueswir1STEXI 32125824d651Sblueswir1@item -parallel @var{dev} 32136616b2adSStefan Weil@findex -parallel 32145824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 32155824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 32165824d651Sblueswir1be used to use hardware devices connected on the corresponding host 32175824d651Sblueswir1parallel port. 32185824d651Sblueswir1 32195824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 32205824d651Sblueswir1ports. 32215824d651Sblueswir1 32225824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 32235824d651Sblueswir1ETEXI 32245824d651Sblueswir1 32255824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3226ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3227ad96090aSBlue Swirl QEMU_ARCH_ALL) 32285824d651Sblueswir1STEXI 32294e307fc8SGerd Hoffmann@item -monitor @var{dev} 32306616b2adSStefan Weil@findex -monitor 32315824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 32325824d651Sblueswir1serial port). 32335824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 32345824d651Sblueswir1non graphical mode. 323570e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 32365824d651Sblueswir1ETEXI 32376ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3238ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3239ad96090aSBlue Swirl QEMU_ARCH_ALL) 324095d5f08bSStefan WeilSTEXI 324195d5f08bSStefan Weil@item -qmp @var{dev} 32426616b2adSStefan Weil@findex -qmp 324395d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 324495d5f08bSStefan WeilETEXI 32454821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 32464821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 32474821cd4cSMax Reitz QEMU_ARCH_ALL) 32484821cd4cSMax ReitzSTEXI 32494821cd4cSMax Reitz@item -qmp-pretty @var{dev} 32504821cd4cSMax Reitz@findex -qmp-pretty 32514821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 32524821cd4cSMax ReitzETEXI 32535824d651Sblueswir1 325422a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3255ef670726SVicente Jimenez Aguilar "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 325622a0e04bSGerd HoffmannSTEXI 3257ef670726SVicente Jimenez Aguilar@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 32586616b2adSStefan Weil@findex -mon 3259ef670726SVicente Jimenez AguilarSetup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 3260ef670726SVicente Jimenez Aguilareasing human reading and debugging. 326122a0e04bSGerd HoffmannETEXI 326222a0e04bSGerd Hoffmann 3263c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3264ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3265ad96090aSBlue Swirl QEMU_ARCH_ALL) 3266c9f398e5SH. Peter AnvinSTEXI 3267c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 32686616b2adSStefan Weil@findex -debugcon 3269c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3270c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3271c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3272c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3273c9f398e5SH. Peter Anvinnon graphical mode. 3274c9f398e5SH. Peter AnvinETEXI 3275c9f398e5SH. Peter Anvin 32765824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3277ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 32785824d651Sblueswir1STEXI 32795824d651Sblueswir1@item -pidfile @var{file} 32806616b2adSStefan Weil@findex -pidfile 32815824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 32825824d651Sblueswir1from a script. 32835824d651Sblueswir1ETEXI 32845824d651Sblueswir1 32851b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3286ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 32871b530a6dSaurel32STEXI 32881b530a6dSaurel32@item -singlestep 32896616b2adSStefan Weil@findex -singlestep 32901b530a6dSaurel32Run the emulation in single step mode. 32911b530a6dSaurel32ETEXI 32921b530a6dSaurel32 3293047f7038SIgor MammedovDEF("preconfig", 0, QEMU_OPTION_preconfig, \ 3294047f7038SIgor Mammedov "--preconfig pause QEMU before machine is initialized\n", 3295047f7038SIgor Mammedov QEMU_ARCH_ALL) 3296047f7038SIgor MammedovSTEXI 3297047f7038SIgor Mammedov@item --preconfig 3298047f7038SIgor Mammedov@findex --preconfig 3299047f7038SIgor MammedovPause QEMU for interactive configuration before the machine is created, 3300047f7038SIgor Mammedovwhich allows querying and configuring properties that will affect 3301047f7038SIgor Mammedovmachine initialization. Use the QMP command 'exit-preconfig' to exit 3302047f7038SIgor Mammedovthe preconfig state and move to the next state (ie. run guest if -S 3303047f7038SIgor Mammedovisn't used or pause the second time if -S is used). 3304047f7038SIgor MammedovETEXI 3305047f7038SIgor Mammedov 33065824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3307ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3308ad96090aSBlue Swirl QEMU_ARCH_ALL) 33095824d651Sblueswir1STEXI 33105824d651Sblueswir1@item -S 33116616b2adSStefan Weil@findex -S 33125824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 33135824d651Sblueswir1ETEXI 33145824d651Sblueswir1 3315888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3316888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3317888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3318888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3319888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3320888a6bc6SSatoru MoriyaSTEXI 3321888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3322888a6bc6SSatoru Moriya@findex -realtime 3323888a6bc6SSatoru MoriyaRun qemu with realtime features. 3324888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3325888a6bc6SSatoru Moriya(enabled by default). 3326888a6bc6SSatoru MoriyaETEXI 3327888a6bc6SSatoru Moriya 332859030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3329ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 33305824d651Sblueswir1STEXI 333159030a8cSaliguori@item -gdb @var{dev} 33326616b2adSStefan Weil@findex -gdb 333359030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 333459030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3335b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 333659030a8cSaliguoriwithin gdb and establish the connection via a pipe: 333759030a8cSaliguori@example 33383804da9dSStefan Weil(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 333959030a8cSaliguori@end example 33405824d651Sblueswir1ETEXI 33415824d651Sblueswir1 334259030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3343ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3344ad96090aSBlue Swirl QEMU_ARCH_ALL) 33455824d651Sblueswir1STEXI 334659030a8cSaliguori@item -s 33476616b2adSStefan Weil@findex -s 334859030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 334959030a8cSaliguori(@pxref{gdb_usage}). 33505824d651Sblueswir1ETEXI 33515824d651Sblueswir1 33525824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3353989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3354ad96090aSBlue Swirl QEMU_ARCH_ALL) 33555824d651Sblueswir1STEXI 3356989b697dSPeter Maydell@item -d @var{item1}[,...] 33576616b2adSStefan Weil@findex -d 3358989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 33595824d651Sblueswir1ETEXI 33605824d651Sblueswir1 3361c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3362989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3363c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3364c235d738SMatthew FernandezSTEXI 33658bd383b4SStefan Weil@item -D @var{logfile} 3366c235d738SMatthew Fernandez@findex -D 3367989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3368c235d738SMatthew FernandezETEXI 3369c235d738SMatthew Fernandez 33703514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 33713514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 33723514552eSAlex Bennée QEMU_ARCH_ALL) 33733514552eSAlex BennéeSTEXI 33743514552eSAlex Bennée@item -dfilter @var{range1}[,...] 33753514552eSAlex Bennée@findex -dfilter 33763514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 33773514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 33783514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 33793514552eSAlex Bennéeaddresses and sizes required. For example: 33803514552eSAlex Bennée@example 33813514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 33823514552eSAlex Bennée@end example 33833514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 33843514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 33853514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 33863514552eSAlex BennéeETEXI 33873514552eSAlex Bennée 33885824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3389ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3390ad96090aSBlue Swirl QEMU_ARCH_ALL) 33915824d651Sblueswir1STEXI 33925824d651Sblueswir1@item -L @var{path} 33936616b2adSStefan Weil@findex -L 33945824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 339537146e7eSRichard W.M. Jones 339637146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 33975824d651Sblueswir1ETEXI 33985824d651Sblueswir1 33995824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3400ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 34015824d651Sblueswir1STEXI 34025824d651Sblueswir1@item -bios @var{file} 34036616b2adSStefan Weil@findex -bios 34045824d651Sblueswir1Set the filename for the BIOS. 34055824d651Sblueswir1ETEXI 34065824d651Sblueswir1 34075824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3408ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 34095824d651Sblueswir1STEXI 34105824d651Sblueswir1@item -enable-kvm 34116616b2adSStefan Weil@findex -enable-kvm 34125824d651Sblueswir1Enable KVM full virtualization support. This option is only available 34135824d651Sblueswir1if KVM support is enabled when compiling. 34145824d651Sblueswir1ETEXI 34155824d651Sblueswir1 3416b0cb0a66SVincent PalatinDEF("enable-hax", 0, QEMU_OPTION_enable_hax, \ 3417b0cb0a66SVincent Palatin "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386) 3418b0cb0a66SVincent PalatinSTEXI 3419b0cb0a66SVincent Palatin@item -enable-hax 3420b0cb0a66SVincent Palatin@findex -enable-hax 3421b0cb0a66SVincent PalatinEnable HAX (Hardware-based Acceleration eXecution) support. This option 3422b0cb0a66SVincent Palatinis only available if HAX support is enabled when compiling. HAX is only 3423b0cb0a66SVincent Palatinapplicable to MAC and Windows platform, and thus does not conflict with 3424b0cb0a66SVincent PalatinKVM. 3425b0cb0a66SVincent PalatinETEXI 3426b0cb0a66SVincent Palatin 3427e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3428ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3429e37630caSaliguoriDEF("xen-create", 0, QEMU_OPTION_xen_create, 3430e37630caSaliguori "-xen-create create domain using xen hypercalls, bypassing xend\n" 3431ad96090aSBlue Swirl " warning: should not be used when xend is in use\n", 3432ad96090aSBlue Swirl QEMU_ARCH_ALL) 3433e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3434e37630caSaliguori "-xen-attach attach to existing xen domain\n" 3435b65ee4faSStefan Weil " xend will use this when starting QEMU\n", 3436ad96090aSBlue Swirl QEMU_ARCH_ALL) 34371c599472SPaul DurrantDEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 34381c599472SPaul Durrant "-xen-domid-restrict restrict set of available xen operations\n" 34391c599472SPaul Durrant " to specified domain id. (Does not affect\n" 34401c599472SPaul Durrant " xenpv machine type).\n", 34411c599472SPaul Durrant QEMU_ARCH_ALL) 344295d5f08bSStefan WeilSTEXI 344395d5f08bSStefan Weil@item -xen-domid @var{id} 34446616b2adSStefan Weil@findex -xen-domid 344595d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 344695d5f08bSStefan Weil@item -xen-create 34476616b2adSStefan Weil@findex -xen-create 344895d5f08bSStefan WeilCreate domain using xen hypercalls, bypassing xend. 344995d5f08bSStefan WeilWarning: should not be used when xend is in use (XEN only). 345095d5f08bSStefan Weil@item -xen-attach 34516616b2adSStefan Weil@findex -xen-attach 345295d5f08bSStefan WeilAttach to existing xen domain. 3453b65ee4faSStefan Weilxend will use this when starting QEMU (XEN only). 34541c599472SPaul Durrant@findex -xen-domid-restrict 34551c599472SPaul DurrantRestrict set of available xen operations to specified domain id (XEN only). 345695d5f08bSStefan WeilETEXI 3457e37630caSaliguori 34585824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3459ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 34605824d651Sblueswir1STEXI 34615824d651Sblueswir1@item -no-reboot 34626616b2adSStefan Weil@findex -no-reboot 34635824d651Sblueswir1Exit instead of rebooting. 34645824d651Sblueswir1ETEXI 34655824d651Sblueswir1 34665824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3467ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 34685824d651Sblueswir1STEXI 34695824d651Sblueswir1@item -no-shutdown 34706616b2adSStefan Weil@findex -no-shutdown 34715824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 34725824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 34735824d651Sblueswir1disk image. 34745824d651Sblueswir1ETEXI 34755824d651Sblueswir1 34765824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 34775824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3478ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3479ad96090aSBlue Swirl QEMU_ARCH_ALL) 34805824d651Sblueswir1STEXI 34815824d651Sblueswir1@item -loadvm @var{file} 34826616b2adSStefan Weil@findex -loadvm 34835824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 34845824d651Sblueswir1ETEXI 34855824d651Sblueswir1 34865824d651Sblueswir1#ifndef _WIN32 34875824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3488ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 34895824d651Sblueswir1#endif 34905824d651Sblueswir1STEXI 34915824d651Sblueswir1@item -daemonize 34926616b2adSStefan Weil@findex -daemonize 34935824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 34945824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 34955824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 34965824d651Sblueswir1to cope with initialization race conditions. 34975824d651Sblueswir1ETEXI 34985824d651Sblueswir1 34995824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3500ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3501ad96090aSBlue Swirl QEMU_ARCH_ALL) 35025824d651Sblueswir1STEXI 35035824d651Sblueswir1@item -option-rom @var{file} 35046616b2adSStefan Weil@findex -option-rom 35055824d651Sblueswir1Load the contents of @var{file} as an option ROM. 35065824d651Sblueswir1This option is useful to load things like EtherBoot. 35075824d651Sblueswir1ETEXI 35085824d651Sblueswir1 3509e218052fSMarkus ArmbrusterHXCOMM Silently ignored for compatibility 3510e218052fSMarkus ArmbrusterDEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 35115824d651Sblueswir1 35121ed2fc1fSJan KiszkaHXCOMM Options deprecated by -rtc 3513ad96090aSBlue SwirlDEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 3514ad96090aSBlue SwirlDEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 35155824d651Sblueswir1 35161ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 351778808141SPaolo Bonzini "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3518ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3519ad96090aSBlue Swirl QEMU_ARCH_ALL) 35201ed2fc1fSJan Kiszka 35215824d651Sblueswir1STEXI 35225824d651Sblueswir1 35236875204cSJan Kiszka@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 35246616b2adSStefan Weil@findex -rtc 35251ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 35261ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 35271ed2fc1fSJan KiszkaMS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 35281ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 35291ed2fc1fSJan Kiszka 35309d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 35316875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 35326875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 353378808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 353478808141SPaolo Bonzinito @code{rt} instead. To even prevent it from progressing during suspension, 353578808141SPaolo Bonziniyou can set it to @code{vm}. 35366875204cSJan Kiszka 35371ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 35381ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 35391ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 35401ed2fc1fSJan Kiszkare-inject them. 35415824d651Sblueswir1ETEXI 35425824d651Sblueswir1 35435824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 35449c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3545bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3546f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3547f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 35485824d651Sblueswir1STEXI 35499c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 35506616b2adSStefan Weil@findex -icount 35515824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 35524e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 35535824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 35545824d651Sblueswir1time within a few seconds of real time. 35555824d651Sblueswir1 3556f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3557778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3558778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3559f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3560f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3561f1f4b57eSVictor CLEMENTthe guest point of view. 3562f1f4b57eSVictor CLEMENT 35635824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 35645824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 35655824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 35665824d651Sblueswir1executed often has little or no correlation with actual performance. 3567a8bfac37SSebastian Tanase 3568b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3569a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3570a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3571a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 357282597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3573a8bfac37SSebastian Tanaseto inform about the delay. 3574a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3575a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3576a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3577a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 35784c27b859SPavel Dovgalyuk 35794c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 35804c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 35814c27b859SPavel Dovgalyukread from this file in replay mode. 35829c2037d0SPavel Dovgalyuk 35839c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 35849c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 35859c2037d0SPavel Dovgalyukto load the initial VM state. 35865824d651Sblueswir1ETEXI 35875824d651Sblueswir1 35889dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3589d7933ef3SXu Wang "-watchdog model\n" \ 3590ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3591ad96090aSBlue Swirl QEMU_ARCH_ALL) 35929dd986ccSRichard W.M. JonesSTEXI 35939dd986ccSRichard W.M. Jones@item -watchdog @var{model} 35946616b2adSStefan Weil@findex -watchdog 35959dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 35969dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3597d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3598d7933ef3SXu Wangwhich your guest has drivers. 35999dd986ccSRichard W.M. Jones 3600d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3601d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 36029dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3603d7933ef3SXu Wang 3604d7933ef3SXu WangThe following models may be available: 3605d7933ef3SXu Wang@table @option 3606d7933ef3SXu Wang@item ib700 3607d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3608d7933ef3SXu Wang@item i6300esb 3609d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3610d7933ef3SXu Wangdual-timer watchdog. 3611188f24c2SXu Wang@item diag288 3612188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3613188f24c2SXu Wang(currently KVM only). 3614d7933ef3SXu Wang@end table 36159dd986ccSRichard W.M. JonesETEXI 36169dd986ccSRichard W.M. Jones 36179dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 36187ad9270eSMarkus Armbruster "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 3619ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3620ad96090aSBlue Swirl QEMU_ARCH_ALL) 36219dd986ccSRichard W.M. JonesSTEXI 36229dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3623b8f490ebSMarkus Armbruster@findex -watchdog-action 36249dd986ccSRichard W.M. Jones 36259dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 36269dd986ccSRichard W.M. Jonesexpires. 36279dd986ccSRichard W.M. JonesThe default is 36289dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 36299dd986ccSRichard W.M. JonesOther possible actions are: 36309dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 36319dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 36327ad9270eSMarkus Armbruster@code{inject-nmi} (inject a NMI into the guest), 36339dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 36349dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 36359dd986ccSRichard W.M. Jones@code{none} (do nothing). 36369dd986ccSRichard W.M. Jones 36379dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 36389dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 36399dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 36409dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 36419dd986ccSRichard W.M. Jones 36429dd986ccSRichard W.M. JonesExamples: 36439dd986ccSRichard W.M. Jones 36449dd986ccSRichard W.M. Jones@table @code 36459dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3646f9cfd655SMarkus Armbruster@itemx -watchdog ib700 36479dd986ccSRichard W.M. Jones@end table 36489dd986ccSRichard W.M. JonesETEXI 36499dd986ccSRichard W.M. Jones 36505824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3651ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3652ad96090aSBlue Swirl QEMU_ARCH_ALL) 36535824d651Sblueswir1STEXI 36545824d651Sblueswir1 36554e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 36566616b2adSStefan Weil@findex -echr 36575824d651Sblueswir1Change the escape character used for switching to the monitor when using 36585824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 36595824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 36605824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 36615824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 36625824d651Sblueswir1instance you could use the either of the following to change the escape 36635824d651Sblueswir1character to Control-t. 36645824d651Sblueswir1@table @code 36655824d651Sblueswir1@item -echr 0x14 3666f9cfd655SMarkus Armbruster@itemx -echr 20 36675824d651Sblueswir1@end table 36685824d651Sblueswir1ETEXI 36695824d651Sblueswir1 36705824d651Sblueswir1DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 36715824d651Sblueswir1 "-virtioconsole c\n" \ 3672ad96090aSBlue Swirl " set virtio console\n", QEMU_ARCH_ALL) 36735824d651Sblueswir1STEXI 36745824d651Sblueswir1@item -virtioconsole @var{c} 36756616b2adSStefan Weil@findex -virtioconsole 36765824d651Sblueswir1Set virtio console. 367745401299SThomas HuthThis option is deprecated, please use @option{-device virtconsole} instead. 36785824d651Sblueswir1ETEXI 36795824d651Sblueswir1 36805824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3681ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 36825824d651Sblueswir1STEXI 368395d5f08bSStefan Weil@item -show-cursor 36846616b2adSStefan Weil@findex -show-cursor 368595d5f08bSStefan WeilShow cursor. 36865824d651Sblueswir1ETEXI 36875824d651Sblueswir1 36885824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3689ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 36905824d651Sblueswir1STEXI 369195d5f08bSStefan Weil@item -tb-size @var{n} 36926616b2adSStefan Weil@findex -tb-size 369395d5f08bSStefan WeilSet TB size. 36945824d651Sblueswir1ETEXI 36955824d651Sblueswir1 36965824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 36977c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 36987c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 36997c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 37007c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 37017c601803SMichael Tokarev " specified protocol and socket address\n" \ 37027c601803SMichael Tokarev "-incoming fd:fd\n" \ 37037c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 37047c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 37051597051bSDr. David Alan Gilbert " or from given external command\n" \ 37061597051bSDr. David Alan Gilbert "-incoming defer\n" \ 37071597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3708ad96090aSBlue Swirl QEMU_ARCH_ALL) 37095824d651Sblueswir1STEXI 37107c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3711f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 37126616b2adSStefan Weil@findex -incoming 37137c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 37147c601803SMichael Tokarev 37157c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 37167c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 37177c601803SMichael Tokarev 37187c601803SMichael Tokarev@item -incoming fd:@var{fd} 37197c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 37207c601803SMichael Tokarev 37217c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 37227c601803SMichael TokarevAccept incoming migration as an output from specified external command. 37231597051bSDr. David Alan Gilbert 37241597051bSDr. David Alan Gilbert@item -incoming defer 37251597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 37261597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 37271597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 37285824d651Sblueswir1ETEXI 37295824d651Sblueswir1 3730d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 3731d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 3732d15c05fcSAshijeet AcharyaSTEXI 3733d15c05fcSAshijeet Acharya@item -only-migratable 3734d15c05fcSAshijeet Acharya@findex -only-migratable 3735d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 3736d15c05fcSAshijeet Acharyaunmigratable state. 3737d15c05fcSAshijeet AcharyaETEXI 3738d15c05fcSAshijeet Acharya 3739d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3740ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3741d8c208ddSGerd HoffmannSTEXI 37423dbf2c7fSStefan Weil@item -nodefaults 37436616b2adSStefan Weil@findex -nodefaults 374466c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 374566c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 374666c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 374766c19bf1SMichal Novotnydefault devices. 3748d8c208ddSGerd HoffmannETEXI 3749d8c208ddSGerd Hoffmann 37505824d651Sblueswir1#ifndef _WIN32 37515824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3752ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3753ad96090aSBlue Swirl QEMU_ARCH_ALL) 37545824d651Sblueswir1#endif 37555824d651Sblueswir1STEXI 37564e257e5eSKevin Wolf@item -chroot @var{dir} 37576616b2adSStefan Weil@findex -chroot 37585824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 37595824d651Sblueswir1directory. Especially useful in combination with -runas. 37605824d651Sblueswir1ETEXI 37615824d651Sblueswir1 37625824d651Sblueswir1#ifndef _WIN32 37635824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 37642c42f1e8SIan Jackson "-runas user change to user id user just before starting the VM\n" \ 37652c42f1e8SIan Jackson " user can be numeric uid:gid instead\n", 3766ad96090aSBlue Swirl QEMU_ARCH_ALL) 37675824d651Sblueswir1#endif 37685824d651Sblueswir1STEXI 37694e257e5eSKevin Wolf@item -runas @var{user} 37706616b2adSStefan Weil@findex -runas 37715824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 37725824d651Sblueswir1to the specified user. 37735824d651Sblueswir1ETEXI 37745824d651Sblueswir1 37755824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 37765824d651Sblueswir1 "-prom-env variable=value\n" 3777ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 3778ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 377995d5f08bSStefan WeilSTEXI 378095d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 37816616b2adSStefan Weil@findex -prom-env 378295d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 378395d5f08bSStefan WeilETEXI 37845824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 3785f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 37863b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 37873b3c1694SLeon Alrae QEMU_ARCH_MIPS) 378895d5f08bSStefan WeilSTEXI 378995d5f08bSStefan Weil@item -semihosting 37906616b2adSStefan Weil@findex -semihosting 37913b3c1694SLeon AlraeEnable semihosting mode (ARM, M68K, Xtensa, MIPS only). 3792a38bb079SLiviu IonescuETEXI 3793a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3794a59d31a1SLeon Alrae "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 3795a59d31a1SLeon Alrae " semihosting configuration\n", 37963b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 37973b3c1694SLeon AlraeQEMU_ARCH_MIPS) 3798a38bb079SLiviu IonescuSTEXI 3799a59d31a1SLeon Alrae@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 3800a38bb079SLiviu Ionescu@findex -semihosting-config 38013b3c1694SLeon AlraeEnable and configure semihosting (ARM, M68K, Xtensa, MIPS only). 3802a59d31a1SLeon Alrae@table @option 3803a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 3804a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 3805a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 3806a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 3807a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 3808a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 3809a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 3810a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 3811a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 3812a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 3813a59d31a1SLeon Alrae@end table 381495d5f08bSStefan WeilETEXI 38155824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 3816ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 381795d5f08bSStefan WeilSTEXI 381895d5f08bSStefan Weil@item -old-param 38196616b2adSStefan Weil@findex -old-param (ARM) 382095d5f08bSStefan WeilOld param mode (ARM only). 382195d5f08bSStefan WeilETEXI 382295d5f08bSStefan Weil 38237d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 382473a1e647SEduardo Otubo "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 382524f8cdc5SEduardo Otubo " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 38262b716fa6SEduardo Otubo " Enable seccomp mode 2 system call filter (default 'off').\n" \ 38272b716fa6SEduardo Otubo " use 'obsolete' to allow obsolete system calls that are provided\n" \ 38282b716fa6SEduardo Otubo " by the kernel, but typically no longer used by modern\n" \ 382973a1e647SEduardo Otubo " C library implementations.\n" \ 383073a1e647SEduardo Otubo " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 383173a1e647SEduardo Otubo " its privileges by blacklisting all set*uid|gid system calls.\n" \ 383273a1e647SEduardo Otubo " The value 'children' will deny set*uid|gid system calls for\n" \ 3833995a226fSEduardo Otubo " main QEMU process but will allow forks and execves to run unprivileged\n" \ 3834995a226fSEduardo Otubo " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 383524f8cdc5SEduardo Otubo " blacklisting *fork and execve\n" \ 383624f8cdc5SEduardo Otubo " use 'resourcecontrol' to disable process affinity and schedular priority\n", 38377d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 38387d76ad4fSEduardo OtuboSTEXI 383924f8cdc5SEduardo Otubo@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 38407d76ad4fSEduardo Otubo@findex -sandbox 38417d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 38427d76ad4fSEduardo Otubodisable it. The default is 'off'. 38432b716fa6SEduardo Otubo@table @option 38442b716fa6SEduardo Otubo@item obsolete=@var{string} 38452b716fa6SEduardo OtuboEnable Obsolete system calls 384673a1e647SEduardo Otubo@item elevateprivileges=@var{string} 384773a1e647SEduardo OtuboDisable set*uid|gid system calls 3848995a226fSEduardo Otubo@item spawn=@var{string} 3849995a226fSEduardo OtuboDisable *fork and execve 385024f8cdc5SEduardo Otubo@item resourcecontrol=@var{string} 385124f8cdc5SEduardo OtuboDisable process affinity and schedular priority 38522b716fa6SEduardo Otubo@end table 38537d76ad4fSEduardo OtuboETEXI 38547d76ad4fSEduardo Otubo 3855715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3856ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 38573dbf2c7fSStefan WeilSTEXI 38583dbf2c7fSStefan Weil@item -readconfig @var{file} 38596616b2adSStefan Weil@findex -readconfig 3860ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 3861ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 3862ed24cfacSMichal Novotnycharacter limit. 38633dbf2c7fSStefan WeilETEXI 3864715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3865715a664aSGerd Hoffmann "-writeconfig <file>\n" 3866ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 38673dbf2c7fSStefan WeilSTEXI 38683dbf2c7fSStefan Weil@item -writeconfig @var{file} 38696616b2adSStefan Weil@findex -writeconfig 3870ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 3871ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 3872ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 38733dbf2c7fSStefan WeilETEXI 38743478eae9SEduardo HabkostHXCOMM Deprecated, same as -no-user-config 38753478eae9SEduardo HabkostDEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, "", QEMU_ARCH_ALL) 3876f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3877f29a5614SEduardo Habkost "-no-user-config\n" 38783478eae9SEduardo Habkost " do not load default user-provided config files at startup\n", 3879f29a5614SEduardo Habkost QEMU_ARCH_ALL) 3880f29a5614SEduardo HabkostSTEXI 3881f29a5614SEduardo Habkost@item -no-user-config 3882f29a5614SEduardo Habkost@findex -no-user-config 3883f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 38843478eae9SEduardo Habkostconfig files on @var{sysconfdir}. 3885292444cbSAnthony LiguoriETEXI 3886ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 388710578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 388823d15e86SLluís " specify tracing options\n", 3889ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 3890ab6540d5SPrerna SaxenaSTEXI 389123d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 389223d15e86SLluísHXCOMM HX does not support conditional compilation of text. 3893e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 3894ab6540d5SPrerna Saxena@findex -trace 3895eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 3896ab6540d5SPrerna SaxenaETEXI 38973dbf2c7fSStefan Weil 389831e70d6cSMarkus ArmbrusterHXCOMM Internal use 389931e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 390031e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3901c7f0f3b1SAnthony Liguori 39020f66998fSPaul Moore#ifdef __linux__ 39030f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 39040f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 39050f66998fSPaul Moore QEMU_ARCH_ALL) 39060f66998fSPaul Moore#endif 39070f66998fSPaul MooreSTEXI 39080f66998fSPaul Moore@item -enable-fips 39090f66998fSPaul Moore@findex -enable-fips 39100f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 39110f66998fSPaul MooreETEXI 39120f66998fSPaul Moore 3913a0dac021SJan KiszkaHXCOMM Deprecated by -machine accel=tcg property 3914c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3915a0dac021SJan Kiszka 39165e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 39175e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 39185e2ac519SSeiji Aguchi " change the format of messages\n" 39195e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 39205e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 39215e2ac519SSeiji AguchiSTEXI 39225e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 39235e2ac519SSeiji Aguchi@findex -msg 39245e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 39255e2ac519SSeiji AguchiETEXI 39265e2ac519SSeiji Aguchi 3927abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 3928abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 3929abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 3930abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 3931abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 39322382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 3933abfd9ce3SAmit Shah QEMU_ARCH_ALL) 3934abfd9ce3SAmit ShahSTEXI 3935abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 3936abfd9ce3SAmit Shah@findex -dump-vmstate 3937abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 3938abfd9ce3SAmit Shahin @var{file} 3939abfd9ce3SAmit ShahETEXI 3940abfd9ce3SAmit Shah 394143f187a5SPaolo BonziniSTEXI 394243f187a5SPaolo Bonzini@end table 394343f187a5SPaolo BonziniETEXI 394443f187a5SPaolo BonziniDEFHEADING() 3945de6b4f90SMarkus Armbruster 3946de6b4f90SMarkus ArmbrusterDEFHEADING(Generic object creation:) 394743f187a5SPaolo BonziniSTEXI 394843f187a5SPaolo Bonzini@table @option 394943f187a5SPaolo BonziniETEXI 3950b9174d4fSDaniel P. Berrange 3951b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 3952b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 3953b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 3954b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 3955b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 3956b9174d4fSDaniel P. Berrange " '/objects' path.\n", 3957b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 3958b9174d4fSDaniel P. BerrangeSTEXI 3959b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3960b9174d4fSDaniel P. Berrange@findex -object 3961b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 3962b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 3963b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 3964b9174d4fSDaniel P. Berrange'/objects' path. 3965b9174d4fSDaniel P. Berrange 3966b9174d4fSDaniel P. Berrange@table @option 3967b9174d4fSDaniel P. Berrange 396898376843SHaozhong 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} 3969b9174d4fSDaniel P. Berrange 3970b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 3971c7cddce1SStefan Hajnoczithe guest RAM with huge pages. 3972c7cddce1SStefan Hajnoczi 3973c7cddce1SStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 3974c7cddce1SStefan Hajnoczimemory region when configuring the @option{-numa} argument. 3975c7cddce1SStefan Hajnoczi 3976c7cddce1SStefan HajnocziThe @option{size} option provides the size of the memory region, and accepts 3977c7cddce1SStefan Hajnoczicommon suffixes, eg @option{500M}. 3978c7cddce1SStefan Hajnoczi 3979c7cddce1SStefan HajnocziThe @option{mem-path} provides the path to either a shared memory or huge page 3980c7cddce1SStefan Hajnoczifilesystem mount. 3981c7cddce1SStefan Hajnoczi 3982b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 3983b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 3984b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 3985c7cddce1SStefan Hajnoczi 398606329cceSMarcel ApfelbaumThe @option{share} is also required for pvrdma devices due to 398706329cceSMarcel Apfelbaumlimitations in the RDMA API provided by Linux. 398806329cceSMarcel Apfelbaum 398906329cceSMarcel ApfelbaumSetting share=on might affect the ability to configure NUMA 399006329cceSMarcel Apfelbaumbindings for the memory backend under some circumstances, see 399106329cceSMarcel ApfelbaumDocumentation/vm/numa_memory_policy.txt on the Linux kernel 399206329cceSMarcel Apfelbaumsource tree for additional details. 399306329cceSMarcel Apfelbaum 399411ae6ed8SEduardo HabkostSetting the @option{discard-data} boolean option to @var{on} 399511ae6ed8SEduardo Habkostindicates that file contents can be destroyed when QEMU exits, 399611ae6ed8SEduardo Habkostto avoid unnecessarily flushing data to the backing file. Note 399711ae6ed8SEduardo Habkostthat @option{discard-data} is only an optimization, and QEMU 399811ae6ed8SEduardo Habkostmight not discard file contents if it aborts unexpectedly or is 399911ae6ed8SEduardo Habkostterminated using SIGKILL. 4000b9174d4fSDaniel P. Berrange 4001c7cddce1SStefan HajnocziThe @option{merge} boolean option enables memory merge, also known as 4002c7cddce1SStefan HajnocziMADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 4003c7cddce1SStefan Hajnoczimemory deduplication. 4004c7cddce1SStefan Hajnoczi 4005c7cddce1SStefan HajnocziSetting the @option{dump} boolean option to @var{off} excludes the memory from 4006c7cddce1SStefan Hajnoczicore dumps. This feature is also known as MADV_DONTDUMP. 4007c7cddce1SStefan Hajnoczi 4008c7cddce1SStefan HajnocziThe @option{prealloc} boolean option enables memory preallocation. 4009c7cddce1SStefan Hajnoczi 4010c7cddce1SStefan HajnocziThe @option{host-nodes} option binds the memory range to a list of NUMA host 4011c7cddce1SStefan Hajnoczinodes. 4012c7cddce1SStefan Hajnoczi 4013c7cddce1SStefan HajnocziThe @option{policy} option sets the NUMA policy to one of the following values: 4014c7cddce1SStefan Hajnoczi 4015c7cddce1SStefan Hajnoczi@table @option 4016c7cddce1SStefan Hajnoczi@item @var{default} 4017c7cddce1SStefan Hajnoczidefault host policy 4018c7cddce1SStefan Hajnoczi 4019c7cddce1SStefan Hajnoczi@item @var{preferred} 4020c7cddce1SStefan Hajnocziprefer the given host node list for allocation 4021c7cddce1SStefan Hajnoczi 4022c7cddce1SStefan Hajnoczi@item @var{bind} 4023c7cddce1SStefan Hajnoczirestrict memory allocation to the given host node list 4024c7cddce1SStefan Hajnoczi 4025c7cddce1SStefan Hajnoczi@item @var{interleave} 4026c7cddce1SStefan Hajnocziinterleave memory allocations across the given host node list 4027c7cddce1SStefan Hajnoczi@end table 4028c7cddce1SStefan Hajnoczi 402998376843SHaozhong ZhangThe @option{align} option specifies the base address alignment when 403098376843SHaozhong ZhangQEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 403198376843SHaozhong Zhang@option{2M}. Some backend store specified by @option{mem-path} 403298376843SHaozhong Zhangrequires an alignment different than the default one used by QEMU, eg 403398376843SHaozhong Zhangthe device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 403498376843SHaozhong Zhangsuch cases, users can specify the required alignment via this option. 403598376843SHaozhong Zhang 403606329cceSMarcel 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} 4037cd19491aSStefan Hajnoczi 4038cd19491aSStefan HajnocziCreates a memory backend object, which can be used to back the guest RAM. 4039cd19491aSStefan HajnocziMemory backend objects offer more control than the @option{-m} option that is 4040cd19491aSStefan Hajnoczitraditionally used to define guest RAM. Please refer to 4041cd19491aSStefan Hajnoczi@option{memory-backend-file} for a description of the options. 4042cd19491aSStefan Hajnoczi 4043dbb9e0f4SMarc-André Lureau@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@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} 4044dbb9e0f4SMarc-André Lureau 4045dbb9e0f4SMarc-André LureauCreates an anonymous memory file backend object, which allows QEMU to 4046dbb9e0f4SMarc-André Lureaushare the memory with an external process (e.g. when using 4047dbb9e0f4SMarc-André Lureauvhost-user). The memory is allocated with memfd and optional 4048dbb9e0f4SMarc-André Lureausealing. (Linux only) 4049dbb9e0f4SMarc-André Lureau 4050dbb9e0f4SMarc-André LureauThe @option{seal} option creates a sealed-file, that will block 4051dbb9e0f4SMarc-André Lureaufurther resizing the memory ('on' by default). 4052dbb9e0f4SMarc-André Lureau 4053dbb9e0f4SMarc-André LureauThe @option{hugetlb} option specify the file to be created resides in 4054dbb9e0f4SMarc-André Lureauthe hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 4055dbb9e0f4SMarc-André Lureauthe @option{hugetlb} option, the @option{hugetlbsize} option specify 4056dbb9e0f4SMarc-André Lureauthe hugetlb page size on systems that support multiple hugetlb page 4057dbb9e0f4SMarc-André Lureausizes (it must be a power of 2 value supported by the system). 4058dbb9e0f4SMarc-André Lureau 4059dbb9e0f4SMarc-André LureauIn some versions of Linux, the @option{hugetlb} option is incompatible 4060dbb9e0f4SMarc-André Lureauwith the @option{seal} option (requires at least Linux 4.16). 4061dbb9e0f4SMarc-André Lureau 4062dbb9e0f4SMarc-André LureauPlease refer to @option{memory-backend-file} for a description of the 4063dbb9e0f4SMarc-André Lureauother options. 4064dbb9e0f4SMarc-André Lureau 4065b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4066b9174d4fSDaniel P. Berrange 4067b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4068b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 4069b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 4070b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 4071b9174d4fSDaniel P. Berrangeentropy from and if omitted defaults to @option{/dev/random}. 4072b9174d4fSDaniel P. Berrange 4073b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4074b9174d4fSDaniel P. Berrange 4075b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4076b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 4077b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 4078b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 4079b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 4080b9174d4fSDaniel P. Berrangeto the RNG daemon. 4081b9174d4fSDaniel P. Berrange 4082e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4083e00adf6cSDaniel P. Berrange 4084e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 4085e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 4086e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 4087e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 4088e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 4089e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 4090e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 4091e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 4092e00adf6cSDaniel P. Berrange 4093e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 4094e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 4095e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 4096e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 4097e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 4098e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 4099e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 4100e00adf6cSDaniel P. Berrangeupfront and saved. 4101e00adf6cSDaniel P. Berrange 410200e5e9dfSChristophe 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} 410385bcbc78SDaniel P. Berrange 410485bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 410585bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 410685bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 410785bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 410885bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 410985bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 411085bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 411185bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 411285bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 411385bcbc78SDaniel P. Berrange 411485bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 411585bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 411685bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 411785bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 411885bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 411985bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 412085bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 412185bcbc78SDaniel P. Berrangeupfront and saved. 412285bcbc78SDaniel P. Berrange 412385bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 412485bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 412585bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 412685bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 412785bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 412885bcbc78SDaniel P. Berrange 41291d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 41301d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 41311d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 41321d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 41331d7b5b4aSDaniel P. Berrangepassword for decryption. 41341d7b5b4aSDaniel P. Berrange 413500e5e9dfSChristophe FergeauThe @var{priority} parameter allows to override the global default 413600e5e9dfSChristophe Fergeaupriority used by gnutls. This can be useful if the system administrator 413700e5e9dfSChristophe Fergeauneeds to use a weaker set of crypto priorities for QEMU without 413800e5e9dfSChristophe Fergeaupotentially forcing the weakness onto all applications. Or conversely 413900e5e9dfSChristophe Fergeauif one wants wants a stronger default for QEMU than for all other 414000e5e9dfSChristophe Fergeauapplications, they can do this through this parameter. Its format is 414100e5e9dfSChristophe Fergeaua gnutls priority string as described at 414200e5e9dfSChristophe Fergeau@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 414300e5e9dfSChristophe Fergeau 4144338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 41457dbb11c8SYang Hongyang 41467dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 41477dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 41487dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 4149338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 4150338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 41517dbb11c8SYang Hongyang 41527dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 41537dbb11c8SYang Hongyang 41547dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 41557dbb11c8SYang Hongyang queue of the netdev (default). 41567dbb11c8SYang Hongyang 41577dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 41587dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 41597dbb11c8SYang Hongyang 41607dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 41617dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 41627dbb11c8SYang Hongyang 4163e2521f0eSZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4164f6d3afb5SZhang Chen 4165e2521f0eSZhang 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. 4166f6d3afb5SZhang Chen 416700d5c240SZhang 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] 4168d46f75b2SZhang Chen 4169d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 417000d5c240SZhang Chen@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 417100d5c240SZhang Chenfilter-redirector will redirect packet with vnet_hdr_len. 4172d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 4173d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 4174d46f75b2SZhang Chenneed to be specified. 4175d46f75b2SZhang Chen 41764b39bdceSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4177e6eee8abSZhang Chen 4178e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 4179e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 4180e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 41814b39bdceSZhang Chenclient.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4182e6eee8abSZhang Chen 4183e6eee8abSZhang Chenusage: 4184e6eee8abSZhang Chencolo secondary: 4185e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4186e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4187e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4188e6eee8abSZhang Chen 4189c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4190d3e0c032SThomas Huth 4191d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 4192d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4193d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 4194d3e0c032SThomas Huthor Wireshark. 4195d3e0c032SThomas Huth 4196aa3a7032SZhang Chen@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid}[,vnet_hdr_support] 41977dce4e6fSZhang Chen 41987dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 41997dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 42007dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 42017dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 4202aa3a7032SZhang Chenif it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len. 42037dce4e6fSZhang Chen 42047dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 42057dce4e6fSZhang Chen 42067dce4e6fSZhang Chen@example 42077dce4e6fSZhang Chen 42087dce4e6fSZhang Chenprimary: 42097dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 42107dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 42117dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 42127dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 42137dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 42147dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 42157dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 42167dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 42177dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 42187dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 42197dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 42207dce4e6fSZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0 42217dce4e6fSZhang Chen 42227dce4e6fSZhang Chensecondary: 42237dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 42247dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 42257dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 42267dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 42277dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 42287dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 42297dce4e6fSZhang Chen 42307dce4e6fSZhang Chen@end example 42317dce4e6fSZhang Chen 42327dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 42337dce4e6fSZhang Chenthe colo-compare git log. 42347dce4e6fSZhang Chen 42351653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 42361653a5f3SGonglei 42371653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 42381653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 42391653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 42401653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 42411653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 42421653a5f3SGonglei@var{queues} is 1. 42431653a5f3SGonglei 42441653a5f3SGonglei@example 42451653a5f3SGonglei 42461653a5f3SGonglei # qemu-system-x86_64 \ 42471653a5f3SGonglei [...] \ 42481653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 42491653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 42501653a5f3SGonglei [...] 42511653a5f3SGonglei@end example 42521653a5f3SGonglei 4253042cea27SGonglei@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 4254042cea27SGonglei 4255042cea27SGongleiCreates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 4256042cea27SGongleiThe @var{id} parameter is a unique ID that will be used to reference this 4257042cea27SGongleicryptodev backend from the @option{virtio-crypto} device. 4258042cea27SGongleiThe chardev should be a unix domain socket backed one. The vhost-user uses 4259042cea27SGongleia specifically defined protocol to pass vhost ioctl replacement messages 4260042cea27SGongleito an application on the other end of the socket. 4261042cea27SGongleiThe @var{queues} parameter is optional, which specify the queue number 4262042cea27SGongleiof cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 4263042cea27SGonglei 4264042cea27SGonglei@example 4265042cea27SGonglei 4266042cea27SGonglei # qemu-system-x86_64 \ 4267042cea27SGonglei [...] \ 4268042cea27SGonglei -chardev socket,id=chardev0,path=/path/to/socket \ 4269042cea27SGonglei -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 4270042cea27SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4271042cea27SGonglei [...] 4272042cea27SGonglei@end example 4273042cea27SGonglei 4274ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4275ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4276ac1d8878SDaniel P. Berrange 4277ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4278ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4279ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4280ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4281ac1d8878SDaniel P. Berrange 4282ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4283ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4284ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4285ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4286ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4287ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4288ac1d8878SDaniel P. Berrange 4289ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4290ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4291ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4292ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4293ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4294ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4295ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 429669c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4297ac1d8878SDaniel P. Berrange 4298ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4299ac1d8878SDaniel P. Berrange 4300ac1d8878SDaniel P. Berrange@example 4301ac1d8878SDaniel P. Berrange 4302ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,data=letmein,format=raw 4303ac1d8878SDaniel P. Berrange 4304ac1d8878SDaniel P. Berrange@end example 4305ac1d8878SDaniel P. Berrange 4306ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4307ac1d8878SDaniel P. Berrange 4308b43671f8SEric Blake # printf "letmein" > mypasswd.txt 4309ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 4310ac1d8878SDaniel P. Berrange 4311ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4312ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4313ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4314ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4315ac1d8878SDaniel P. Berrange 4316ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4317ac1d8878SDaniel P. Berrange 4318ac1d8878SDaniel P. Berrange@example 4319ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4320ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4321ac1d8878SDaniel P. Berrange@end example 4322ac1d8878SDaniel P. Berrange 4323ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4324ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4325ac1d8878SDaniel P. Berrange 4326ac1d8878SDaniel P. Berrange@example 4327ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4328ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4329ac1d8878SDaniel P. Berrange@end example 4330ac1d8878SDaniel P. Berrange 4331ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4332ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4333ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4334ac1d8878SDaniel P. Berrange 4335ac1d8878SDaniel P. Berrange@example 4336b43671f8SEric Blake # SECRET=$(printf "letmein" | 4337ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4338ac1d8878SDaniel P. Berrange@end example 4339ac1d8878SDaniel P. Berrange 4340ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4341ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4342ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4343ac1d8878SDaniel P. Berrange 4344ac1d8878SDaniel P. Berrange@example 4345ac1d8878SDaniel P. Berrange # $QEMU \ 4346ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4347ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4348ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4349ac1d8878SDaniel P. Berrange@end example 4350ac1d8878SDaniel P. Berrange 4351a9b4942fSBrijesh 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}] 4352a9b4942fSBrijesh Singh 4353a9b4942fSBrijesh SinghCreate a Secure Encrypted Virtualization (SEV) guest object, which can be used 4354a9b4942fSBrijesh Singhto provide the guest memory encryption support on AMD processors. 4355a9b4942fSBrijesh Singh 4356a9b4942fSBrijesh SinghWhen memory encryption is enabled, one of the physical address bit (aka the 4357a9b4942fSBrijesh SinghC-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 4358a9b4942fSBrijesh Singhis used to provide the C-bit position. The C-bit position is Host family dependent 4359a9b4942fSBrijesh Singhhence user must provide this value. On EPYC, the value should be 47. 4360a9b4942fSBrijesh Singh 4361a9b4942fSBrijesh SinghWhen memory encryption is enabled, we loose certain bits in physical address space. 4362a9b4942fSBrijesh SinghThe @option{reduced-phys-bits} is used to provide the number of bits we loose in 4363a9b4942fSBrijesh Singhphysical address space. Similar to C-bit, the value is Host family dependent. 4364a9b4942fSBrijesh SinghOn EPYC, the value should be 5. 4365a9b4942fSBrijesh Singh 4366a9b4942fSBrijesh SinghThe @option{sev-device} provides the device file to use for communicating with 4367a9b4942fSBrijesh Singhthe SEV firmware running inside AMD Secure Processor. The default device is 4368a9b4942fSBrijesh Singh'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 4369a9b4942fSBrijesh Singhcreated by CCP driver. 4370a9b4942fSBrijesh Singh 4371a9b4942fSBrijesh SinghThe @option{policy} provides the guest policy to be enforced by the SEV firmware 4372a9b4942fSBrijesh Singhand restrict what configuration and operational commands can be performed on this 4373a9b4942fSBrijesh Singhguest by the hypervisor. The policy should be provided by the guest owner and is 4374a9b4942fSBrijesh Singhbound to the guest and cannot be changed throughout the lifetime of the guest. 4375a9b4942fSBrijesh SinghThe default is 0. 4376a9b4942fSBrijesh Singh 4377a9b4942fSBrijesh SinghIf guest @option{policy} allows sharing the key with another SEV guest then 4378a9b4942fSBrijesh Singh@option{handle} can be use to provide handle of the guest from which to share 4379a9b4942fSBrijesh Singhthe key. 4380a9b4942fSBrijesh Singh 4381a9b4942fSBrijesh SinghThe @option{dh-cert-file} and @option{session-file} provides the guest owner's 4382a9b4942fSBrijesh SinghPublic Diffie-Hillman key defined in SEV spec. The PDH and session parameters 4383a9b4942fSBrijesh Singhare used for establishing a cryptographic session with the guest owner to 4384a9b4942fSBrijesh Singhnegotiate keys used for attestation. The file must be encoded in base64. 4385a9b4942fSBrijesh Singh 4386a9b4942fSBrijesh Singhe.g to launch a SEV guest 4387a9b4942fSBrijesh Singh@example 4388a9b4942fSBrijesh Singh # $QEMU \ 4389a9b4942fSBrijesh Singh ...... 4390a9b4942fSBrijesh Singh -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 4391a9b4942fSBrijesh Singh -machine ...,memory-encryption=sev0 4392a9b4942fSBrijesh Singh ..... 4393a9b4942fSBrijesh Singh 4394a9b4942fSBrijesh Singh@end example 4395b9174d4fSDaniel P. Berrange@end table 4396b9174d4fSDaniel P. Berrange 4397b9174d4fSDaniel P. BerrangeETEXI 4398b9174d4fSDaniel P. Berrange 4399b9174d4fSDaniel P. Berrange 44003dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 44013dbf2c7fSStefan WeilSTEXI 44023dbf2c7fSStefan Weil@end table 44033dbf2c7fSStefan WeilETEXI 4404