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" 378490fc78SLuiz Capitulino " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 38a52a7fdfSLe Tan " mem-merge=on|off controls memory merge support (default: on)\n" 392eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 409850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4187252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 42902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 43274250c3SXiao Feng Ren " enforce-config-section=on|off enforce configuration section migration (default=off)\n" 44db588194SBrijesh Singh " memory-encryption=@var{} memory encryption object to use (default=none)\n", 4580f52a66SJan Kiszka QEMU_ARCH_ALL) 465824d651Sblueswir1STEXI 4780f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 4880f52a66SJan Kiszka@findex -machine 49585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 508bfce83aSDaniel P. Berrangeavailable machines. 518bfce83aSDaniel P. Berrange 528bfce83aSDaniel P. BerrangeFor architectures which aim to support live migration compatibility 538bfce83aSDaniel P. Berrangeacross releases, each release will introduce a new versioned machine 548bfce83aSDaniel P. Berrangetype. For example, the 2.8.0 release introduced machine types 558bfce83aSDaniel P. Berrange``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 568bfce83aSDaniel P. Berrange 578bfce83aSDaniel P. BerrangeTo allow live migration of guests from QEMU version 2.8.0, to QEMU 588bfce83aSDaniel P. Berrangeversion 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 598bfce83aSDaniel P. Berrangeand ``pc-q35-2.8'' machines too. To allow users live migrating VMs 608bfce83aSDaniel P. Berrangeto skip multiple intermediate releases when upgrading, new releases 618bfce83aSDaniel P. Berrangeof QEMU will support machine types from many previous versions. 628bfce83aSDaniel P. Berrange 638bfce83aSDaniel P. BerrangeSupported machine properties are: 6480f52a66SJan Kiszka@table @option 6580f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 6680f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 67d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 68bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 69bde4d920SThomas Huthfails to initialize. 706a48ffaaSJan Kiszka@item kernel_irqchip=on|off 7132c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 72d1048befSDon Slutz@item vmport=on|off|auto 73d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 74d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 75d1048befSDon Slutzis on. 76ddb97f1dSJason Baron@item dump-guest-core=on|off 77ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 788490fc78SLuiz Capitulino@item mem-merge=on|off 798490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 808490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 818490fc78SLuiz Capitulino(enabled by default). 822eb1cd07STony Krowiak@item aes-key-wrap=on|off 832eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 842eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 852eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 862eb1cd07STony Krowiak@item dea-key-wrap=on|off 872eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 882eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 892eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 9087252e1bSXiao Guangrong@item nvdimm=on|off 9187252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 9216f72448SPeter Xu@item enforce-config-section=on|off 9316f72448SPeter XuIf @option{enforce-config-section} is set to @var{on}, force migration 9416f72448SPeter Xucode to send configuration section even if the machine-type sets the 9516f72448SPeter Xu@option{migration.send-configuration} property to @var{off}. 9616f72448SPeter XuNOTE: this parameter is deprecated. Please use @option{-global} 9716f72448SPeter Xu@option{migration.send-configuration}=@var{on|off} instead. 98db588194SBrijesh Singh@item memory-encryption=@var{} 99db588194SBrijesh SinghMemory encryption object to use. The default is none. 10080f52a66SJan Kiszka@end table 1015824d651Sblueswir1ETEXI 1025824d651Sblueswir1 10380f52a66SJan KiszkaHXCOMM Deprecated by -machine 10480f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 10580f52a66SJan Kiszka 1065824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 107585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 1085824d651Sblueswir1STEXI 1095824d651Sblueswir1@item -cpu @var{model} 1106616b2adSStefan Weil@findex -cpu 111585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 1125824d651Sblueswir1ETEXI 1135824d651Sblueswir1 1148d4e9146SKONRAD FredericDEF("accel", HAS_ARG, QEMU_OPTION_accel, 115fe174132SPaolo Bonzini "-accel [accel=]accelerator[,prop[=value][,...]]\n" 116d661d9a4SJustin Terry (VM) " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n" 11746472d82SPaolo Bonzini " igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n" 118*23b0898eSPaolo Bonzini " kvm-shadow-mem=size of KVM shadow MMU in bytes\n" 119fe174132SPaolo Bonzini " tb-size=n (TCG translation block cache size)\n" 1200b3c5c81SEduardo Habkost " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL) 1218d4e9146SKONRAD FredericSTEXI 1228d4e9146SKONRAD Frederic@item -accel @var{name}[,prop=@var{value}[,...]] 1238d4e9146SKONRAD Frederic@findex -accel 1248d4e9146SKONRAD FredericThis is used to enable an accelerator. Depending on the target architecture, 125d661d9a4SJustin Terry (VM)kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 126bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 127bde4d920SThomas Huthfails to initialize. 1288d4e9146SKONRAD Frederic@table @option 12946472d82SPaolo Bonzini@item igd-passthru=on|off 13046472d82SPaolo BonziniWhen Xen is in use, this option controls whether Intel integrated graphics 13146472d82SPaolo Bonzinidevices can be passed through to the guest (default=off) 132*23b0898eSPaolo Bonzini@item kvm-shadow-mem=size 133*23b0898eSPaolo BonziniDefines the size of the KVM shadow MMU. 134fe174132SPaolo Bonzini@item tb-size=@var{n} 135fe174132SPaolo BonziniControls the size (in MiB) of the TCG translation block cache. 1368d4e9146SKONRAD Frederic@item thread=single|multi 1378d4e9146SKONRAD FredericControls number of TCG threads. When the TCG is multi-threaded there will be one 1388d4e9146SKONRAD Fredericthread per vCPU therefor taking advantage of additional host cores. The default 1398d4e9146SKONRAD Fredericis to enable multi-threading where both the back-end and front-ends support it and 1408d4e9146SKONRAD Fredericno incompatible TCG features have been enabled (e.g. icount/replay). 1418d4e9146SKONRAD Frederic@end table 1428d4e9146SKONRAD FredericETEXI 1438d4e9146SKONRAD Frederic 1445824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 1451b458422SLike Xu "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n" 1466be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1476be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 148ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 1491b458422SLike Xu " cores= number of CPU cores on one socket (for PC, it's on one die)\n" 15058a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 1511b458422SLike Xu " dies= number of CPU dies on one socket (for PC only)\n" 152ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 153ad96090aSBlue Swirl QEMU_ARCH_ALL) 1545824d651Sblueswir1STEXI 1551b458422SLike Xu@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1566616b2adSStefan Weil@findex -smp 1575824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1585824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1595824d651Sblueswir1to 4. 1601b458422SLike XuFor the PC target, the number of @var{cores} per die, the number of @var{threads} 1611b458422SLike Xuper cores, the number of @var{dies} per packages and the total number of 1621b458422SLike Xu@var{sockets} can be specified. Missing values will be computed. 1631b458422SLike XuIf any on the three values is given, the total number of CPUs @var{n} can be omitted. 1641b458422SLike Xu@var{maxcpus} specifies the maximum number of hotpluggable CPUs. 1655824d651Sblueswir1ETEXI 1665824d651Sblueswir1 167268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 168e0ee9fd0SEduardo Habkost "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1690f203430SHe Chen "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1702d19c656SIgor Mammedov "-numa dist,src=source,dst=destination,val=distance\n" 1712d19c656SIgor Mammedov "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n", 1722d19c656SIgor Mammedov QEMU_ARCH_ALL) 173268a362cSaliguoriSTEXI 174e0ee9fd0SEduardo Habkost@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 175e0ee9fd0SEduardo Habkost@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 1760f203430SHe Chen@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 177419fcdecSIgor Mammedov@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 1786616b2adSStefan Weil@findex -numa 1794b9a5dd7SEduardo HabkostDefine a NUMA node and assign RAM and VCPUs to it. 1800f203430SHe ChenSet the NUMA distance from a source node to a destination node. 1817febe36fSPaolo Bonzini 182419fcdecSIgor MammedovLegacy VCPU assignment uses @samp{cpus} option where 1834b9a5dd7SEduardo Habkost@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 1844b9a5dd7SEduardo Habkost@samp{cpus} option represent a contiguous range of CPU indexes 1854b9a5dd7SEduardo Habkost(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 1864b9a5dd7SEduardo Habkostset of VCPUs can be represented by providing multiple @samp{cpus} 1874b9a5dd7SEduardo Habkostoptions. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 1884b9a5dd7SEduardo Habkostsplit between them. 1894b9a5dd7SEduardo Habkost 1904b9a5dd7SEduardo HabkostFor example, the following option assigns VCPUs 0, 1, 2 and 5 to 1914b9a5dd7SEduardo Habkosta NUMA node: 1924b9a5dd7SEduardo Habkost@example 1934b9a5dd7SEduardo Habkost-numa node,cpus=0-2,cpus=5 1944b9a5dd7SEduardo Habkost@end example 1954b9a5dd7SEduardo Habkost 196419fcdecSIgor Mammedov@samp{cpu} option is a new alternative to @samp{cpus} option 197419fcdecSIgor Mammedovwhich uses @samp{socket-id|core-id|thread-id} properties to assign 198419fcdecSIgor MammedovCPU objects to a @var{node} using topology layout properties of CPU. 199419fcdecSIgor MammedovThe set of properties is machine specific, and depends on used 200419fcdecSIgor Mammedovmachine type/@samp{smp} options. It could be queried with 201419fcdecSIgor Mammedov@samp{hotpluggable-cpus} monitor command. 202419fcdecSIgor Mammedov@samp{node-id} property specifies @var{node} to which CPU object 203419fcdecSIgor Mammedovwill be assigned, it's required for @var{node} to be declared 204419fcdecSIgor Mammedovwith @samp{node} option before it's used with @samp{cpu} option. 205419fcdecSIgor Mammedov 206419fcdecSIgor MammedovFor example: 207419fcdecSIgor Mammedov@example 208419fcdecSIgor Mammedov-M pc \ 209419fcdecSIgor Mammedov-smp 1,sockets=2,maxcpus=2 \ 210419fcdecSIgor Mammedov-numa node,nodeid=0 -numa node,nodeid=1 \ 211419fcdecSIgor Mammedov-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 212419fcdecSIgor Mammedov@end example 213419fcdecSIgor Mammedov 2144b9a5dd7SEduardo Habkost@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 2154b9a5dd7SEduardo Habkostassigns RAM from a given memory backend device to a node. If 2164b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 2174b9a5dd7SEduardo Habkostsplit equally between them. 2184b9a5dd7SEduardo Habkost 2194b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 2204b9a5dd7SEduardo Habkostif one node uses @samp{memdev}, all of them have to use it. 2214b9a5dd7SEduardo Habkost 2220f203430SHe Chen@var{source} and @var{destination} are NUMA node IDs. 2230f203430SHe Chen@var{distance} is the NUMA distance from @var{source} to @var{destination}. 2240f203430SHe ChenThe distance from a node to itself is always 10. If any pair of nodes is 2250f203430SHe Chengiven a distance, then all pairs must be given distances. Although, when 2260f203430SHe Chendistances are only given in one direction for each pair of nodes, then 2270f203430SHe Chenthe distances in the opposite directions are assumed to be the same. If, 2280f203430SHe Chenhowever, an asymmetrical pair of distances is given for even one node 2290f203430SHe Chenpair, then all node pairs must be provided distance values for both 2300f203430SHe Chendirections, even when they are symmetrical. When a node is unreachable 2310f203430SHe Chenfrom another node, set the pair's distance to 255. 2320f203430SHe Chen 2334b9a5dd7SEduardo HabkostNote that the -@option{numa} option doesn't allocate any of the 2344b9a5dd7SEduardo Habkostspecified resources, it just assigns existing resources to NUMA 2354b9a5dd7SEduardo Habkostnodes. This means that one still has to use the @option{-m}, 2364b9a5dd7SEduardo Habkost@option{-smp} options to allocate RAM and VCPUs respectively. 2374b9a5dd7SEduardo Habkost 238268a362cSaliguoriETEXI 239268a362cSaliguori 24010adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 24110adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 24210adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 24310adb8beSMarkus ArmbrusterSTEXI 24410adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 24510adb8beSMarkus Armbruster@findex -add-fd 24610adb8beSMarkus Armbruster 24710adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 24810adb8beSMarkus Armbruster 24910adb8beSMarkus Armbruster@table @option 25010adb8beSMarkus Armbruster@item fd=@var{fd} 25110adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 25210adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 25310adb8beSMarkus Armbruster@item set=@var{set} 25410adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 25510adb8beSMarkus Armbruster@item opaque=@var{opaque} 25610adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 25710adb8beSMarkus Armbruster@end table 25810adb8beSMarkus Armbruster 25910adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 26010adb8beSMarkus Armbruster@example 261664785acSThomas Huth@value{qemu_system} \ 262664785acSThomas Huth -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 263664785acSThomas Huth -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 26410adb8beSMarkus Armbruster -drive file=/dev/fdset/2,index=0,media=disk 26510adb8beSMarkus Armbruster@end example 26610adb8beSMarkus ArmbrusterETEXI 26710adb8beSMarkus Armbruster 26810adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 26910adb8beSMarkus Armbruster "-set group.id.arg=value\n" 27010adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 27110adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 27210adb8beSMarkus ArmbrusterSTEXI 27310adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 27410adb8beSMarkus Armbruster@findex -set 275e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 27610adb8beSMarkus ArmbrusterETEXI 27710adb8beSMarkus Armbruster 27810adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 2793751d7c4SPaolo Bonzini "-global driver.property=value\n" 2803751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 28110adb8beSMarkus Armbruster " set a global default for a driver property\n", 28210adb8beSMarkus Armbruster QEMU_ARCH_ALL) 28310adb8beSMarkus ArmbrusterSTEXI 28410adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 2853751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 28610adb8beSMarkus Armbruster@findex -global 28710adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 28810adb8beSMarkus Armbruster 28910adb8beSMarkus Armbruster@example 290664785acSThomas Huth@value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img 29110adb8beSMarkus Armbruster@end example 29210adb8beSMarkus Armbruster 29310adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 29410adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 29510adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 2963751d7c4SPaolo Bonzini 297ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 298ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 299ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 30010adb8beSMarkus ArmbrusterETEXI 30110adb8beSMarkus Armbruster 30210adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 30310adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 304c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 30510adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 30610adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 30710adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 30810adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 30910adb8beSMarkus Armbruster QEMU_ARCH_ALL) 31010adb8beSMarkus ArmbrusterSTEXI 311c8a6ae8bSAmos 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] 31210adb8beSMarkus Armbruster@findex -boot 31310adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 314d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 31510adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 31610adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 31710adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 318c0d9f7d0SThomas Huth@option{once}. Note that the @option{order} or @option{once} parameter 319c0d9f7d0SThomas Huthshould not be used together with the @option{bootindex} property of 320c0d9f7d0SThomas Huthdevices, since the firmware implementations normally do not support both 321c0d9f7d0SThomas Huthat the same time. 32210adb8beSMarkus Armbruster 32310adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 32410adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 32510adb8beSMarkus Armbruster 32610adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 32710adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 32810adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 32910adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 33010adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 33110adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 33210adb8beSMarkus Armbruster 33310adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 334bbd9e698SHan Hanwhen boot failed, then reboot. If @option{reboot-timeout} is not set, 335bbd9e698SHan Hanguest will not reboot by default. Currently Seabios for X86 33610adb8beSMarkus Armbrustersystem support it. 33710adb8beSMarkus Armbruster 338c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 339c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 340c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 341c8a6ae8bSAmos Kong 34210adb8beSMarkus Armbruster@example 34310adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 344664785acSThomas Huth@value{qemu_system_x86} -boot order=nc 34510adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 346664785acSThomas Huth@value{qemu_system_x86} -boot once=d 34710adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 348664785acSThomas Huth@value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000 34910adb8beSMarkus Armbruster@end example 35010adb8beSMarkus Armbruster 35110adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 35210adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 35310adb8beSMarkus ArmbrusterETEXI 35410adb8beSMarkus Armbruster 35510adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 35689f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 3576e1d3c1cSIgor Mammedov " configure guest RAM\n" 3580daba1f0SAlexander Graf " size: initial amount of guest memory\n" 359c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 360b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 361b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 3626e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 36310adb8beSMarkus ArmbrusterSTEXI 3649fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 36510adb8beSMarkus Armbruster@findex -m 3669fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 3679fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 3689fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 3699fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 3709fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 3719fcc0794SLuiz Capitulino 3729fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 3739fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 3749fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 3759fcc0794SLuiz Capitulino 3769fcc0794SLuiz Capitulino@example 377664785acSThomas Huth@value{qemu_system} -m 1G,slots=3,maxmem=4G 3789fcc0794SLuiz Capitulino@end example 3799fcc0794SLuiz Capitulino 3809fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 3819fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 38210adb8beSMarkus ArmbrusterETEXI 38310adb8beSMarkus Armbruster 38410adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 38510adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 38610adb8beSMarkus ArmbrusterSTEXI 38710adb8beSMarkus Armbruster@item -mem-path @var{path} 38810adb8beSMarkus Armbruster@findex -mem-path 38910adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 39010adb8beSMarkus ArmbrusterETEXI 39110adb8beSMarkus Armbruster 39210adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 39310adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 39410adb8beSMarkus Armbruster QEMU_ARCH_ALL) 39510adb8beSMarkus ArmbrusterSTEXI 39610adb8beSMarkus Armbruster@item -mem-prealloc 39710adb8beSMarkus Armbruster@findex -mem-prealloc 39810adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 39910adb8beSMarkus ArmbrusterETEXI 40010adb8beSMarkus Armbruster 40110adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 40210adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 40310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 40410adb8beSMarkus ArmbrusterSTEXI 40510adb8beSMarkus Armbruster@item -k @var{language} 40610adb8beSMarkus Armbruster@findex -k 40710adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 40810adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 40932945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 41010adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 41110adb8beSMarkus Armbrusterhosts. 41210adb8beSMarkus Armbruster 41310adb8beSMarkus ArmbrusterThe available layouts are: 41410adb8beSMarkus Armbruster@example 41510adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 41610adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 41710adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 41810adb8beSMarkus Armbruster@end example 41910adb8beSMarkus Armbruster 42010adb8beSMarkus ArmbrusterThe default is @code{en-us}. 42110adb8beSMarkus ArmbrusterETEXI 42210adb8beSMarkus Armbruster 42310adb8beSMarkus Armbruster 424f0b3d811SKővágó, ZoltánHXCOMM Deprecated by -audiodev 42510adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 426f0b3d811SKővágó, Zoltán "-audio-help show -audiodev equivalent of the currently specified audio settings\n", 42710adb8beSMarkus Armbruster QEMU_ARCH_ALL) 42810adb8beSMarkus ArmbrusterSTEXI 42910adb8beSMarkus Armbruster@item -audio-help 43010adb8beSMarkus Armbruster@findex -audio-help 431f0b3d811SKővágó, ZoltánWill show the -audiodev equivalent of the currently specified 432f0b3d811SKővágó, Zoltán(deprecated) environment variables. 433f0b3d811SKővágó, ZoltánETEXI 434f0b3d811SKővágó, Zoltán 435f0b3d811SKővágó, ZoltánDEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev, 436f0b3d811SKővágó, Zoltán "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n" 437f0b3d811SKővágó, Zoltán " specifies the audio backend to use\n" 438f0b3d811SKővágó, Zoltán " id= identifier of the backend\n" 439f0b3d811SKővágó, Zoltán " timer-period= timer period in microseconds\n" 4408efac073SKővágó, Zoltán " in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n" 441f0b3d811SKővágó, Zoltán " in|out.fixed-settings= use fixed settings for host audio\n" 442f0b3d811SKővágó, Zoltán " in|out.frequency= frequency to use with fixed settings\n" 443f0b3d811SKővágó, Zoltán " in|out.channels= number of channels to use with fixed settings\n" 444f0b3d811SKővágó, Zoltán " in|out.format= sample format to use with fixed settings\n" 445f0b3d811SKővágó, Zoltán " valid values: s8, s16, s32, u8, u16, u32\n" 446f0b3d811SKővágó, Zoltán " in|out.voices= number of voices to use\n" 4478624725bSStefan Hajnoczi " in|out.buffer-length= length of buffer in microseconds\n" 448f0b3d811SKővágó, Zoltán "-audiodev none,id=id,[,prop[=value][,...]]\n" 449f0b3d811SKővágó, Zoltán " dummy driver that discards all output\n" 450f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_ALSA 451f0b3d811SKővágó, Zoltán "-audiodev alsa,id=id[,prop[=value][,...]]\n" 452f0b3d811SKővágó, Zoltán " in|out.dev= name of the audio device to use\n" 453dfc54343SStefan Hajnoczi " in|out.period-length= length of period in microseconds\n" 454f0b3d811SKővágó, Zoltán " in|out.try-poll= attempt to use poll mode\n" 455f0b3d811SKővágó, Zoltán " threshold= threshold (in microseconds) when playback starts\n" 456f0b3d811SKővágó, Zoltán#endif 457f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_COREAUDIO 458f0b3d811SKővágó, Zoltán "-audiodev coreaudio,id=id[,prop[=value][,...]]\n" 459f0b3d811SKővágó, Zoltán " in|out.buffer-count= number of buffers\n" 460f0b3d811SKővágó, Zoltán#endif 461f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_DSOUND 462f0b3d811SKővágó, Zoltán "-audiodev dsound,id=id[,prop[=value][,...]]\n" 463f0b3d811SKővágó, Zoltán " latency= add extra latency to playback in microseconds\n" 464f0b3d811SKővágó, Zoltán#endif 465f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_OSS 466f0b3d811SKővágó, Zoltán "-audiodev oss,id=id[,prop[=value][,...]]\n" 467f0b3d811SKővágó, Zoltán " in|out.dev= path of the audio device to use\n" 468f0b3d811SKővágó, Zoltán " in|out.buffer-count= number of buffers\n" 469f0b3d811SKővágó, Zoltán " in|out.try-poll= attempt to use poll mode\n" 470f0b3d811SKővágó, Zoltán " try-mmap= try using memory mapped access\n" 471f0b3d811SKővágó, Zoltán " exclusive= open device in exclusive mode\n" 472f0b3d811SKővágó, Zoltán " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n" 473f0b3d811SKővágó, Zoltán#endif 474f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_PA 475f0b3d811SKővágó, Zoltán "-audiodev pa,id=id[,prop[=value][,...]]\n" 476f0b3d811SKővágó, Zoltán " server= PulseAudio server address\n" 477f0b3d811SKővágó, Zoltán " in|out.name= source/sink device name\n" 47814d4f011SStefan Hajnoczi " in|out.latency= desired latency in microseconds\n" 479f0b3d811SKővágó, Zoltán#endif 480f0b3d811SKővágó, Zoltán#ifdef CONFIG_AUDIO_SDL 481f0b3d811SKővágó, Zoltán "-audiodev sdl,id=id[,prop[=value][,...]]\n" 482f0b3d811SKővágó, Zoltán#endif 483f0b3d811SKővágó, Zoltán#ifdef CONFIG_SPICE 484f0b3d811SKővágó, Zoltán "-audiodev spice,id=id[,prop[=value][,...]]\n" 485f0b3d811SKővágó, Zoltán#endif 486f0b3d811SKővágó, Zoltán "-audiodev wav,id=id[,prop[=value][,...]]\n" 487f0b3d811SKővágó, Zoltán " path= path of wav file to record\n", 488f0b3d811SKővágó, Zoltán QEMU_ARCH_ALL) 489f0b3d811SKővágó, ZoltánSTEXI 490f0b3d811SKővágó, Zoltán@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]] 491f0b3d811SKővágó, Zoltán@findex -audiodev 492f0b3d811SKővágó, ZoltánAdds a new audio backend @var{driver} identified by @var{id}. There are 493f0b3d811SKővágó, Zoltánglobal and driver specific properties. Some values can be set 494f0b3d811SKővágó, Zoltándifferently for input and output, they're marked with @code{in|out.}. 495f0b3d811SKővágó, ZoltánYou can set the input's property with @code{in.@var{prop}} and the 496f0b3d811SKővágó, Zoltánoutput's property with @code{out.@var{prop}}. For example: 497f0b3d811SKővágó, Zoltán@example 498f0b3d811SKővágó, Zoltán-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 499f0b3d811SKővágó, Zoltán-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified 500f0b3d811SKővágó, Zoltán@end example 501f0b3d811SKővágó, Zoltán 5028efac073SKővágó, ZoltánNOTE: parameter validation is known to be incomplete, in many cases 5038efac073SKővágó, Zoltánspecifying an invalid option causes QEMU to print an error message and 5048efac073SKővágó, Zoltáncontinue emulation without sound. 5058efac073SKővágó, Zoltán 506f0b3d811SKővágó, ZoltánValid global options are: 507f0b3d811SKővágó, Zoltán 508f0b3d811SKővágó, Zoltán@table @option 509f0b3d811SKővágó, Zoltán@item id=@var{identifier} 510f0b3d811SKővágó, ZoltánIdentifies the audio backend. 511f0b3d811SKővágó, Zoltán 512f0b3d811SKővágó, Zoltán@item timer-period=@var{period} 513f0b3d811SKővágó, ZoltánSets the timer @var{period} used by the audio subsystem in microseconds. 514f0b3d811SKővágó, ZoltánDefault is 10000 (10 ms). 515f0b3d811SKővágó, Zoltán 5168efac073SKővágó, Zoltán@item in|out.mixing-engine=on|off 5178efac073SKővágó, ZoltánUse QEMU's mixing engine to mix all streams inside QEMU and convert 5188efac073SKővágó, Zoltánaudio formats when not supported by the backend. When off, 5198efac073SKővágó, Zoltán@var{fixed-settings} must be off too. Note that disabling this option 5208efac073SKővágó, Zoltánmeans that the selected backend must support multiple streams and the 5218efac073SKővágó, Zoltánaudio formats used by the virtual cards, otherwise you'll get no sound. 5228efac073SKővágó, ZoltánIt's not recommended to disable this option unless you want to use 5.1 5238efac073SKővágó, Zoltánor 7.1 audio, as mixing engine only supports mono and stereo audio. 5248efac073SKővágó, ZoltánDefault is on. 5258efac073SKővágó, Zoltán 526f0b3d811SKővágó, Zoltán@item in|out.fixed-settings=on|off 527f0b3d811SKővágó, ZoltánUse fixed settings for host audio. When off, it will change based on 528f0b3d811SKővágó, Zoltánhow the guest opens the sound card. In this case you must not specify 529f0b3d811SKővágó, Zoltán@var{frequency}, @var{channels} or @var{format}. Default is on. 530f0b3d811SKővágó, Zoltán 531f0b3d811SKővágó, Zoltán@item in|out.frequency=@var{frequency} 532f0b3d811SKővágó, ZoltánSpecify the @var{frequency} to use when using @var{fixed-settings}. 533f0b3d811SKővágó, ZoltánDefault is 44100Hz. 534f0b3d811SKővágó, Zoltán 535f0b3d811SKővágó, Zoltán@item in|out.channels=@var{channels} 536f0b3d811SKővágó, ZoltánSpecify the number of @var{channels} to use when using 537f0b3d811SKővágó, Zoltán@var{fixed-settings}. Default is 2 (stereo). 538f0b3d811SKővágó, Zoltán 539f0b3d811SKővágó, Zoltán@item in|out.format=@var{format} 540f0b3d811SKővágó, ZoltánSpecify the sample @var{format} to use when using @var{fixed-settings}. 541f0b3d811SKővágó, ZoltánValid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8}, 542f0b3d811SKővágó, Zoltán@code{u16}, @code{u32}. Default is @code{s16}. 543f0b3d811SKővágó, Zoltán 544f0b3d811SKővágó, Zoltán@item in|out.voices=@var{voices} 545f0b3d811SKővágó, ZoltánSpecify the number of @var{voices} to use. Default is 1. 546f0b3d811SKővágó, Zoltán 5478624725bSStefan Hajnoczi@item in|out.buffer-length=@var{usecs} 548f0b3d811SKővágó, ZoltánSets the size of the buffer in microseconds. 549f0b3d811SKővágó, Zoltán 550f0b3d811SKővágó, Zoltán@end table 551f0b3d811SKővágó, Zoltán 552f0b3d811SKővágó, Zoltán@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]] 553f0b3d811SKővágó, ZoltánCreates a dummy backend that discards all outputs. This backend has no 554f0b3d811SKővágó, Zoltánbackend specific properties. 555f0b3d811SKővágó, Zoltán 556f0b3d811SKővágó, Zoltán@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 557f0b3d811SKővágó, ZoltánCreates backend using the ALSA. This backend is only available on 558f0b3d811SKővágó, ZoltánLinux. 559f0b3d811SKővágó, Zoltán 560f0b3d811SKővágó, ZoltánALSA specific options are: 561f0b3d811SKővágó, Zoltán 562f0b3d811SKővágó, Zoltán@table @option 563f0b3d811SKővágó, Zoltán 564f0b3d811SKővágó, Zoltán@item in|out.dev=@var{device} 565f0b3d811SKővágó, ZoltánSpecify the ALSA @var{device} to use for input and/or output. Default 566f0b3d811SKővágó, Zoltánis @code{default}. 567f0b3d811SKővágó, Zoltán 568dfc54343SStefan Hajnoczi@item in|out.period-length=@var{usecs} 569f0b3d811SKővágó, ZoltánSets the period length in microseconds. 570f0b3d811SKővágó, Zoltán 571f0b3d811SKővágó, Zoltán@item in|out.try-poll=on|off 572f0b3d811SKővágó, ZoltánAttempt to use poll mode with the device. Default is on. 573f0b3d811SKővágó, Zoltán 574f0b3d811SKővágó, Zoltán@item threshold=@var{threshold} 575f0b3d811SKővágó, ZoltánThreshold (in microseconds) when playback starts. Default is 0. 576f0b3d811SKővágó, Zoltán 577f0b3d811SKővágó, Zoltán@end table 578f0b3d811SKővágó, Zoltán 579f0b3d811SKővágó, Zoltán@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]] 580f0b3d811SKővágó, ZoltánCreates a backend using Apple's Core Audio. This backend is only 581f0b3d811SKővágó, Zoltánavailable on Mac OS and only supports playback. 582f0b3d811SKővágó, Zoltán 583f0b3d811SKővágó, ZoltánCore Audio specific options are: 584f0b3d811SKővágó, Zoltán 585f0b3d811SKővágó, Zoltán@table @option 586f0b3d811SKővágó, Zoltán 587f0b3d811SKővágó, Zoltán@item in|out.buffer-count=@var{count} 588f0b3d811SKővágó, ZoltánSets the @var{count} of the buffers. 589f0b3d811SKővágó, Zoltán 590f0b3d811SKővágó, Zoltán@end table 591f0b3d811SKővágó, Zoltán 592f0b3d811SKővágó, Zoltán@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]] 593f0b3d811SKővágó, ZoltánCreates a backend using Microsoft's DirectSound. This backend is only 594f0b3d811SKővágó, Zoltánavailable on Windows and only supports playback. 595f0b3d811SKővágó, Zoltán 596f0b3d811SKővágó, ZoltánDirectSound specific options are: 597f0b3d811SKővágó, Zoltán 598f0b3d811SKővágó, Zoltán@table @option 599f0b3d811SKővágó, Zoltán 600f0b3d811SKővágó, Zoltán@item latency=@var{usecs} 601f0b3d811SKővágó, ZoltánAdd extra @var{usecs} microseconds latency to playback. Default is 602f0b3d811SKővágó, Zoltán10000 (10 ms). 603f0b3d811SKővágó, Zoltán 604f0b3d811SKővágó, Zoltán@end table 605f0b3d811SKővágó, Zoltán 606f0b3d811SKővágó, Zoltán@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]] 607f0b3d811SKővágó, ZoltánCreates a backend using OSS. This backend is available on most 608f0b3d811SKővágó, ZoltánUnix-like systems. 609f0b3d811SKővágó, Zoltán 610f0b3d811SKővágó, ZoltánOSS specific options are: 611f0b3d811SKővágó, Zoltán 612f0b3d811SKővágó, Zoltán@table @option 613f0b3d811SKővágó, Zoltán 614f0b3d811SKővágó, Zoltán@item in|out.dev=@var{device} 615f0b3d811SKővágó, ZoltánSpecify the file name of the OSS @var{device} to use. Default is 616f0b3d811SKővágó, Zoltán@code{/dev/dsp}. 617f0b3d811SKővágó, Zoltán 618f0b3d811SKővágó, Zoltán@item in|out.buffer-count=@var{count} 619f0b3d811SKővágó, ZoltánSets the @var{count} of the buffers. 620f0b3d811SKővágó, Zoltán 621f0b3d811SKővágó, Zoltán@item in|out.try-poll=on|of 622f0b3d811SKővágó, ZoltánAttempt to use poll mode with the device. Default is on. 623f0b3d811SKővágó, Zoltán 624f0b3d811SKővágó, Zoltán@item try-mmap=on|off 625f0b3d811SKővágó, ZoltánTry using memory mapped device access. Default is off. 626f0b3d811SKővágó, Zoltán 627f0b3d811SKővágó, Zoltán@item exclusive=on|off 628f0b3d811SKővágó, ZoltánOpen the device in exclusive mode (vmix won't work in this case). 629f0b3d811SKővágó, ZoltánDefault is off. 630f0b3d811SKővágó, Zoltán 631f0b3d811SKővágó, Zoltán@item dsp-policy=@var{policy} 632f0b3d811SKővágó, ZoltánSets the timing policy (between 0 and 10, where smaller number means 633f0b3d811SKővágó, Zoltánsmaller latency but higher CPU usage). Use -1 to use buffer sizes 634f0b3d811SKővágó, Zoltánspecified by @code{buffer} and @code{buffer-count}. This option is 635f0b3d811SKővágó, Zoltánignored if you do not have OSS 4. Default is 5. 636f0b3d811SKővágó, Zoltán 637f0b3d811SKővágó, Zoltán@end table 638f0b3d811SKővágó, Zoltán 639f0b3d811SKővágó, Zoltán@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 640f0b3d811SKővágó, ZoltánCreates a backend using PulseAudio. This backend is available on most 641f0b3d811SKővágó, Zoltánsystems. 642f0b3d811SKővágó, Zoltán 643f0b3d811SKővágó, ZoltánPulseAudio specific options are: 644f0b3d811SKővágó, Zoltán 645f0b3d811SKővágó, Zoltán@table @option 646f0b3d811SKővágó, Zoltán 647f0b3d811SKővágó, Zoltán@item server=@var{server} 648f0b3d811SKővágó, ZoltánSets the PulseAudio @var{server} to connect to. 649f0b3d811SKővágó, Zoltán 650f0b3d811SKővágó, Zoltán@item in|out.name=@var{sink} 651f0b3d811SKővágó, ZoltánUse the specified source/sink for recording/playback. 652f0b3d811SKővágó, Zoltán 65314d4f011SStefan Hajnoczi@item in|out.latency=@var{usecs} 65414d4f011SStefan HajnocziDesired latency in microseconds. The PulseAudio server will try to honor this 65514d4f011SStefan Hajnoczivalue but actual latencies may be lower or higher. 65614d4f011SStefan Hajnoczi 657f0b3d811SKővágó, Zoltán@end table 658f0b3d811SKővágó, Zoltán 659f0b3d811SKővágó, Zoltán@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]] 660f0b3d811SKővágó, ZoltánCreates a backend using SDL. This backend is available on most systems, 661f0b3d811SKővágó, Zoltánbut you should use your platform's native backend if possible. This 662f0b3d811SKővágó, Zoltánbackend has no backend specific properties. 663f0b3d811SKővágó, Zoltán 664f0b3d811SKővágó, Zoltán@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]] 665f0b3d811SKővágó, ZoltánCreates a backend that sends audio through SPICE. This backend requires 666f0b3d811SKővágó, Zoltán@code{-spice} and automatically selected in that case, so usually you 667f0b3d811SKővágó, Zoltáncan ignore this option. This backend has no backend specific 668f0b3d811SKővágó, Zoltánproperties. 669f0b3d811SKővágó, Zoltán 670f0b3d811SKővágó, Zoltán@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]] 671f0b3d811SKővágó, ZoltánCreates a backend that writes audio to a WAV file. 672f0b3d811SKővágó, Zoltán 673f0b3d811SKővágó, ZoltánBackend specific options are: 674f0b3d811SKővágó, Zoltán 675f0b3d811SKővágó, Zoltán@table @option 676f0b3d811SKővágó, Zoltán 677f0b3d811SKővágó, Zoltán@item path=@var{path} 678f0b3d811SKővágó, ZoltánWrite recorded audio into the specified file. Default is 679f0b3d811SKővágó, Zoltán@code{qemu.wav}. 680f0b3d811SKővágó, Zoltán 681f0b3d811SKővágó, Zoltán@end table 68210adb8beSMarkus ArmbrusterETEXI 68310adb8beSMarkus Armbruster 68410adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 68510adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 68610adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 68710adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 68810adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 68910adb8beSMarkus ArmbrusterSTEXI 69010adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 69110adb8beSMarkus Armbruster@findex -soundhw 69210adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 693664785acSThomas Huthavailable sound hardware. For example: 69410adb8beSMarkus Armbruster 69510adb8beSMarkus Armbruster@example 696664785acSThomas Huth@value{qemu_system_x86} -soundhw sb16,adlib disk.img 697664785acSThomas Huth@value{qemu_system_x86} -soundhw es1370 disk.img 698664785acSThomas Huth@value{qemu_system_x86} -soundhw ac97 disk.img 699664785acSThomas Huth@value{qemu_system_x86} -soundhw hda disk.img 700664785acSThomas Huth@value{qemu_system_x86} -soundhw all disk.img 701664785acSThomas Huth@value{qemu_system_x86} -soundhw help 70210adb8beSMarkus Armbruster@end example 70310adb8beSMarkus Armbruster 70410adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 70510adb8beSMarkus Armbrusterrequire manually specifying clocking. 70610adb8beSMarkus Armbruster 70710adb8beSMarkus Armbruster@example 70810adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 70910adb8beSMarkus Armbruster@end example 71010adb8beSMarkus ArmbrusterETEXI 71110adb8beSMarkus Armbruster 71210adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 71310adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 71410adb8beSMarkus Armbruster " add device (based on driver)\n" 71510adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 71610adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 71710adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 71810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 71910adb8beSMarkus ArmbrusterSTEXI 72010adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 72110adb8beSMarkus Armbruster@findex -device 72210adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 72310adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 72410adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 72510adb8beSMarkus Armbruster@code{-device @var{driver},help}. 726f8490451SCorey Minyard 727f8490451SCorey MinyardSome drivers are: 7287b0cd78bSCorey Minyard@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}] 729f8490451SCorey Minyard 730f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 731f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 732f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 733f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 734f8490451SCorey Minyard 735f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 736f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 737f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 738f8490451SCorey Minyardit. 739f8490451SCorey Minyard 7408c6fd7f3SCédric Le Goater@table @option 7417b0cd78bSCorey Minyard@item id=@var{id} 7427b0cd78bSCorey MinyardThe BMC id for interfaces to use this device. 7438c6fd7f3SCédric Le Goater@item slave_addr=@var{val} 7448c6fd7f3SCédric Le GoaterDefine slave address to use for the BMC. The default is 0x20. 7458c6fd7f3SCédric Le Goater@item sdrfile=@var{file} 7468c6fd7f3SCédric Le Goaterfile containing raw Sensor Data Records (SDR) data. The default is none. 747540c07d3SCédric Le Goater@item fruareasize=@var{val} 748540c07d3SCédric Le Goatersize of a Field Replaceable Unit (FRU) area. The default is 1024. 749540c07d3SCédric Le Goater@item frudatafile=@var{file} 750540c07d3SCédric Le Goaterfile containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 7517b0cd78bSCorey Minyard@item guid=@var{uuid} 7527b0cd78bSCorey Minyardvalue for the GUID for the BMC, in standard UUID format. If this is set, 7537b0cd78bSCorey Minyardget "Get GUID" command to the BMC will return it. Otherwise "Get GUID" 7547b0cd78bSCorey Minyardwill return an error. 7558c6fd7f3SCédric Le Goater@end table 7568c6fd7f3SCédric Le Goater 757f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 758f8490451SCorey Minyard 759f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 760f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 761f8490451SCorey Minyardto an external entity that provides the IPMI services. 762f8490451SCorey Minyard 763f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 764f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 765f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 766f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 767f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 768f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 769f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 770f8490451SCorey Minyardexposed to any outside network. 771f8490451SCorey Minyard 772f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 773f8490451SCorey Minyarddetails on the external interface. 774f8490451SCorey Minyard 775f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 776f8490451SCorey Minyard 777f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 778f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 779f8490451SCorey Minyard 780f8490451SCorey Minyard@table @option 781f8490451SCorey Minyard@item bmc=@var{id} 782f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 783f8490451SCorey Minyard@item ioport=@var{val} 784f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 785f8490451SCorey Minyard@item irq=@var{val} 786f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 787f8490451SCorey Minyardset this to 0. 788f8490451SCorey Minyard@end table 789f8490451SCorey Minyard 790f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 791f8490451SCorey Minyard 792f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 793f8490451SCorey Minyard0xe4 and the default interrupt is 5. 794f8490451SCorey Minyard 79510adb8beSMarkus ArmbrusterETEXI 79610adb8beSMarkus Armbruster 79710adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 7988f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 79910adb8beSMarkus Armbruster " set the name of the guest\n" 800479a5747SRoman Bolshakov " string1 sets the window title and string2 the process name\n" 801479a5747SRoman Bolshakov " When debug-threads is enabled, individual threads are given a separate name\n" 8028f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 80310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 80410adb8beSMarkus ArmbrusterSTEXI 80510adb8beSMarkus Armbruster@item -name @var{name} 80610adb8beSMarkus Armbruster@findex -name 80710adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 80810adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 80910adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 81010adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 8118f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 81210adb8beSMarkus ArmbrusterETEXI 81310adb8beSMarkus Armbruster 81410adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 81510adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 81610adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 81710adb8beSMarkus ArmbrusterSTEXI 81810adb8beSMarkus Armbruster@item -uuid @var{uuid} 81910adb8beSMarkus Armbruster@findex -uuid 82010adb8beSMarkus ArmbrusterSet system UUID. 82110adb8beSMarkus ArmbrusterETEXI 82210adb8beSMarkus Armbruster 82310adb8beSMarkus ArmbrusterSTEXI 82410adb8beSMarkus Armbruster@end table 82510adb8beSMarkus ArmbrusterETEXI 82610adb8beSMarkus ArmbrusterDEFHEADING() 82710adb8beSMarkus Armbruster 828de6b4f90SMarkus ArmbrusterDEFHEADING(Block device options:) 82910adb8beSMarkus ArmbrusterSTEXI 83010adb8beSMarkus Armbruster@table @option 83110adb8beSMarkus ArmbrusterETEXI 83210adb8beSMarkus Armbruster 8335824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 834ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 835ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 8365824d651Sblueswir1STEXI 8375824d651Sblueswir1@item -fda @var{file} 838f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 8396616b2adSStefan Weil@findex -fda 8406616b2adSStefan Weil@findex -fdb 84192a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 8425824d651Sblueswir1ETEXI 8435824d651Sblueswir1 8445824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 845ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 846ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 8475824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 848ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 849ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 8505824d651Sblueswir1STEXI 8515824d651Sblueswir1@item -hda @var{file} 852f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 853f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 854f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 8556616b2adSStefan Weil@findex -hda 8566616b2adSStefan Weil@findex -hdb 8576616b2adSStefan Weil@findex -hdc 8586616b2adSStefan Weil@findex -hdd 8595824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 8605824d651Sblueswir1ETEXI 8615824d651Sblueswir1 8625824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 863ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 864ad96090aSBlue Swirl QEMU_ARCH_ALL) 8655824d651Sblueswir1STEXI 8665824d651Sblueswir1@item -cdrom @var{file} 8676616b2adSStefan Weil@findex -cdrom 8685824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 8695824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 8705824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 8715824d651Sblueswir1ETEXI 8725824d651Sblueswir1 87342e5f393SMarkus ArmbrusterDEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 87442e5f393SMarkus Armbruster "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 87542e5f393SMarkus Armbruster " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 876c9b749d7SKevin Wolf " [,read-only=on|off][,auto-read-only=on|off]\n" 877c9b749d7SKevin Wolf " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n" 87842e5f393SMarkus Armbruster " [,driver specific parameters...]\n" 87942e5f393SMarkus Armbruster " configure a block backend\n", QEMU_ARCH_ALL) 880dfaca464SKevin WolfSTEXI 881dfaca464SKevin Wolf@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 882dfaca464SKevin Wolf@findex -blockdev 883dfaca464SKevin Wolf 884370e8328SKevin WolfDefine a new block driver node. Some of the options apply to all block drivers, 885370e8328SKevin Wolfother options are only accepted for a specific block driver. See below for a 886370e8328SKevin Wolflist of generic options and options for the most common block drivers. 887370e8328SKevin Wolf 888370e8328SKevin WolfOptions that expect a reference to another node (e.g. @code{file}) can be 889370e8328SKevin Wolfgiven in two ways. Either you specify the node name of an already existing node 890370e8328SKevin Wolf(file=@var{node-name}), or you define a new node inline, adding options 891370e8328SKevin Wolffor the referenced node after a dot (file.filename=@var{path},file.aio=native). 892370e8328SKevin Wolf 893370e8328SKevin WolfA block driver node created with @option{-blockdev} can be used for a guest 894370e8328SKevin Wolfdevice by specifying its node name for the @code{drive} property in a 895370e8328SKevin Wolf@option{-device} argument that defines a block device. 896dfaca464SKevin Wolf 897dfaca464SKevin Wolf@table @option 898dfaca464SKevin Wolf@item Valid options for any block driver node: 899dfaca464SKevin Wolf 900dfaca464SKevin Wolf@table @code 901dfaca464SKevin Wolf@item driver 902dfaca464SKevin WolfSpecifies the block driver to use for the given node. 903dfaca464SKevin Wolf@item node-name 904dfaca464SKevin WolfThis defines the name of the block driver node by which it will be referenced 905dfaca464SKevin Wolflater. The name must be unique, i.e. it must not match the name of a different 906dfaca464SKevin Wolfblock driver node, or (if you use @option{-drive} as well) the ID of a drive. 907dfaca464SKevin Wolf 908dfaca464SKevin WolfIf no node name is specified, it is automatically generated. The generated node 909dfaca464SKevin Wolfname is not intended to be predictable and changes between QEMU invocations. 910dfaca464SKevin WolfFor the top level, an explicit node name must be specified. 911dfaca464SKevin Wolf@item read-only 912dfaca464SKevin WolfOpen the node read-only. Guest write attempts will fail. 913c9b749d7SKevin Wolf 914c9b749d7SKevin WolfNote that some block drivers support only read-only access, either generally or 915c9b749d7SKevin Wolfin certain configurations. In this case, the default value 916c9b749d7SKevin Wolf@option{read-only=off} does not work and the option must be specified 917c9b749d7SKevin Wolfexplicitly. 918c9b749d7SKevin Wolf@item auto-read-only 919c9b749d7SKevin WolfIf @option{auto-read-only=on} is set, QEMU may fall back to read-only usage 920c9b749d7SKevin Wolfeven when @option{read-only=off} is requested, or even switch between modes as 921c9b749d7SKevin Wolfneeded, e.g. depending on whether the image file is writable or whether a 922c9b749d7SKevin Wolfwriting user is attached to the node. 923c9b749d7SKevin Wolf@item force-share 924c9b749d7SKevin WolfOverride the image locking system of QEMU by forcing the node to utilize 925c9b749d7SKevin Wolfweaker shared access for permissions where it would normally request exclusive 926c9b749d7SKevin Wolfaccess. When there is the potential for multiple instances to have the same 927c9b749d7SKevin Wolffile open (whether this invocation of QEMU is the first or the second 928c9b749d7SKevin Wolfinstance), both instances must permit shared access for the second instance to 929c9b749d7SKevin Wolfsucceed at opening the file. 930c9b749d7SKevin Wolf 931c9b749d7SKevin WolfEnabling @option{force-share=on} requires @option{read-only=on}. 932dfaca464SKevin Wolf@item cache.direct 933dfaca464SKevin WolfThe host page cache can be avoided with @option{cache.direct=on}. This will 934dfaca464SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform an 935dfaca464SKevin Wolfinternal copy of the data. 936dfaca464SKevin Wolf@item cache.no-flush 937dfaca464SKevin WolfIn case you don't care about data integrity over host failures, you can use 938dfaca464SKevin Wolf@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 939dfaca464SKevin Wolfany data to the disk but can instead keep things in cache. If anything goes 940dfaca464SKevin Wolfwrong, like your host losing power, the disk storage getting disconnected 941dfaca464SKevin Wolfaccidentally, etc. your image will most probably be rendered unusable. 942dfaca464SKevin Wolf@item discard=@var{discard} 943dfaca464SKevin Wolf@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 944dfaca464SKevin Wolfwhether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 945dfaca464SKevin Wolfignored or passed to the filesystem. Some machine types may not support 946dfaca464SKevin Wolfdiscard requests. 947dfaca464SKevin Wolf@item detect-zeroes=@var{detect-zeroes} 948dfaca464SKevin Wolf@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 949dfaca464SKevin Wolfconversion of plain zero writes by the OS to driver specific optimized 950dfaca464SKevin Wolfzero write commands. You may even choose "unmap" if @var{discard} is set 951dfaca464SKevin Wolfto "unmap" to allow a zero write to be converted to an @code{unmap} operation. 952dfaca464SKevin Wolf@end table 953dfaca464SKevin Wolf 954370e8328SKevin Wolf@item Driver-specific options for @code{file} 955370e8328SKevin Wolf 956370e8328SKevin WolfThis is the protocol-level block driver for accessing regular files. 957370e8328SKevin Wolf 958370e8328SKevin Wolf@table @code 959370e8328SKevin Wolf@item filename 960370e8328SKevin WolfThe path to the image file in the local filesystem 961370e8328SKevin Wolf@item aio 962370e8328SKevin WolfSpecifies the AIO backend (threads/native, default: threads) 9631878eaffSFam Zheng@item locking 9641878eaffSFam ZhengSpecifies whether the image file is protected with Linux OFD / POSIX locks. The 9651878eaffSFam Zhengdefault is to use the Linux Open File Descriptor API if available, otherwise no 9661878eaffSFam Zhenglock is applied. (auto/on/off, default: auto) 967370e8328SKevin Wolf@end table 968370e8328SKevin WolfExample: 969370e8328SKevin Wolf@example 970370e8328SKevin Wolf-blockdev driver=file,node-name=disk,filename=disk.img 971370e8328SKevin Wolf@end example 972370e8328SKevin Wolf 973370e8328SKevin Wolf@item Driver-specific options for @code{raw} 974370e8328SKevin Wolf 975370e8328SKevin WolfThis is the image format block driver for raw images. It is usually 976370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 977370e8328SKevin Wolf 978370e8328SKevin Wolf@table @code 979370e8328SKevin Wolf@item file 980370e8328SKevin WolfReference to or definition of the data source block driver node 981370e8328SKevin Wolf(e.g. a @code{file} driver node) 982370e8328SKevin Wolf@end table 983370e8328SKevin WolfExample 1: 984370e8328SKevin Wolf@example 985370e8328SKevin Wolf-blockdev driver=file,node-name=disk_file,filename=disk.img 986370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file=disk_file 987370e8328SKevin Wolf@end example 988370e8328SKevin WolfExample 2: 989370e8328SKevin Wolf@example 990370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 991370e8328SKevin Wolf@end example 992370e8328SKevin Wolf 993370e8328SKevin Wolf@item Driver-specific options for @code{qcow2} 994370e8328SKevin Wolf 995370e8328SKevin WolfThis is the image format block driver for qcow2 images. It is usually 996370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 997370e8328SKevin Wolf 998370e8328SKevin Wolf@table @code 999370e8328SKevin Wolf@item file 1000370e8328SKevin WolfReference to or definition of the data source block driver node 1001370e8328SKevin Wolf(e.g. a @code{file} driver node) 1002370e8328SKevin Wolf 1003370e8328SKevin Wolf@item backing 1004370e8328SKevin WolfReference to or definition of the backing file block device (default is taken 10054f7be280SMax Reitzfrom the image file). It is allowed to pass @code{null} here in order to disable 10064f7be280SMax Reitzthe default backing file. 1007370e8328SKevin Wolf 1008370e8328SKevin Wolf@item lazy-refcounts 1009370e8328SKevin WolfWhether to enable the lazy refcounts feature (on/off; default is taken from the 1010370e8328SKevin Wolfimage file) 1011370e8328SKevin Wolf 1012370e8328SKevin Wolf@item cache-size 1013370e8328SKevin WolfThe maximum total size of the L2 table and refcount block caches in bytes 101440fb215dSLeonid Bloch(default: the sum of l2-cache-size and refcount-cache-size) 1015370e8328SKevin Wolf 1016370e8328SKevin Wolf@item l2-cache-size 1017370e8328SKevin WolfThe maximum size of the L2 table cache in bytes 101880668d0fSLeonid Bloch(default: if cache-size is not specified - 32M on Linux platforms, and 8M on 101980668d0fSLeonid Blochnon-Linux platforms; otherwise, as large as possible within the cache-size, 102080668d0fSLeonid Blochwhile permitting the requested or the minimal refcount cache size) 1021370e8328SKevin Wolf 1022370e8328SKevin Wolf@item refcount-cache-size 1023370e8328SKevin WolfThe maximum size of the refcount block cache in bytes 102440fb215dSLeonid Bloch(default: 4 times the cluster size; or if cache-size is specified, the part of 102540fb215dSLeonid Blochit which is not used for the L2 cache) 1026370e8328SKevin Wolf 1027370e8328SKevin Wolf@item cache-clean-interval 1028370e8328SKevin WolfClean unused entries in the L2 and refcount caches. The interval is in seconds. 1029e3a7b455SLeonid BlochThe default value is 600 on supporting platforms, and 0 on other platforms. 1030e3a7b455SLeonid BlochSetting it to 0 disables this feature. 1031370e8328SKevin Wolf 1032370e8328SKevin Wolf@item pass-discard-request 1033370e8328SKevin WolfWhether discard requests to the qcow2 device should be forwarded to the data 1034370e8328SKevin Wolfsource (on/off; default: on if discard=unmap is specified, off otherwise) 1035370e8328SKevin Wolf 1036370e8328SKevin Wolf@item pass-discard-snapshot 1037370e8328SKevin WolfWhether discard requests for the data source should be issued when a snapshot 1038370e8328SKevin Wolfoperation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 1039370e8328SKevin Wolfdefault: on) 1040370e8328SKevin Wolf 1041370e8328SKevin Wolf@item pass-discard-other 1042370e8328SKevin WolfWhether discard requests for the data source should be issued on other 1043370e8328SKevin Wolfoccasions where a cluster gets freed (on/off; default: off) 1044370e8328SKevin Wolf 1045370e8328SKevin Wolf@item overlap-check 1046370e8328SKevin WolfWhich overlap checks to perform for writes to the image 1047370e8328SKevin Wolf(none/constant/cached/all; default: cached). For details or finer 1048370e8328SKevin Wolfgranularity control refer to the QAPI documentation of @code{blockdev-add}. 1049370e8328SKevin Wolf@end table 1050370e8328SKevin Wolf 1051370e8328SKevin WolfExample 1: 1052370e8328SKevin Wolf@example 1053370e8328SKevin Wolf-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 1054370e8328SKevin Wolf-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 1055370e8328SKevin Wolf@end example 1056370e8328SKevin WolfExample 2: 1057370e8328SKevin Wolf@example 1058370e8328SKevin Wolf-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 1059370e8328SKevin Wolf@end example 1060370e8328SKevin Wolf 1061370e8328SKevin Wolf@item Driver-specific options for other drivers 1062370e8328SKevin WolfPlease refer to the QAPI documentation of the @code{blockdev-add} QMP command. 1063370e8328SKevin Wolf 1064dfaca464SKevin Wolf@end table 1065dfaca464SKevin Wolf 1066dfaca464SKevin WolfETEXI 106742e5f393SMarkus Armbruster 10685824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 10695824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 107092196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 1071572023f7SKevin Wolf " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 1072d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 1073fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 10742f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 10753e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 10763e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 10773e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 10783e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 10792024c1dfSBenoît Canet " [[,iops_size=is]]\n" 108076f4afb4SAlberto Garcia " [[,group=g]]\n" 1081ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 10825824d651Sblueswir1STEXI 10835824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 10846616b2adSStefan Weil@findex -drive 10855824d651Sblueswir1 1086dfaca464SKevin WolfDefine a new drive. This includes creating a block driver node (the backend) as 1087dfaca464SKevin Wolfwell as a guest device, and is mostly a shortcut for defining the corresponding 1088dfaca464SKevin Wolf@option{-blockdev} and @option{-device} options. 1089dfaca464SKevin Wolf 1090dfaca464SKevin Wolf@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 1091dfaca464SKevin Wolfaddition, it knows the following options: 10925824d651Sblueswir1 1093b3f046c2SKevin Wolf@table @option 10945824d651Sblueswir1@item file=@var{file} 10955824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 10965824d651Sblueswir1this drive. If the filename contains comma, you must double it 10975824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 10980f5314a2SRonnie Sahlberg 10990f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 11000f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 11015824d651Sblueswir1@item if=@var{interface} 11025824d651Sblueswir1This option defines on which type on interface the drive is connected. 1103ed1fcd00SCraig JellickAvailable types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 11045824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 11055824d651Sblueswir1These options define where is connected the drive by defining the bus number and 11065824d651Sblueswir1the unit id. 11075824d651Sblueswir1@item index=@var{index} 11085824d651Sblueswir1This option defines where is connected the drive by using an index in the list 11095824d651Sblueswir1of available connectors of a given interface type. 11105824d651Sblueswir1@item media=@var{media} 11115824d651Sblueswir1This option defines the type of the media: disk or cdrom. 11125824d651Sblueswir1@item snapshot=@var{snapshot} 11139d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 11149d85d557SMichael Tokarev(see @option{-snapshot}). 11155824d651Sblueswir1@item cache=@var{cache} 1116dfaca464SKevin Wolf@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 1117dfaca464SKevin Wolfand controls how the host cache is used to access block data. This is a 1118dfaca464SKevin Wolfshortcut that sets the @option{cache.direct} and @option{cache.no-flush} 1119dfaca464SKevin Wolfoptions (as in @option{-blockdev}), and additionally @option{cache.writeback}, 1120dfaca464SKevin Wolfwhich provides a default for the @option{write-cache} option of block guest 1121dfaca464SKevin Wolfdevices (as in @option{-device}). The modes correspond to the following 1122dfaca464SKevin Wolfsettings: 1123dfaca464SKevin Wolf 1124dfaca464SKevin Wolf@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 1125dfaca464SKevin Wolf@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 1126dfaca464SKevin Wolf@c and the HTML output. 1127dfaca464SKevin Wolf@example 1128dfaca464SKevin Wolf@ │ cache.writeback cache.direct cache.no-flush 1129dfaca464SKevin Wolf─────────────┼───────────────────────────────────────────────── 1130dfaca464SKevin Wolfwriteback │ on off off 1131dfaca464SKevin Wolfnone │ on on off 1132dfaca464SKevin Wolfwritethrough │ off off off 1133dfaca464SKevin Wolfdirectsync │ off on off 1134dfaca464SKevin Wolfunsafe │ on off on 1135dfaca464SKevin Wolf@end example 1136dfaca464SKevin Wolf 1137dfaca464SKevin WolfThe default mode is @option{cache=writeback}. 1138dfaca464SKevin Wolf 11395c6c3a6cSChristoph Hellwig@item aio=@var{aio} 11405c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 11415824d651Sblueswir1@item format=@var{format} 11425824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 1143d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 11445824d651Sblueswir1an untrusted format header. 1145ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 1146ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 1147ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 1148ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 1149ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 1150ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 1151fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 1152fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 1153fb0490f6SStefan Hajnoczifile sectors into the image file. 115401f9cfabSStefan Hajnoczi@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 115501f9cfabSStefan HajnocziSpecify bandwidth throttling limits in bytes per second, either for all request 115601f9cfabSStefan Hajnoczitypes or for reads or writes only. Small values can lead to timeouts or hangs 115701f9cfabSStefan Hajnocziinside the guest. A safe minimum for disks is 2 MB/s. 115801f9cfabSStefan Hajnoczi@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 115901f9cfabSStefan HajnocziSpecify bursts in bytes per second, either for all request types or for reads 116001f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 116101f9cfabSStefan Hajnoczitemporarily. 116201f9cfabSStefan Hajnoczi@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 116301f9cfabSStefan HajnocziSpecify request rate limits in requests per second, either for all request 116401f9cfabSStefan Hajnoczitypes or for reads or writes only. 116501f9cfabSStefan Hajnoczi@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 116601f9cfabSStefan HajnocziSpecify bursts in requests per second, either for all request types or for reads 116701f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 116801f9cfabSStefan Hajnoczitemporarily. 116901f9cfabSStefan Hajnoczi@item iops_size=@var{is} 117001f9cfabSStefan HajnocziLet every @var{is} bytes of a request count as a new request for iops 117101f9cfabSStefan Hajnoczithrottling purposes. Use this option to prevent guests from circumventing iops 117201f9cfabSStefan Hajnoczilimits by sending fewer but larger requests. 117301f9cfabSStefan Hajnoczi@item group=@var{g} 117401f9cfabSStefan HajnocziJoin a throttling quota group with given name @var{g}. All drives that are 117501f9cfabSStefan Hajnoczimembers of the same group are accounted for together. Use this option to 117601f9cfabSStefan Hajnocziprevent guests from circumventing throttling limits by using many small disks 117701f9cfabSStefan Hajnocziinstead of a single larger disk. 11785824d651Sblueswir1@end table 11795824d651Sblueswir1 1180dfaca464SKevin WolfBy default, the @option{cache.writeback=on} mode is used. It will report data 1181a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 1182a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 1183a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 1184a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 1185a13e5e05SKevin Wolfdata corruption. 11865824d651Sblueswir1 1187dfaca464SKevin WolfFor such guests, you should consider using @option{cache.writeback=off}. This 1188a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 1189a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 1190a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 11915824d651Sblueswir1 1192dfaca464SKevin WolfWhen using the @option{-snapshot} option, unsafe caching is always used. 1193016f5cf6SAlexander Graf 1194fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 1195fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 1196fb0490f6SStefan Hajnocziis off. 1197fb0490f6SStefan Hajnoczi 11985824d651Sblueswir1Instead of @option{-cdrom} you can use: 11995824d651Sblueswir1@example 1200664785acSThomas Huth@value{qemu_system} -drive file=file,index=2,media=cdrom 12015824d651Sblueswir1@end example 12025824d651Sblueswir1 12035824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 12045824d651Sblueswir1use: 12055824d651Sblueswir1@example 1206664785acSThomas Huth@value{qemu_system} -drive file=file,index=0,media=disk 1207664785acSThomas Huth@value{qemu_system} -drive file=file,index=1,media=disk 1208664785acSThomas Huth@value{qemu_system} -drive file=file,index=2,media=disk 1209664785acSThomas Huth@value{qemu_system} -drive file=file,index=3,media=disk 12105824d651Sblueswir1@end example 12115824d651Sblueswir1 1212587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 1213587ed6beSCorey Bryant@example 1214664785acSThomas Huth@value{qemu_system} \ 1215664785acSThomas Huth -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 1216664785acSThomas Huth -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 1217587ed6beSCorey Bryant -drive file=/dev/fdset/2,index=0,media=disk 1218587ed6beSCorey Bryant@end example 1219587ed6beSCorey Bryant 12205824d651Sblueswir1You can connect a CDROM to the slave of ide0: 12215824d651Sblueswir1@example 1222664785acSThomas Huth@value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom 12235824d651Sblueswir1@end example 12245824d651Sblueswir1 12255824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 12265824d651Sblueswir1@example 1227664785acSThomas Huth@value{qemu_system_x86} -drive if=ide,index=1,media=cdrom 12285824d651Sblueswir1@end example 12295824d651Sblueswir1 12305824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 12315824d651Sblueswir1@example 1232664785acSThomas Huth@value{qemu_system_x86} -drive file=file,index=0,if=floppy 1233664785acSThomas Huth@value{qemu_system_x86} -drive file=file,index=1,if=floppy 12345824d651Sblueswir1@end example 12355824d651Sblueswir1 12365824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 12375824d651Sblueswir1incremented: 12385824d651Sblueswir1@example 1239664785acSThomas Huth@value{qemu_system_x86} -drive file=a -drive file=b" 12405824d651Sblueswir1@end example 12415824d651Sblueswir1is interpreted like: 12425824d651Sblueswir1@example 1243664785acSThomas Huth@value{qemu_system_x86} -hda a -hdb b 12445824d651Sblueswir1@end example 12455824d651Sblueswir1ETEXI 12465824d651Sblueswir1 12475824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 1248ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 1249ad96090aSBlue Swirl QEMU_ARCH_ALL) 12505824d651Sblueswir1STEXI 12514e257e5eSKevin Wolf@item -mtdblock @var{file} 12526616b2adSStefan Weil@findex -mtdblock 12534e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 12545824d651Sblueswir1ETEXI 12555824d651Sblueswir1 12565824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 1257ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 12585824d651Sblueswir1STEXI 12594e257e5eSKevin Wolf@item -sd @var{file} 12606616b2adSStefan Weil@findex -sd 12614e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 12625824d651Sblueswir1ETEXI 12635824d651Sblueswir1 12645824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 1265ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 12665824d651Sblueswir1STEXI 12674e257e5eSKevin Wolf@item -pflash @var{file} 12686616b2adSStefan Weil@findex -pflash 12694e257e5eSKevin WolfUse @var{file} as a parallel flash image. 12705824d651Sblueswir1ETEXI 12715824d651Sblueswir1 12725824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 1273ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 1274ad96090aSBlue Swirl QEMU_ARCH_ALL) 12755824d651Sblueswir1STEXI 12765824d651Sblueswir1@item -snapshot 12776616b2adSStefan Weil@findex -snapshot 12785824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 12795824d651Sblueswir1the raw disk image you use is not written back. You can however force 12805824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 12815824d651Sblueswir1ETEXI 12825824d651Sblueswir1 128374db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 1284b44a6b09SGreg Kurz "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n" 1285b44a6b09SGreg Kurz " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n" 1286b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1287b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1288b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1289b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1290b44a6b09SGreg Kurz " [[,throttling.iops-size=is]]\n" 1291b44a6b09SGreg Kurz "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n" 1292b44a6b09SGreg Kurz "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n" 1293b44a6b09SGreg Kurz "-fsdev synth,id=id\n", 129474db920cSGautham R Shenoy QEMU_ARCH_ALL) 129574db920cSGautham R Shenoy 129674db920cSGautham R ShenoySTEXI 129774db920cSGautham R Shenoy 1298b44a6b09SGreg Kurz@item -fsdev local,id=@var{id},path=@var{path},security_model=@var{security_model} [,writeout=@var{writeout}][,readonly][,fmode=@var{fmode}][,dmode=@var{dmode}] [,throttling.@var{option}=@var{value}[,throttling.@var{option}=@var{value}[,...]]] 1299b44a6b09SGreg Kurz@itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly] 1300b44a6b09SGreg Kurz@itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly] 1301b44a6b09SGreg Kurz@itemx -fsdev synth,id=@var{id}[,readonly] 130274db920cSGautham R Shenoy@findex -fsdev 13037c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 13047c92a3d2SAneesh Kumar K.V@table @option 1305b44a6b09SGreg Kurz@item local 1306b44a6b09SGreg KurzAccesses to the filesystem are done by QEMU. 1307b44a6b09SGreg Kurz@item proxy 1308b44a6b09SGreg KurzAccesses to the filesystem are done by virtfs-proxy-helper(1). 1309b44a6b09SGreg Kurz@item synth 1310b44a6b09SGreg KurzSynthetic filesystem, only used by QTests. 13117c92a3d2SAneesh Kumar K.V@item id=@var{id} 1312b44a6b09SGreg KurzSpecifies identifier for this device. 13137c92a3d2SAneesh Kumar K.V@item path=@var{path} 13147c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 13157c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 13167c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 13177c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 13182c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 13197c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1320b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 13212c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 13227c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 13232c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 13242c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 13257c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 13267c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1327d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 132893aee84fSGreg Kurzonly for local fsdriver. Other fsdrivers (like proxy) don't take 1329d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 13307c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 13317c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 13327c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 13337c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 13347c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 13352c74c2cbSM. Mohan Kumar@item readonly 13362c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 13372c74c2cbSM. Mohan Kumarread-write access is given. 133884a87cc4SM. Mohan Kumar@item socket=@var{socket} 133984a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 1340b44a6b09SGreg Kurzwith virtfs-proxy-helper(1). 1341f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 1342f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 1343b44a6b09SGreg Kurzcommunicating with virtfs-proxy-helper(1). Usually a helper like libvirt 1344b44a6b09SGreg Kurzwill create socketpair and pass one of the fds as sock_fd. 1345b96feb2cSTobias Schramm@item fmode=@var{fmode} 1346b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1347b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1348b96feb2cSTobias Schramm@item dmode=@var{dmode} 1349b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1350b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 1351b44a6b09SGreg Kurz@item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w} 1352b44a6b09SGreg KurzSpecify bandwidth throttling limits in bytes per second, either for all request 1353b44a6b09SGreg Kurztypes or for reads or writes only. 1354b44a6b09SGreg Kurz@item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm} 1355b44a6b09SGreg KurzSpecify bursts in bytes per second, either for all request types or for reads 1356b44a6b09SGreg Kurzor writes only. Bursts allow the guest I/O to spike above the limit 1357b44a6b09SGreg Kurztemporarily. 1358b44a6b09SGreg Kurz@item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w} 1359b44a6b09SGreg KurzSpecify request rate limits in requests per second, either for all request 1360b44a6b09SGreg Kurztypes or for reads or writes only. 1361b44a6b09SGreg Kurz@item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm} 1362b44a6b09SGreg KurzSpecify bursts in requests per second, either for all request types or for reads 1363b44a6b09SGreg Kurzor writes only. Bursts allow the guest I/O to spike above the limit temporarily. 1364b44a6b09SGreg Kurz@item throttling.iops-size=@var{is} 1365b44a6b09SGreg KurzLet every @var{is} bytes of a request count as a new request for iops 1366b44a6b09SGreg Kurzthrottling purposes. 136774db920cSGautham R Shenoy@end table 13687c92a3d2SAneesh Kumar K.V 1369b44a6b09SGreg Kurz-fsdev option is used along with -device driver "virtio-9p-...". 1370b44a6b09SGreg Kurz@item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag} 1371b44a6b09SGreg KurzOptions for virtio-9p-... driver are: 13727c92a3d2SAneesh Kumar K.V@table @option 1373b44a6b09SGreg Kurz@item @var{type} 1374b44a6b09SGreg KurzSpecifies the variant to be used. Supported values are "pci", "ccw" or "device", 1375b44a6b09SGreg Kurzdepending on the machine type. 13767c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 1377b44a6b09SGreg KurzSpecifies the id value specified along with -fsdev option. 13787c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 1379b44a6b09SGreg KurzSpecifies the tag name to be used by the guest to mount this export point. 13807c92a3d2SAneesh Kumar K.V@end table 13817c92a3d2SAneesh Kumar K.V 138274db920cSGautham R ShenoyETEXI 138374db920cSGautham R Shenoy 13843d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 1385b44a6b09SGreg Kurz "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n" 13861a6ed33cSAntonios Motakis " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n" 1387b44a6b09SGreg Kurz "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n" 1388b44a6b09SGreg Kurz "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n" 1389b44a6b09SGreg Kurz "-virtfs synth,mount_tag=tag[,id=id][,readonly]\n", 13903d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 13913d54abc7SGautham R Shenoy 13923d54abc7SGautham R ShenoySTEXI 13933d54abc7SGautham R Shenoy 13941a6ed33cSAntonios Motakis@item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}][,multidevs=@var{multidevs}] 1395b44a6b09SGreg Kurz@itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 1396b44a6b09SGreg Kurz@itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 1397b44a6b09SGreg Kurz@itemx -virtfs synth,mount_tag=@var{mount_tag} 13983d54abc7SGautham R Shenoy@findex -virtfs 13993d54abc7SGautham R Shenoy 1400b44a6b09SGreg KurzDefine a new filesystem device and expose it to the guest using a virtio-9p-device. The general form of a Virtual File system pass-through options are: 14017c92a3d2SAneesh Kumar K.V@table @option 1402b44a6b09SGreg Kurz@item local 1403b44a6b09SGreg KurzAccesses to the filesystem are done by QEMU. 1404b44a6b09SGreg Kurz@item proxy 1405b44a6b09SGreg KurzAccesses to the filesystem are done by virtfs-proxy-helper(1). 1406b44a6b09SGreg Kurz@item synth 1407b44a6b09SGreg KurzSynthetic filesystem, only used by QTests. 14087c92a3d2SAneesh Kumar K.V@item id=@var{id} 1409b44a6b09SGreg KurzSpecifies identifier for the filesystem device 14107c92a3d2SAneesh Kumar K.V@item path=@var{path} 14117c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 14127c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 14137c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 14147c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 14152c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 14167c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1417b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 14182c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 14197c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 14202c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 14212c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 14227c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 14237c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1424d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 142593aee84fSGreg Kurzfor local fsdriver. Other fsdrivers (like proxy) don't take security 1426d9b36a6eSM. Mohan Kumarmodel as a parameter. 14277c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 14287c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 14297c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 14307c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 14317c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 14322c74c2cbSM. Mohan Kumar@item readonly 14332c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 14342c74c2cbSM. Mohan Kumarread-write access is given. 143584a87cc4SM. Mohan Kumar@item socket=@var{socket} 143684a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 1437b44a6b09SGreg Kurzcommunicating with virtfs-proxy-helper(1). Usually a helper like libvirt 1438b44a6b09SGreg Kurzwill create socketpair and pass one of the fds as sock_fd. 1439f67e3ffdSM. Mohan Kumar@item sock_fd 1440f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 1441b44a6b09SGreg Kurzdescriptor for interfacing with virtfs-proxy-helper(1). 1442b96feb2cSTobias Schramm@item fmode=@var{fmode} 1443b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1444b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1445b96feb2cSTobias Schramm@item dmode=@var{dmode} 1446b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1447b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 1448b44a6b09SGreg Kurz@item mount_tag=@var{mount_tag} 1449b44a6b09SGreg KurzSpecifies the tag name to be used by the guest to mount this export point. 14501a6ed33cSAntonios Motakis@item multidevs=@var{multidevs} 14511a6ed33cSAntonios MotakisSpecifies how to deal with multiple devices being shared with a 9p export. 14521a6ed33cSAntonios MotakisSupported behaviours are either "remap", "forbid" or "warn". The latter is 14531a6ed33cSAntonios Motakisthe default behaviour on which virtfs 9p expects only one device to be 14541a6ed33cSAntonios Motakisshared with the same export, and if more than one device is shared and 14551a6ed33cSAntonios Motakisaccessed via the same 9p export then only a warning message is logged 14561a6ed33cSAntonios Motakis(once) by qemu on host side. In order to avoid file ID collisions on guest 14571a6ed33cSAntonios Motakisyou should either create a separate virtfs export for each device to be 14581a6ed33cSAntonios Motakisshared with guests (recommended way) or you might use "remap" instead which 14591a6ed33cSAntonios Motakisallows you to share multiple devices with only one export instead, which is 14601a6ed33cSAntonios Motakisachieved by remapping the original inode numbers from host to guest in a 14611a6ed33cSAntonios Motakisway that would prevent such collisions. Remapping inodes in such use cases 14621a6ed33cSAntonios Motakisis required because the original device IDs from host are never passed and 14631a6ed33cSAntonios Motakisexposed on guest. Instead all files of an export shared with virtfs always 14641a6ed33cSAntonios Motakisshare the same device id on guest. So two files with identical inode 14651a6ed33cSAntonios Motakisnumbers but from actually different devices on host would otherwise cause a 14661a6ed33cSAntonios Motakisfile ID collision and hence potential misbehaviours on guest. "forbid" on 14671a6ed33cSAntonios Motakisthe other hand assumes like "warn" that only one device is shared by the 14681a6ed33cSAntonios Motakissame export, however it will not only log a warning message but also 14691a6ed33cSAntonios Motakisdeny access to additional devices on guest. Note though that "forbid" does 14701a6ed33cSAntonios Motakiscurrently not block all possible file access operations (e.g. readdir() 14711a6ed33cSAntonios Motakiswould still return entries from other devices). 14723d54abc7SGautham R Shenoy@end table 14733d54abc7SGautham R ShenoyETEXI 14743d54abc7SGautham R Shenoy 147561d70487SMarkus ArmbrusterDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 147661d70487SMarkus Armbruster "-iscsi [user=user][,password=password]\n" 147761d70487SMarkus Armbruster " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 147861d70487SMarkus Armbruster " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 147961d70487SMarkus Armbruster " [,timeout=timeout]\n" 148061d70487SMarkus Armbruster " iSCSI session parameters\n", QEMU_ARCH_ALL) 148161d70487SMarkus Armbruster 14825824d651Sblueswir1STEXI 148344743148SMarkus Armbruster@item -iscsi 148444743148SMarkus Armbruster@findex -iscsi 148544743148SMarkus ArmbrusterConfigure iSCSI session parameters. 148644743148SMarkus ArmbrusterETEXI 148744743148SMarkus Armbruster 148844743148SMarkus ArmbrusterSTEXI 14895824d651Sblueswir1@end table 14905824d651Sblueswir1ETEXI 14915824d651Sblueswir1DEFHEADING() 14925824d651Sblueswir1 1493de6b4f90SMarkus ArmbrusterDEFHEADING(USB options:) 149410adb8beSMarkus ArmbrusterSTEXI 149510adb8beSMarkus Armbruster@table @option 149610adb8beSMarkus ArmbrusterETEXI 149710adb8beSMarkus Armbruster 149810adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 149973f46fefSStefan Hajnoczi "-usb enable on-board USB host controller (if not enabled by default)\n", 150010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 150110adb8beSMarkus ArmbrusterSTEXI 150210adb8beSMarkus Armbruster@item -usb 150310adb8beSMarkus Armbruster@findex -usb 150473f46fefSStefan HajnocziEnable USB emulation on machine types with an on-board USB host controller (if 150573f46fefSStefan Hajnoczinot enabled by default). Note that on-board USB host controllers may not 150673f46fefSStefan Hajnoczisupport USB 3.0. In this case @option{-device qemu-xhci} can be used instead 150773f46fefSStefan Hajnoczion machines with PCI. 150810adb8beSMarkus ArmbrusterETEXI 150910adb8beSMarkus Armbruster 151010adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 151110adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 151210adb8beSMarkus Armbruster QEMU_ARCH_ALL) 151310adb8beSMarkus ArmbrusterSTEXI 151410adb8beSMarkus Armbruster 151510adb8beSMarkus Armbruster@item -usbdevice @var{devname} 151610adb8beSMarkus Armbruster@findex -usbdevice 1517a358a3afSThomas HuthAdd the USB device @var{devname}. Note that this option is deprecated, 1518a358a3afSThomas Huthplease use @code{-device usb-...} instead. @xref{usb_devices}. 151910adb8beSMarkus Armbruster 152010adb8beSMarkus Armbruster@table @option 152110adb8beSMarkus Armbruster 152210adb8beSMarkus Armbruster@item mouse 152310adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 152410adb8beSMarkus Armbruster 152510adb8beSMarkus Armbruster@item tablet 152610adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 152710adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 152810adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 152910adb8beSMarkus Armbruster 153010adb8beSMarkus Armbruster@item braille 153110adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 153210adb8beSMarkus Armbrusteror fake device. 153310adb8beSMarkus Armbruster 153410adb8beSMarkus Armbruster@end table 153510adb8beSMarkus ArmbrusterETEXI 153610adb8beSMarkus Armbruster 153710adb8beSMarkus ArmbrusterSTEXI 153810adb8beSMarkus Armbruster@end table 153910adb8beSMarkus ArmbrusterETEXI 154010adb8beSMarkus ArmbrusterDEFHEADING() 154110adb8beSMarkus Armbruster 1542de6b4f90SMarkus ArmbrusterDEFHEADING(Display options:) 15435824d651Sblueswir1STEXI 15445824d651Sblueswir1@table @option 15455824d651Sblueswir1ETEXI 15465824d651Sblueswir1 15471472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 154888b40c68SThomas Huth#if defined(CONFIG_SPICE) 1549d8aec9d9SMarc-André Lureau "-display spice-app[,gl=on|off]\n" 155088b40c68SThomas Huth#endif 155188b40c68SThomas Huth#if defined(CONFIG_SDL) 155288b40c68SThomas Huth "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n" 15534867e47cSElie Tournier " [,window_close=on|off][,gl=on|core|es|off]\n" 155488b40c68SThomas Huth#endif 155588b40c68SThomas Huth#if defined(CONFIG_GTK) 1556f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 155788b40c68SThomas Huth#endif 155888b40c68SThomas Huth#if defined(CONFIG_VNC) 1559f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 156088b40c68SThomas Huth#endif 156188b40c68SThomas Huth#if defined(CONFIG_CURSES) 15622f8b7cd5SSamuel Thibault "-display curses[,charset=<encoding>]\n" 156388b40c68SThomas Huth#endif 156488b40c68SThomas Huth#if defined(CONFIG_OPENGL) 156588b40c68SThomas Huth "-display egl-headless[,rendernode=<file>]\n" 156688b40c68SThomas Huth#endif 1567144aaa99SErik Skultety "-display none\n" 156888b40c68SThomas Huth " select display backend type\n" 1569f04ec5afSRobert Ho " The default display is equivalent to\n " 1570f04ec5afSRobert Ho#if defined(CONFIG_GTK) 157188b40c68SThomas Huth "\"-display gtk\"\n" 1572f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 157388b40c68SThomas Huth "\"-display sdl\"\n" 1574f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 157588b40c68SThomas Huth "\"-display cocoa\"\n" 1576f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 157788b40c68SThomas Huth "\"-vnc localhost:0,to=99,id=default\"\n" 1578f04ec5afSRobert Ho#else 157988b40c68SThomas Huth "\"-display none\"\n" 1580f04ec5afSRobert Ho#endif 1581f04ec5afSRobert Ho , QEMU_ARCH_ALL) 15821472a95bSJes SorensenSTEXI 15831472a95bSJes Sorensen@item -display @var{type} 15841472a95bSJes Sorensen@findex -display 15851472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 15861472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 15871472a95bSJes Sorensen@table @option 15881472a95bSJes Sorensen@item sdl 15891472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 15901472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 15911472a95bSJes Sorensen@item curses 15921472a95bSJes SorensenDisplay video output via curses. For graphics device models which 15931472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 15941472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 15951472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 15961472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 15972f8b7cd5SSamuel ThibaultThe font charset used by the guest can be specified with the 15982f8b7cd5SSamuel Thibault@code{charset} option, for example @code{charset=CP850} for IBM CP850 15992f8b7cd5SSamuel Thibaultencoding. The default is @code{CP437}. 16004171d32eSJes Sorensen@item none 16014171d32eSJes SorensenDo not display video output. The guest will still see an emulated 16024171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 16034171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 16044171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 16054171d32eSJes Sorensenthe destination of the serial and parallel port data. 1606881249c7SJan Kiszka@item gtk 1607881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 1608881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 1609881249c7SJan Kiszkaruntime. 16103264ff12SJes Sorensen@item vnc 16113264ff12SJes SorensenStart a VNC server on display <arg> 1612144aaa99SErik Skultety@item egl-headless 1613144aaa99SErik SkultetyOffload all OpenGL operations to a local DRI device. For any graphical display, 1614144aaa99SErik Skultetythis display needs to be paired with either VNC or SPICE displays. 1615d8aec9d9SMarc-André Lureau@item spice-app 1616d8aec9d9SMarc-André LureauStart QEMU as a Spice server and launch the default Spice client 1617d8aec9d9SMarc-André Lureauapplication. The Spice server will redirect the serial consoles and 1618d8aec9d9SMarc-André LureauQEMU monitors. (Since 4.0) 16191472a95bSJes Sorensen@end table 16201472a95bSJes SorensenETEXI 16211472a95bSJes Sorensen 16225824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 1623ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1624ad96090aSBlue Swirl QEMU_ARCH_ALL) 16255824d651Sblueswir1STEXI 16265824d651Sblueswir1@item -nographic 16276616b2adSStefan Weil@findex -nographic 1628dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1629dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1630dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1631dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1632dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1633dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1634dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1635dc0a3e44SColin Lordswitching between the console and monitor. 16365824d651Sblueswir1ETEXI 16375824d651Sblueswir1 16385824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1639f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1640ad96090aSBlue Swirl QEMU_ARCH_ALL) 16415824d651Sblueswir1STEXI 16425824d651Sblueswir1@item -curses 1643b8f490ebSMarkus Armbruster@findex -curses 1644dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1645dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1646dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1647dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1648dc0a3e44SColin Lordmode. 16495824d651Sblueswir1ETEXI 16505824d651Sblueswir1 16515824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1652ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1653ad96090aSBlue Swirl QEMU_ARCH_ALL) 16545824d651Sblueswir1STEXI 16555824d651Sblueswir1@item -alt-grab 16566616b2adSStefan Weil@findex -alt-grab 1657de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1658de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 16595824d651Sblueswir1ETEXI 16605824d651Sblueswir1 16610ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1662ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1663ad96090aSBlue Swirl QEMU_ARCH_ALL) 16640ca9f8a4SDustin KirklandSTEXI 16650ca9f8a4SDustin Kirkland@item -ctrl-grab 16666616b2adSStefan Weil@findex -ctrl-grab 1667de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1668de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 16690ca9f8a4SDustin KirklandETEXI 16700ca9f8a4SDustin Kirkland 16715824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1672ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 16735824d651Sblueswir1STEXI 16745824d651Sblueswir1@item -no-quit 16756616b2adSStefan Weil@findex -no-quit 16765824d651Sblueswir1Disable SDL window close capability. 16775824d651Sblueswir1ETEXI 16785824d651Sblueswir1 16795824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1680f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 16815824d651Sblueswir1STEXI 16825824d651Sblueswir1@item -sdl 16836616b2adSStefan Weil@findex -sdl 16845824d651Sblueswir1Enable SDL. 16855824d651Sblueswir1ETEXI 16865824d651Sblueswir1 168729b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 168827af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 168927af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 169027af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1691fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 169227af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 169327af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 169427af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 169527af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 169627af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 169727af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 169827af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 169927af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 17005ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 17015ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 17027b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 170327af7788SYonit Halperin " enable spice\n" 170427af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 170527af7788SYonit Halperin QEMU_ARCH_ALL) 170629b0040bSGerd HoffmannSTEXI 170729b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 170829b0040bSGerd Hoffmann@findex -spice 170929b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 171029b0040bSGerd Hoffmann 171129b0040bSGerd Hoffmann@table @option 171229b0040bSGerd Hoffmann 171329b0040bSGerd Hoffmann@item port=<nr> 1714c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 171529b0040bSGerd Hoffmann 1716333b0eebSGerd Hoffmann@item addr=<addr> 1717333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1718333b0eebSGerd Hoffmann 1719333b0eebSGerd Hoffmann@item ipv4 1720f9cfd655SMarkus Armbruster@itemx ipv6 1721f9cfd655SMarkus Armbruster@itemx unix 1722333b0eebSGerd HoffmannForce using the specified IP version. 1723333b0eebSGerd Hoffmann 172429b0040bSGerd Hoffmann@item password=<secret> 172529b0040bSGerd HoffmannSet the password you need to authenticate. 172629b0040bSGerd Hoffmann 172748b3ed0aSMarc-André Lureau@item sasl 172848b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 172948b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 173048b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 173148b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 173248b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 173348b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 173448b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 173548b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 173648b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 173748b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 173848b3ed0aSMarc-André Lureaucredentials. 173948b3ed0aSMarc-André Lureau 174029b0040bSGerd Hoffmann@item disable-ticketing 174129b0040bSGerd HoffmannAllow client connects without authentication. 174229b0040bSGerd Hoffmann 1743d4970b07SHans de Goede@item disable-copy-paste 1744d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1745d4970b07SHans de Goede 17465ad24e5fSHans de Goede@item disable-agent-file-xfer 17475ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 17485ad24e5fSHans de Goede 1749c448e855SGerd Hoffmann@item tls-port=<nr> 1750c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1751c448e855SGerd Hoffmann 1752c448e855SGerd Hoffmann@item x509-dir=<dir> 1753c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1754c448e855SGerd Hoffmann 1755c448e855SGerd Hoffmann@item x509-key-file=<file> 1756f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1757f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1758f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1759f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1760c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1761c448e855SGerd Hoffmann 1762c448e855SGerd Hoffmann@item tls-ciphers=<list> 1763c448e855SGerd HoffmannSpecify which ciphers to use. 1764c448e855SGerd Hoffmann 1765d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1766f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 176717b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 176817b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 176917b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 177017b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 177117b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 177217b6dea0SGerd Hoffmann 17739f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 17749f04e09eSYonit HalperinConfigure image compression (lossless). 17759f04e09eSYonit HalperinDefault is auto_glz. 17769f04e09eSYonit Halperin 17779f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1778f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 17799f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 17809f04e09eSYonit HalperinDefault is auto. 17819f04e09eSYonit Halperin 178284a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 178393ca519eSLi ZhijianConfigure video stream detection. Default is off. 178484a23f25SGerd Hoffmann 178584a23f25SGerd Hoffmann@item agent-mouse=[on|off] 178684a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 178784a23f25SGerd Hoffmann 178884a23f25SGerd Hoffmann@item playback-compression=[on|off] 178984a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 179084a23f25SGerd Hoffmann 17918c957053SYonit Halperin@item seamless-migration=[on|off] 17928c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 17938c957053SYonit Halperin 1794474114b7SGerd Hoffmann@item gl=[on|off] 1795474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1796474114b7SGerd Hoffmann 17977b525508SMarc-André Lureau@item rendernode=<file> 17987b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 17997b525508SMarc-André Lureauthe first available. (Since 2.9) 18007b525508SMarc-André Lureau 180129b0040bSGerd Hoffmann@end table 180229b0040bSGerd HoffmannETEXI 180329b0040bSGerd Hoffmann 18045824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1805ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1806ad96090aSBlue Swirl QEMU_ARCH_ALL) 18075824d651Sblueswir1STEXI 18085824d651Sblueswir1@item -portrait 18096616b2adSStefan Weil@findex -portrait 18105824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 18115824d651Sblueswir1ETEXI 18125824d651Sblueswir1 18139312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 18149312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 18159312805dSVasily Khoruzhick QEMU_ARCH_ALL) 18169312805dSVasily KhoruzhickSTEXI 18176265c43bSMarkus Armbruster@item -rotate @var{deg} 18189312805dSVasily Khoruzhick@findex -rotate 18199312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 18209312805dSVasily KhoruzhickETEXI 18219312805dSVasily Khoruzhick 18225824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1823a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1824ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 18255824d651Sblueswir1STEXI 1826e4558dcaSmalc@item -vga @var{type} 18276616b2adSStefan Weil@findex -vga 18285824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1829b3f046c2SKevin Wolf@table @option 18305824d651Sblueswir1@item cirrus 18315824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 18325824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 18335824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 183441eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 18355824d651Sblueswir1@item std 18365824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 18375824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 18385824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 183941eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 18405824d651Sblueswir1@item vmware 18415824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 18425824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 18435824d651Sblueswir1card. 1844a19cbfb3SGerd Hoffmann@item qxl 1845a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1846a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1847a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 184833632788SMark Cave-Ayland@item tcx 184933632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 185033632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 185133632788SMark Cave-Aylandfixed resolution of 1024x768. 185233632788SMark Cave-Ayland@item cg3 185333632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 185433632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 185533632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1856a94f0c5cSGerd Hoffmann@item virtio 1857a94f0c5cSGerd HoffmannVirtio VGA card. 18585824d651Sblueswir1@item none 18595824d651Sblueswir1Disable VGA card. 18605824d651Sblueswir1@end table 18615824d651Sblueswir1ETEXI 18625824d651Sblueswir1 18635824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1864ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 18655824d651Sblueswir1STEXI 18665824d651Sblueswir1@item -full-screen 18676616b2adSStefan Weil@findex -full-screen 18685824d651Sblueswir1Start in full screen. 18695824d651Sblueswir1ETEXI 18705824d651Sblueswir1 18715824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1872ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 18738ac919a0SLaurent Vivier QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K) 18745824d651Sblueswir1STEXI 187595d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 18766616b2adSStefan Weil@findex -g 187795d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 18785824d651Sblueswir1ETEXI 18795824d651Sblueswir1 18805824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1881f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 18825824d651Sblueswir1STEXI 18835824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 18846616b2adSStefan Weil@findex -vnc 1885dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1886dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1887dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1888dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1889dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1890a358a3afSThomas Huth(option @option{-device usb-tablet}). When using the VNC display, you 1891dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1892dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 18935824d651Sblueswir1 1894b3f046c2SKevin Wolf@table @option 18955824d651Sblueswir1 189699a9a52aSRobert Ho@item to=@var{L} 189799a9a52aSRobert Ho 189899a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 189999a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 190099a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 190199a9a52aSRobert Hoapplication. By default, to=0. 190299a9a52aSRobert Ho 19035824d651Sblueswir1@item @var{host}:@var{d} 19045824d651Sblueswir1 19055824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 19065824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 19075824d651Sblueswir1be omitted in which case the server will accept connections from any host. 19085824d651Sblueswir1 19094e257e5eSKevin Wolf@item unix:@var{path} 19105824d651Sblueswir1 19115824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 19125824d651Sblueswir1location of a unix socket to listen for connections on. 19135824d651Sblueswir1 19145824d651Sblueswir1@item none 19155824d651Sblueswir1 19165824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 19175824d651Sblueswir1can be used to later start the VNC server. 19185824d651Sblueswir1 19195824d651Sblueswir1@end table 19205824d651Sblueswir1 19215824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 19225824d651Sblueswir1separated by commas. Valid options are 19235824d651Sblueswir1 1924b3f046c2SKevin Wolf@table @option 19255824d651Sblueswir1 19265824d651Sblueswir1@item reverse 19275824d651Sblueswir1 19285824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 19295824d651Sblueswir1client is specified by the @var{display}. For reverse network 19305824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 19315824d651Sblueswir1is a TCP port number, not a display number. 19325824d651Sblueswir1 19337536ee4bSTim Hardeck@item websocket 19347536ee4bSTim Hardeck 19357536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1936275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 1937275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 1938275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 1939275e0d61SDaniel P. Berrange 1940275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 1941275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 1942275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 1943275e0d61SDaniel P. Berrange 19443e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 19453e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 19463e305e4aSDaniel P. Berrangerequires encrypted client connections. 19477536ee4bSTim Hardeck 19485824d651Sblueswir1@item password 19495824d651Sblueswir1 19505824d651Sblueswir1Require that password based authentication is used for client connections. 195186ee5bc3SMichal Novotny 195286ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 195386ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 195486ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 195586ee5bc3SMichal Novotny"vnc" or "spice". 195686ee5bc3SMichal Novotny 195786ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 195886ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 195986ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 196086ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 196186ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 196286ee5bc3SMichal Novotnydate and time). 196386ee5bc3SMichal Novotny 196486ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 196586ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 19665824d651Sblueswir1 19673e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 19683e305e4aSDaniel P. Berrange 19693e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 19703e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 19713e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 19723e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 19733e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 19743e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 19753e305e4aSDaniel P. Berrange 197655cf09a0SDaniel P. Berrange@item tls-authz=@var{ID} 197755cf09a0SDaniel P. Berrange 197855cf09a0SDaniel P. BerrangeProvides the ID of the QAuthZ authorization object against which 197955cf09a0SDaniel P. Berrangethe client's x509 distinguished name will validated. This object is 198055cf09a0SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the 198155cf09a0SDaniel P. Berrangefly while the VNC server is active. If missing, it will default 198255cf09a0SDaniel P. Berrangeto denying access. 198355cf09a0SDaniel P. Berrange 19845824d651Sblueswir1@item sasl 19855824d651Sblueswir1 19865824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 19875824d651Sblueswir1The exact choice of authentication method used is controlled from the 19885824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 19895824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 19905824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 19915824d651Sblueswir1to make it search alternate locations for the service config. 19925824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 19935824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 19945824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 19955824d651Sblueswir1ensures a data encryption preventing compromise of authentication 19965824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 19975824d651Sblueswir1SASL authentication. 19985824d651Sblueswir1 199955cf09a0SDaniel P. Berrange@item sasl-authz=@var{ID} 200055cf09a0SDaniel P. Berrange 200155cf09a0SDaniel P. BerrangeProvides the ID of the QAuthZ authorization object against which 200255cf09a0SDaniel P. Berrangethe client's SASL username will validated. This object is 200355cf09a0SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the 200455cf09a0SDaniel P. Berrangefly while the VNC server is active. If missing, it will default 200555cf09a0SDaniel P. Berrangeto denying access. 200655cf09a0SDaniel P. Berrange 20075824d651Sblueswir1@item acl 20085824d651Sblueswir1 200955cf09a0SDaniel P. BerrangeLegacy method for enabling authorization of clients against the 201055cf09a0SDaniel P. Berrangex509 distinguished name and SASL username. It results in the creation 201155cf09a0SDaniel P. Berrangeof two @code{authz-list} objects with IDs of @code{vnc.username} and 201255cf09a0SDaniel P. Berrange@code{vnc.x509dname}. The rules for these objects must be configured 201355cf09a0SDaniel P. Berrangewith the HMP ACL commands. 201455cf09a0SDaniel P. Berrange 201555cf09a0SDaniel P. BerrangeThis option is deprecated and should no longer be used. The new 201655cf09a0SDaniel P. Berrange@option{sasl-authz} and @option{tls-authz} options are a 201755cf09a0SDaniel P. Berrangereplacement. 20185824d651Sblueswir1 20196f9c78c1SCorentin Chary@item lossy 20206f9c78c1SCorentin Chary 20216f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 20226f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 20236f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 20246f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 20256f9c78c1SCorentin Chary 202680e0c8c3SCorentin Chary@item non-adaptive 202780e0c8c3SCorentin Chary 202880e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 202980e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 203080e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 203161cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 20329d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 203380e0c8c3SCorentin Charylike Tight. 203480e0c8c3SCorentin Chary 20358cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 20368cf36489SGerd Hoffmann 20378cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 20388cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 20398cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 20408cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 20418cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 20428cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 20438cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 20448cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 20458cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 2046b65ee4faSStefan Weilspec but is traditional QEMU behavior. 20478cf36489SGerd Hoffmann 2048c5ce8333SGerd Hoffmann@item key-delay-ms 2049c5ce8333SGerd Hoffmann 2050c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 2051d3b0db6dSAlexander GrafDefault is 10. Keyboards are low-bandwidth devices, so this slowdown 2052c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 2053c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 2054c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 2055c5ce8333SGerd Hoffmann 2056f0b9f36dSKővágó, Zoltán@item audiodev=@var{audiodev} 2057f0b9f36dSKővágó, Zoltán 2058f0b9f36dSKővágó, ZoltánUse the specified @var{audiodev} when the VNC client requests audio 2059f0b9f36dSKővágó, Zoltántransmission. When not using an -audiodev argument, this option must 2060f0b9f36dSKővágó, Zoltánbe omitted, otherwise is must be present and specify a valid audiodev. 2061f0b9f36dSKővágó, Zoltán 20625824d651Sblueswir1@end table 20635824d651Sblueswir1ETEXI 20645824d651Sblueswir1 20655824d651Sblueswir1STEXI 20665824d651Sblueswir1@end table 20675824d651Sblueswir1ETEXI 2068a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 20695824d651Sblueswir1 2070de6b4f90SMarkus ArmbrusterARCHHEADING(i386 target only:, QEMU_ARCH_I386) 20715824d651Sblueswir1STEXI 20725824d651Sblueswir1@table @option 20735824d651Sblueswir1ETEXI 20745824d651Sblueswir1 20755824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 2076ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 2077ad96090aSBlue Swirl QEMU_ARCH_I386) 20785824d651Sblueswir1STEXI 20795824d651Sblueswir1@item -win2k-hack 20806616b2adSStefan Weil@findex -win2k-hack 20815824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 20825824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 20835824d651Sblueswir1slows down the IDE transfers). 20845824d651Sblueswir1ETEXI 20855824d651Sblueswir1 20865824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 2087ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 2088ad96090aSBlue Swirl QEMU_ARCH_I386) 20895824d651Sblueswir1STEXI 20905824d651Sblueswir1@item -no-fd-bootchk 20916616b2adSStefan Weil@findex -no-fd-bootchk 20924eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 20935824d651Sblueswir1be needed to boot from old floppy disks. 20945824d651Sblueswir1ETEXI 20955824d651Sblueswir1 20965824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 2097f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 20985824d651Sblueswir1STEXI 20995824d651Sblueswir1@item -no-acpi 21006616b2adSStefan Weil@findex -no-acpi 21015824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 21025824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 21035824d651Sblueswir1only). 21045824d651Sblueswir1ETEXI 21055824d651Sblueswir1 21065824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 2107ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 21085824d651Sblueswir1STEXI 21095824d651Sblueswir1@item -no-hpet 21106616b2adSStefan Weil@findex -no-hpet 21115824d651Sblueswir1Disable HPET support. 21125824d651Sblueswir1ETEXI 21135824d651Sblueswir1 21145824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 2115104bf02eSMichael 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" 2116ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 21175824d651Sblueswir1STEXI 21185824d651Sblueswir1@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}]...] 21196616b2adSStefan Weil@findex -acpitable 21205824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 2121104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 2122104bf02eSMichael TokarevACPI headers (possible overridden by other options). 2123104bf02eSMichael TokarevFor data=, only data 2124104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 2125104bf02eSMichael Tokarevcommand line. 2126ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 2127ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 2128ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 2129ae123749SLaszlo Ersekspec. 21305824d651Sblueswir1ETEXI 21315824d651Sblueswir1 2132b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 2133b6f6e3d3Saliguori "-smbios file=binary\n" 2134ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 2135b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 2136b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 2137ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 2138b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2139b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 2140b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 2141b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2142b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 2143b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 2144b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 2145b155eb1dSGabriel L. Somlo " [,sku=str]\n" 2146b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 2147b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 2148b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 2149b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 2150b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 21513ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 2152b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 2153c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 2154b6f6e3d3SaliguoriSTEXI 2155b6f6e3d3Saliguori@item -smbios file=@var{binary} 21566616b2adSStefan Weil@findex -smbios 2157b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 2158b6f6e3d3Saliguori 215984351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 2160b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 2161b6f6e3d3Saliguori 2162b6f6e3d3Saliguori@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}] 2163b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 2164b155eb1dSGabriel L. Somlo 21653fdbd1d7SIgor Mammedov@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}] 2166b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 2167b155eb1dSGabriel L. Somlo 2168b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 2169b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 2170b155eb1dSGabriel L. Somlo 2171b155eb1dSGabriel 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}] 2172b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 2173b155eb1dSGabriel L. Somlo 21743ebd6cc8SGabriel 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}] 2175b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 2176b6f6e3d3SaliguoriETEXI 2177b6f6e3d3Saliguori 21785824d651Sblueswir1STEXI 21795824d651Sblueswir1@end table 21805824d651Sblueswir1ETEXI 2181c70a01e4SMarkus ArmbrusterDEFHEADING() 21825824d651Sblueswir1 2183de6b4f90SMarkus ArmbrusterDEFHEADING(Network options:) 21845824d651Sblueswir1STEXI 21855824d651Sblueswir1@table @option 21865824d651Sblueswir1ETEXI 21875824d651Sblueswir1 21886a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 21895824d651Sblueswir1#ifdef CONFIG_SLIRP 21900b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 21910b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 21920b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 2193f18d1375SBenjamin Drung " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 21940fca92b9SFam Zheng " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 2195ad196a9dSJan Kiszka#ifndef _WIN32 2196c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 2197ad196a9dSJan Kiszka#endif 21986a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 21996a8b4a5bSThomas Huth " its DHCP server and optional services\n" 22005824d651Sblueswir1#endif 22015824d651Sblueswir1#ifdef _WIN32 22026a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 22036a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 22045824d651Sblueswir1#else 22056a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 2206584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 22076a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 220869e87b32SJason Wang " [,poll-us=n]\n" 22096a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 2210584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 2211a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 2212a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 2213a7c36ee4SCorey Bryant " to deconfigure it\n" 2214ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 2215a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 2216a7c36ee4SCorey Bryant " configure it\n" 22175824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 22182ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 2219ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 2220f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 2221ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 2222ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 222382b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 22245430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 22255430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 222682b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 22272ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 2228ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 222969e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 223069e87b32SJason Wang " spent on busy polling for vhost net\n" 22316a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 22326a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 22336a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 22346a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 22350df0ff6dSMark McLoughlin#endif 22363fb69aa1SAnton Ivanov#ifdef __linux__ 22376a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 22386a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 22396a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 22406a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 22416a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 22426a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 22433fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 22442f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 22453fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 22463fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 22473fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 22483fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 22493fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 22503fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 22513952651aSGonglei " use 'srcport=' to specify source udp port\n" 22523fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 22533fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 22543fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 22553fb69aa1SAnton Ivanov " well as a weak security measure\n" 22563fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 22573fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 22583fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 22593fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 22603fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 22613fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 22623fb69aa1SAnton Ivanov#endif 22636a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 22646a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 22656a8b4a5bSThomas Huth " using a socket connection\n" 22666a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 22676a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 22683a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 22696a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 22706a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 22716a8b4a5bSThomas Huth " using an UDP tunnel\n" 22725824d651Sblueswir1#ifdef CONFIG_VDE 22736a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 22746a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 22756a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 22765824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 22775824d651Sblueswir1 " ownership and permissions for communication port.\n" 22785824d651Sblueswir1#endif 227958952137SVincenzo Maffione#ifdef CONFIG_NETMAP 22806a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 228158952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 228258952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 228358952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 228458952137SVincenzo Maffione#endif 2285253dc14cSThomas Huth#ifdef CONFIG_POSIX 22866a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 22876a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 2288253dc14cSThomas Huth#endif 228918d65d22SThomas Huth "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 2290af1a5c3eSThomas Huth " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 229178cd6f7bSThomas HuthDEF("nic", HAS_ARG, QEMU_OPTION_nic, 2292dfaa7d50SBALATON Zoltan "-nic [tap|bridge|" 229378cd6f7bSThomas Huth#ifdef CONFIG_SLIRP 229478cd6f7bSThomas Huth "user|" 229578cd6f7bSThomas Huth#endif 229678cd6f7bSThomas Huth#ifdef __linux__ 229778cd6f7bSThomas Huth "l2tpv3|" 229878cd6f7bSThomas Huth#endif 229978cd6f7bSThomas Huth#ifdef CONFIG_VDE 230078cd6f7bSThomas Huth "vde|" 230178cd6f7bSThomas Huth#endif 230278cd6f7bSThomas Huth#ifdef CONFIG_NETMAP 230378cd6f7bSThomas Huth "netmap|" 230478cd6f7bSThomas Huth#endif 230578cd6f7bSThomas Huth#ifdef CONFIG_POSIX 230678cd6f7bSThomas Huth "vhost-user|" 230778cd6f7bSThomas Huth#endif 230878cd6f7bSThomas Huth "socket][,option][,...][mac=macaddr]\n" 230978cd6f7bSThomas Huth " initialize an on-board / default host NIC (using MAC address\n" 231078cd6f7bSThomas Huth " macaddr) and connect it to the given host network backend\n" 2311dfaa7d50SBALATON Zoltan "-nic none use it alone to have zero network devices (the default is to\n" 231278cd6f7bSThomas Huth " provided a 'user' network connection)\n", 231378cd6f7bSThomas Huth QEMU_ARCH_ALL) 23146a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 2315af1a5c3eSThomas Huth "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 23160e60a82dSThomas Huth " configure or create an on-board (or machine default) NIC and\n" 2317af1a5c3eSThomas Huth " connect it to hub 0 (please use -nic unless you need a hub)\n" 23186a8b4a5bSThomas Huth "-net [" 2319a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 2320a1ea458fSMark McLoughlin "user|" 2321a1ea458fSMark McLoughlin#endif 2322a1ea458fSMark McLoughlin "tap|" 2323a7c36ee4SCorey Bryant "bridge|" 2324a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 2325a1ea458fSMark McLoughlin "vde|" 2326a1ea458fSMark McLoughlin#endif 232758952137SVincenzo Maffione#ifdef CONFIG_NETMAP 232858952137SVincenzo Maffione "netmap|" 232958952137SVincenzo Maffione#endif 2330af1a5c3eSThomas Huth "socket][,option][,option][,...]\n" 23316a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 23326a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 23335824d651Sblueswir1STEXI 2334abbbb035SThomas Huth@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 2335abbbb035SThomas Huth@findex -nic 2336abbbb035SThomas HuthThis option is a shortcut for configuring both the on-board (default) guest 2337abbbb035SThomas HuthNIC hardware and the host network backend in one go. The host backend options 2338abbbb035SThomas Huthare the same as with the corresponding @option{-netdev} options below. 2339abbbb035SThomas HuthThe guest NIC model can be set with @option{model=@var{modelname}}. 2340abbbb035SThomas HuthUse @option{model=help} to list the available device types. 2341abbbb035SThomas HuthThe hardware MAC address can be set with @option{mac=@var{macaddr}}. 2342abbbb035SThomas Huth 2343abbbb035SThomas HuthThe following two example do exactly the same, to show how @option{-nic} can 2344abbbb035SThomas Huthbe used to shorten the command line length (note that the e1000 is the default 2345abbbb035SThomas Huthon i386, so the @option{model=e1000} parameter could even be omitted here, too): 2346abbbb035SThomas Huth@example 2347664785acSThomas Huth@value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 2348664785acSThomas Huth@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 2349abbbb035SThomas Huth@end example 2350abbbb035SThomas Huth 2351abbbb035SThomas Huth@item -nic none 2352abbbb035SThomas HuthIndicate that no network devices should be configured. It is used to override 2353abbbb035SThomas Huththe default configuration (default NIC with ``user'' host network backend) 2354abbbb035SThomas Huthwhich is activated if no other networking options are provided. 23555824d651Sblueswir1 235608d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 2357b8f490ebSMarkus Armbruster@findex -netdev 2358abbbb035SThomas HuthConfigure user mode host network backend which requires no administrator 2359ad196a9dSJan Kiszkaprivilege to run. Valid options are: 23605824d651Sblueswir1 2361b3f046c2SKevin Wolf@table @option 236208d12022SStefan Hajnoczi@item id=@var{id} 2363ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 2364ad196a9dSJan Kiszka 2365abbbb035SThomas Huth@item ipv4=on|off and ipv6=on|off 2366abbbb035SThomas HuthSpecify that either IPv4 or IPv6 must be enabled. If neither is specified 2367abbbb035SThomas Huthboth protocols are enabled. 23680b11c036SSamuel Thibault 2369c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 2370c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 2371c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 2372b0b36e5dSBrad Hards10.0.2.0/24. 2373c92ef6a2SJan Kiszka 2374c92ef6a2SJan Kiszka@item host=@var{addr} 2375c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 2376c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 2377ad196a9dSJan Kiszka 2378d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 2379d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 2380d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 2381d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 2382d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 23837aac531eSYann Bordenave 2384d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 23857aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 23867aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 23877aac531eSYann Bordenave 2388c54ed5bcSJan Kiszka@item restrict=on|off 2389caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 2390ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 2391caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 2392ad196a9dSJan Kiszka 2393ad196a9dSJan Kiszka@item hostname=@var{name} 239463d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 2395ad196a9dSJan Kiszka 2396c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 2397c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 2398b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2399c92ef6a2SJan Kiszka 2400c92ef6a2SJan Kiszka@item dns=@var{addr} 2401c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 2402c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 2403c92ef6a2SJan Kiszkai.e. x.x.x.3. 2404c92ef6a2SJan Kiszka 2405d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 24067aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 24077aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 24087aac531eSYann Bordenavenetwork, i.e. xxxx::3. 24097aac531eSYann Bordenave 241063d2960bSKlaus Stengel@item dnssearch=@var{domain} 241163d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 241263d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 241363d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 241463d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 241563d2960bSKlaus Stengelcan not be resolved. 241663d2960bSKlaus Stengel 241763d2960bSKlaus StengelExample: 241863d2960bSKlaus Stengel@example 2419664785acSThomas Huth@value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 242063d2960bSKlaus Stengel@end example 242163d2960bSKlaus Stengel 2422f18d1375SBenjamin Drung@item domainname=@var{domain} 2423f18d1375SBenjamin DrungSpecifies the client domain name reported by the built-in DHCP server. 2424f18d1375SBenjamin Drung 2425ad196a9dSJan Kiszka@item tftp=@var{dir} 2426ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 2427ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 2428ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 2429c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 2430ad196a9dSJan Kiszka 24310fca92b9SFam Zheng@item tftp-server-name=@var{name} 24320fca92b9SFam ZhengIn BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option 24330fca92b9SFam Zheng66). This can be used to advise the guest to load boot files or configurations 24340fca92b9SFam Zhengfrom a different server than the host address. 24350fca92b9SFam Zheng 2436ad196a9dSJan Kiszka@item bootfile=@var{file} 2437ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 2438ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 2439ad196a9dSJan Kiszkaa guest from a local directory. 2440ad196a9dSJan Kiszka 2441ad196a9dSJan KiszkaExample (using pxelinux): 2442ad196a9dSJan Kiszka@example 2443664785acSThomas Huth@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \ 2444abbbb035SThomas Huth -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2445ad196a9dSJan Kiszka@end example 2446ad196a9dSJan Kiszka 2447c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 2448ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 2449ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 2450c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 2451c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 2452ad196a9dSJan Kiszka 2453ad196a9dSJan KiszkaIn the guest Windows OS, the line: 2454ad196a9dSJan Kiszka@example 2455ad196a9dSJan Kiszka10.0.2.4 smbserver 2456ad196a9dSJan Kiszka@end example 2457ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2458ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2459ad196a9dSJan Kiszka 2460ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2461ad196a9dSJan Kiszka 2462e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 2463ad196a9dSJan Kiszka 24643c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2465c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 2466c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 2467c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 24683c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 24693c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 2470c92ef6a2SJan Kiszkaused. This option can be given multiple times. 2471ad196a9dSJan Kiszka 2472ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 2473ad196a9dSJan Kiszkascreen 0, use the following: 2474ad196a9dSJan Kiszka 2475ad196a9dSJan Kiszka@example 2476ad196a9dSJan Kiszka# on the host 2477664785acSThomas Huth@value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 2478ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 2479ad196a9dSJan Kiszkaxterm -display :1 2480ad196a9dSJan Kiszka@end example 2481ad196a9dSJan Kiszka 2482ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 2483ad196a9dSJan Kiszkathe guest, use the following: 2484ad196a9dSJan Kiszka 2485ad196a9dSJan Kiszka@example 2486ad196a9dSJan Kiszka# on the host 2487664785acSThomas Huth@value{qemu_system} -nic user,hostfwd=tcp::5555-:23 2488ad196a9dSJan Kiszkatelnet localhost 5555 2489ad196a9dSJan Kiszka@end example 2490ad196a9dSJan Kiszka 2491ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 2492ad196a9dSJan Kiszkaconnect to the guest telnet server. 2493ad196a9dSJan Kiszka 2494c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2495f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 24963c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 2497b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 2498b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 2499b412eb61SAlexander Graf 250043ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 2501b412eb61SAlexander Graflifetime, like in the following example: 2502b412eb61SAlexander Graf 2503b412eb61SAlexander Graf@example 2504b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2505b412eb61SAlexander Graf# the guest accesses it 2506664785acSThomas Huth@value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 2507b412eb61SAlexander Graf@end example 2508b412eb61SAlexander Graf 2509b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 251043ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 2511b412eb61SAlexander Graf 2512b412eb61SAlexander Graf@example 2513b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2514b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 2515664785acSThomas Huth@value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2516b412eb61SAlexander Graf@end example 2517ad196a9dSJan Kiszka 2518ad196a9dSJan Kiszka@end table 2519ad196a9dSJan Kiszka 2520584613eaSAlexey 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}] 2521abbbb035SThomas HuthConfigure a host TAP network backend with ID @var{id}. 2522a7c36ee4SCorey Bryant 2523a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 25245824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2525a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 2526a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 2527a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2528a7c36ee4SCorey Bryantto disable script execution. 2529a7c36ee4SCorey Bryant 2530a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 2531584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 2532584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 2533584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 2534a7c36ee4SCorey Bryant 2535a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 2536a7c36ee4SCorey Bryantopened host TAP interface. 2537a7c36ee4SCorey Bryant 2538a7c36ee4SCorey BryantExamples: 25395824d651Sblueswir1 25405824d651Sblueswir1@example 2541a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 2542664785acSThomas Huth@value{qemu_system} linux.img -nic tap 25435824d651Sblueswir1@end example 25445824d651Sblueswir1 25455824d651Sblueswir1@example 2546a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 2547a7c36ee4SCorey Bryant#to a TAP device 2548664785acSThomas Huth@value{qemu_system} linux.img \ 254974f78b99SThomas Huth -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 255074f78b99SThomas Huth -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 25515824d651Sblueswir1@end example 25525824d651Sblueswir1 2553a7c36ee4SCorey Bryant@example 2554a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2555a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2556664785acSThomas Huth@value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \ 2557abbbb035SThomas Huth -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 2558a7c36ee4SCorey Bryant@end example 2559a7c36ee4SCorey Bryant 256008d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2561a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 2562a7c36ee4SCorey Bryant 2563a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 2564a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 2565420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 2566a7c36ee4SCorey Bryantdevice is @file{br0}. 2567a7c36ee4SCorey Bryant 2568a7c36ee4SCorey BryantExamples: 2569a7c36ee4SCorey Bryant 2570a7c36ee4SCorey Bryant@example 2571a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2572a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 2573664785acSThomas Huth@value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 2574a7c36ee4SCorey Bryant@end example 2575a7c36ee4SCorey Bryant 2576a7c36ee4SCorey Bryant@example 2577a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2578a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 2579664785acSThomas Huth@value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 2580a7c36ee4SCorey Bryant@end example 2581a7c36ee4SCorey Bryant 258208d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 25835824d651Sblueswir1 2584abbbb035SThomas HuthThis host network backend can be used to connect the guest's network to 2585abbbb035SThomas Huthanother QEMU virtual machine using a TCP socket connection. If @option{listen} 2586abbbb035SThomas Huthis specified, QEMU waits for incoming connections on @var{port} 25875824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 25885824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 25895824d651Sblueswir1specifies an already opened TCP socket. 25905824d651Sblueswir1 25915824d651Sblueswir1Example: 25925824d651Sblueswir1@example 25935824d651Sblueswir1# launch a first QEMU instance 2594664785acSThomas Huth@value{qemu_system} linux.img \ 2595abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2596abbbb035SThomas Huth -netdev socket,id=n1,listen=:1234 2597abbbb035SThomas Huth# connect the network of this instance to the network of the first instance 2598664785acSThomas Huth@value{qemu_system} linux.img \ 2599abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2600abbbb035SThomas Huth -netdev socket,id=n2,connect=127.0.0.1:1234 26015824d651Sblueswir1@end example 26025824d651Sblueswir1 260308d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 26045824d651Sblueswir1 2605abbbb035SThomas HuthConfigure a socket host network backend to share the guest's network traffic 2606abbbb035SThomas Huthwith another QEMU virtual machines using a UDP multicast socket, effectively 2607abbbb035SThomas Huthmaking a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 26085824d651Sblueswir1NOTES: 26095824d651Sblueswir1@enumerate 26105824d651Sblueswir1@item 26115824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 26125824d651Sblueswir1correct multicast setup for these hosts). 26135824d651Sblueswir1@item 26145824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 26155824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 26165824d651Sblueswir1@item 26175824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 26185824d651Sblueswir1@end enumerate 26195824d651Sblueswir1 26205824d651Sblueswir1Example: 26215824d651Sblueswir1@example 26225824d651Sblueswir1# launch one QEMU instance 2623664785acSThomas Huth@value{qemu_system} linux.img \ 2624abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2625abbbb035SThomas Huth -netdev socket,id=n1,mcast=230.0.0.1:1234 26265824d651Sblueswir1# launch another QEMU instance on same "bus" 2627664785acSThomas Huth@value{qemu_system} linux.img \ 2628abbbb035SThomas Huth -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2629abbbb035SThomas Huth -netdev socket,id=n2,mcast=230.0.0.1:1234 26305824d651Sblueswir1# launch yet another QEMU instance on same "bus" 2631664785acSThomas Huth@value{qemu_system} linux.img \ 263237a4442aSThomas Huth -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 2633abbbb035SThomas Huth -netdev socket,id=n3,mcast=230.0.0.1:1234 26345824d651Sblueswir1@end example 26355824d651Sblueswir1 26365824d651Sblueswir1Example (User Mode Linux compat.): 26375824d651Sblueswir1@example 2638abbbb035SThomas Huth# launch QEMU instance (note mcast address selected is UML's default) 2639664785acSThomas Huth@value{qemu_system} linux.img \ 2640abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2641abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102 26425824d651Sblueswir1# launch UML 26435824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 26445824d651Sblueswir1@end example 26455824d651Sblueswir1 26463a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 26473a75e74cSMike Ryan@example 2648664785acSThomas Huth@value{qemu_system} linux.img \ 2649abbbb035SThomas Huth -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2650abbbb035SThomas Huth -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 26513a75e74cSMike Ryan@end example 26523a75e74cSMike Ryan 26533fb69aa1SAnton 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}] 2654abbbb035SThomas HuthConfigure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a 2655abbbb035SThomas Huthpopular protocol to transport Ethernet (and other Layer 2) data frames between 26563fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 26573fb69aa1SAnton Ivanov(from version 3.3 onwards). 26583fb69aa1SAnton Ivanov 26593fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 26603fb69aa1SAnton Ivanov 26611e9a7379SMarkus Armbruster@table @option 26623fb69aa1SAnton Ivanov@item src=@var{srcaddr} 26633fb69aa1SAnton Ivanov source address (mandatory) 26643fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 26653fb69aa1SAnton Ivanov destination address (mandatory) 26663fb69aa1SAnton Ivanov@item udp 26673fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 26683fb69aa1SAnton Ivanov@item srcport=@var{srcport} 26693fb69aa1SAnton Ivanov source udp port. 26703fb69aa1SAnton Ivanov@item dstport=@var{dstport} 26713fb69aa1SAnton Ivanov destination udp port. 26723fb69aa1SAnton Ivanov@item ipv6 26733fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 26743fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2675f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 26763fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 26773fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 26783fb69aa1SAnton Ivanovbit. 26793fb69aa1SAnton Ivanov@item cookie64 26803fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 26813fb69aa1SAnton Ivanov@item counter=off 26823fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 26833fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 26843fb69aa1SAnton Ivanov@item pincounter=on 26853fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 26863fb69aa1SAnton Ivanovnetworks which have packet reorder. 26873fb69aa1SAnton Ivanov@item offset=@var{offset} 26883fb69aa1SAnton Ivanov Add an extra offset between header and data 26891e9a7379SMarkus Armbruster@end table 26903fb69aa1SAnton Ivanov 26913fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 26923fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 26933fb69aa1SAnton Ivanov@example 26943fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 26953fb69aa1SAnton Ivanov# on 1.2.3.4 26963fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 26973fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 26983fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 26993fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 27003fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 27013fb69aa1SAnton Ivanovifconfig vmtunnel0 up 27023fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 27033fb69aa1SAnton Ivanov 27043fb69aa1SAnton Ivanov 27053fb69aa1SAnton Ivanov# on 4.3.2.1 27063fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 27073fb69aa1SAnton Ivanov 2708664785acSThomas Huth@value{qemu_system} linux.img -device e1000,netdev=n1 \ 2709abbbb035SThomas 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 27103fb69aa1SAnton Ivanov 27113fb69aa1SAnton Ivanov@end example 27123fb69aa1SAnton Ivanov 271308d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2714abbbb035SThomas HuthConfigure VDE backend to connect to PORT @var{n} of a vde switch running on host and 27155824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 27165824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2717c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 27185824d651Sblueswir1with vde support enabled. 27195824d651Sblueswir1 27205824d651Sblueswir1Example: 27215824d651Sblueswir1@example 27225824d651Sblueswir1# launch vde switch 27235824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 27245824d651Sblueswir1# launch QEMU instance 2725664785acSThomas Huth@value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch 27265824d651Sblueswir1@end example 27275824d651Sblueswir1 2728b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 272903ce5744SNikolay Nikolaev 273003ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 273103ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 273203ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 273303ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2734b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2735b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 273603ce5744SNikolay Nikolaev 273703ce5744SNikolay NikolaevExample: 273803ce5744SNikolay Nikolaev@example 273903ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 274003ce5744SNikolay Nikolaev -numa node,memdev=mem \ 274179cad2faSVincenzo Maffione -chardev socket,id=chr0,path=/path/to/socket \ 274203ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 274303ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 274403ce5744SNikolay Nikolaev@end example 274503ce5744SNikolay Nikolaev 2746abbbb035SThomas Huth@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 274778cd6f7bSThomas Huth 2748abbbb035SThomas HuthCreate a hub port on the emulated hub with ID @var{hubid}. 274978cd6f7bSThomas Huth 2750abbbb035SThomas HuthThe hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 2751af1a5c3eSThomas Huthsingle netdev. Alternatively, you can also connect the hubport to another 2752af1a5c3eSThomas Huthnetdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 2753abbbb035SThomas Huth 2754af1a5c3eSThomas Huth@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 2755abbbb035SThomas Huth@findex -net 2756abbbb035SThomas HuthLegacy option to configure or create an on-board (or machine default) Network 2757af1a5c3eSThomas HuthInterface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 2758af1a5c3eSThomas Huththe default hub), or to the netdev @var{nd}. 2759abbbb035SThomas HuthThe NIC is an e1000 by default on the PC target. Optionally, the MAC address 2760abbbb035SThomas Huthcan be changed to @var{mac}, the device address set to @var{addr} (PCI cards 2761abbbb035SThomas Huthonly), and a @var{name} can be assigned for use in monitor commands. 2762abbbb035SThomas HuthOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2763abbbb035SThomas Huththat the card should have; this option currently only affects virtio cards; set 2764abbbb035SThomas Huth@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2765abbbb035SThomas HuthNIC is created. QEMU can emulate several different models of network card. 2766abbbb035SThomas HuthUse @code{-net nic,model=help} for a list of available devices for your target. 2767abbbb035SThomas Huth 2768af1a5c3eSThomas Huth@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 2769abbbb035SThomas HuthConfigure a host network backend (with the options corresponding to the same 2770af1a5c3eSThomas Huth@option{-netdev} option) and connect it to the emulated hub 0 (the default 2771af1a5c3eSThomas Huthhub). Use @var{name} to specify the name of the hub port. 27725824d651Sblueswir1ETEXI 27735824d651Sblueswir1 2774c70a01e4SMarkus ArmbrusterSTEXI 2775c70a01e4SMarkus Armbruster@end table 2776c70a01e4SMarkus ArmbrusterETEXI 27777273a2dbSMatthew BoothDEFHEADING() 27787273a2dbSMatthew Booth 2779de6b4f90SMarkus ArmbrusterDEFHEADING(Character device options:) 27807273a2dbSMatthew Booth 27817273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2782517b3d40SLin Ma "-chardev help\n" 2783d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 27845dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2785981b06e7SJulia Suvorova " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n" 2786fd4a5fd4SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n" 2787981b06e7SJulia Suvorova "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n" 2788d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 27897273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 279097331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2791d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2792d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 27937273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2794d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2795d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2796d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2797d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 27987273a2dbSMatthew Booth#ifdef _WIN32 2799d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2800d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28017273a2dbSMatthew Booth#else 2802d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2803d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 28047273a2dbSMatthew Booth#endif 28057273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2806d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28077273a2dbSMatthew Booth#endif 28087273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 28097273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2810d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2811d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28127273a2dbSMatthew Booth#endif 28137273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2814d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2815d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 28167273a2dbSMatthew Booth#endif 2817cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2818d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2819d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2820cbcc6336SAlon Levy#endif 2821ad96090aSBlue Swirl , QEMU_ARCH_ALL 28227273a2dbSMatthew Booth) 28237273a2dbSMatthew Booth 28247273a2dbSMatthew BoothSTEXI 2825dddba068SMarkus Armbruster 2826dddba068SMarkus ArmbrusterThe general form of a character device option is: 2827dddba068SMarkus Armbruster@table @option 282897331287SJan Kiszka@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 28296616b2adSStefan Weil@findex -chardev 28307273a2dbSMatthew BoothBackend is one of: 28317273a2dbSMatthew Booth@option{null}, 28327273a2dbSMatthew Booth@option{socket}, 28337273a2dbSMatthew Booth@option{udp}, 28347273a2dbSMatthew Booth@option{msmouse}, 28357273a2dbSMatthew Booth@option{vc}, 28364f57378fSMarkus Armbruster@option{ringbuf}, 28377273a2dbSMatthew Booth@option{file}, 28387273a2dbSMatthew Booth@option{pipe}, 28397273a2dbSMatthew Booth@option{console}, 28407273a2dbSMatthew Booth@option{serial}, 28417273a2dbSMatthew Booth@option{pty}, 28427273a2dbSMatthew Booth@option{stdio}, 28437273a2dbSMatthew Booth@option{braille}, 28447273a2dbSMatthew Booth@option{tty}, 284588a946d3SGerd Hoffmann@option{parallel}, 2846cbcc6336SAlon Levy@option{parport}, 284716fdc56aSThomas Huth@option{spicevmc}, 28485a49d3e9SMarc-André Lureau@option{spiceport}. 28497273a2dbSMatthew BoothThe specific backend will determine the applicable options. 28507273a2dbSMatthew Booth 2851dddba068SMarkus ArmbrusterUse @code{-chardev help} to print all available chardev backend types. 2852517b3d40SLin Ma 28537273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 28547273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 28557273a2dbSMatthew Booth 285697331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2857a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2858a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2859a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2860a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2861a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2862a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2863a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2864a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2865a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2866a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2867a40db1b3SPeter Maydell 2868a40db1b3SPeter Maydell@example 2869a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2870bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2871a40db1b3SPeter Maydell-serial chardev:char0 \ 2872a40db1b3SPeter Maydell-serial chardev:char0 2873a40db1b3SPeter Maydell@end example 2874a40db1b3SPeter Maydell 2875a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2876a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2877a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2878a40db1b3SPeter Maydell 2879a40db1b3SPeter Maydell@example 2880a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2881bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2882a40db1b3SPeter Maydell-parallel chardev:char0 \ 2883a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2884a40db1b3SPeter Maydell-serial chardev:char1 \ 2885a40db1b3SPeter Maydell-serial chardev:char1 2886a40db1b3SPeter Maydell@end example 2887a40db1b3SPeter Maydell 2888a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2889a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2890a40db1b3SPeter Maydellmultiplexer}. 2891a40db1b3SPeter Maydell 2892a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2893a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2894a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2895a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2896a40db1b3SPeter Maydellstdio. 2897a40db1b3SPeter Maydell 2898a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2899a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 290097331287SJan Kiszka 2901d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2902d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2903d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2904d0d7708bSDaniel P. Berrangeopened. 2905d0d7708bSDaniel P. Berrange 2906dddba068SMarkus Armbruster@end table 29077273a2dbSMatthew Booth 2908dddba068SMarkus ArmbrusterThe available backends are: 2909dddba068SMarkus Armbruster 2910dddba068SMarkus Armbruster@table @option 29117273a2dbSMatthew Booth@item -chardev null,id=@var{id} 29127273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 29137273a2dbSMatthew Boothreceives. The null backend does not take any options. 29147273a2dbSMatthew Booth 2915fd4a5fd4SDaniel P. Berrange@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}] 29167273a2dbSMatthew Booth 29177273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 29187273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 29197273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 29207273a2dbSMatthew Booth 29217273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 29227273a2dbSMatthew Booth 29237273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 29247273a2dbSMatthew Boothconnect to a listening socket. 29257273a2dbSMatthew Booth 29267273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 29277273a2dbSMatthew Boothescape sequences. 29287273a2dbSMatthew Booth 2929981b06e7SJulia Suvorova@option{websocket} specifies that the socket uses WebSocket protocol for 2930981b06e7SJulia Suvorovacommunication. 2931981b06e7SJulia Suvorova 29325dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 29335dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 29345dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 29355dd1f02bSCorey Minyard 2936a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2937a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2938a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2939a8fb5427SDaniel P. Berrangeargument. 2940a8fb5427SDaniel P. Berrange 2941fd4a5fd4SDaniel P. Berrange@option{tls-auth} provides the ID of the QAuthZ authorization object against 2942fd4a5fd4SDaniel P. Berrangewhich the client's x509 distinguished name will be validated. This object is 2943fd4a5fd4SDaniel P. Berrangeonly resolved at time of use, so can be deleted and recreated on the fly 2944fd4a5fd4SDaniel P. Berrangewhile the chardev server is active. If missing, it will default to denying 2945fd4a5fd4SDaniel P. Berrangeaccess. 2946fd4a5fd4SDaniel P. Berrange 29477273a2dbSMatthew BoothTCP and unix socket options are given below: 29487273a2dbSMatthew Booth 29497273a2dbSMatthew Booth@table @option 29507273a2dbSMatthew Booth 29518d533561SAurelien Jarno@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 29527273a2dbSMatthew Booth 29537273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 29547273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 29557273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 29567273a2dbSMatthew Booth 29577273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 29587273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 29597273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 29607273a2dbSMatthew Booth@option{port} is required. 29617273a2dbSMatthew Booth 29627273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 29637273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 29647273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 29657273a2dbSMatthew Boothas a port number. 29667273a2dbSMatthew Booth 29677273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 29687273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 29697273a2dbSMatthew Booth 29707273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 29717273a2dbSMatthew Booth 29727273a2dbSMatthew Booth@item unix options: path=@var{path} 29737273a2dbSMatthew Booth 29747273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 29757273a2dbSMatthew Boothrequired. 29767273a2dbSMatthew Booth 29777273a2dbSMatthew Booth@end table 29787273a2dbSMatthew Booth 29797273a2dbSMatthew Booth@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 29807273a2dbSMatthew Booth 29817273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 29827273a2dbSMatthew Booth 29837273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 29847273a2dbSMatthew Boothdefaults to @code{localhost}. 29857273a2dbSMatthew Booth 29867273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 29877273a2dbSMatthew Boothis required. 29887273a2dbSMatthew Booth 29897273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 29907273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 29917273a2dbSMatthew Booth 29927273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 29937273a2dbSMatthew Boothavailable local port will be used. 29947273a2dbSMatthew Booth 29957273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 29967273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 29977273a2dbSMatthew Booth 29987273a2dbSMatthew Booth@item -chardev msmouse,id=@var{id} 29997273a2dbSMatthew Booth 30007273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 30017273a2dbSMatthew Boothtake any options. 30027273a2dbSMatthew Booth 30037273a2dbSMatthew Booth@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 30047273a2dbSMatthew Booth 30057273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 30067273a2dbSMatthew Boothsize. 30077273a2dbSMatthew Booth 30087273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 30097273a2dbSMatthew Booththe console, in pixels. 30107273a2dbSMatthew Booth 30117273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 30127273a2dbSMatthew Boothconsole with the given dimensions. 30137273a2dbSMatthew Booth 30144f57378fSMarkus Armbruster@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 301551767e7cSLei Li 30163949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 3017e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 301851767e7cSLei Li 30197273a2dbSMatthew Booth@item -chardev file,id=@var{id},path=@var{path} 30207273a2dbSMatthew Booth 30217273a2dbSMatthew BoothLog all traffic received from the guest to a file. 30227273a2dbSMatthew Booth 30237273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 30247273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 30257273a2dbSMatthew Boothis required. 30267273a2dbSMatthew Booth 30277273a2dbSMatthew Booth@item -chardev pipe,id=@var{id},path=@var{path} 30287273a2dbSMatthew Booth 30297273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 30307273a2dbSMatthew BoothWindows hosts and other hosts: 30317273a2dbSMatthew Booth 30327273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 30337273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 30347273a2dbSMatthew Booth 30357273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 30367273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 30377273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 30387273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 30397273a2dbSMatthew Boothbe present. 30407273a2dbSMatthew Booth 30417273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 30427273a2dbSMatthew Boothrequired. 30437273a2dbSMatthew Booth 30447273a2dbSMatthew Booth@item -chardev console,id=@var{id} 30457273a2dbSMatthew Booth 30467273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 30477273a2dbSMatthew Boothtake any options. 30487273a2dbSMatthew Booth 30497273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 30507273a2dbSMatthew Booth 30517273a2dbSMatthew Booth@item -chardev serial,id=@var{id},path=@option{path} 30527273a2dbSMatthew Booth 30537273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 30547273a2dbSMatthew Booth 3055d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 3056d59044efSGerd Hoffmannnot only serial lines. 30577273a2dbSMatthew Booth 30587273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 30597273a2dbSMatthew Booth 30607273a2dbSMatthew Booth@item -chardev pty,id=@var{id} 30617273a2dbSMatthew Booth 30627273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 30637273a2dbSMatthew Boothnot take any options. 30647273a2dbSMatthew Booth 30657273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 30667273a2dbSMatthew Booth 3067b7fdb3abSAurelien Jarno@item -chardev stdio,id=@var{id}[,signal=on|off] 3068b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 3069b7fdb3abSAurelien Jarno 3070b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 3071b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 3072b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 3073b7fdb3abSAurelien Jarno 30747273a2dbSMatthew Booth@item -chardev braille,id=@var{id} 30757273a2dbSMatthew Booth 30767273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 30777273a2dbSMatthew Booth 30787273a2dbSMatthew Booth@item -chardev tty,id=@var{id},path=@var{path} 30797273a2dbSMatthew Booth 30807273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 3081d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 30827273a2dbSMatthew Booth 30837273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 30847273a2dbSMatthew Booth 308588a946d3SGerd Hoffmann@item -chardev parallel,id=@var{id},path=@var{path} 3086f9cfd655SMarkus Armbruster@itemx -chardev parport,id=@var{id},path=@var{path} 30877273a2dbSMatthew Booth 308888a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 30897273a2dbSMatthew Booth 30907273a2dbSMatthew BoothConnect to a local parallel port. 30917273a2dbSMatthew Booth 30927273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 30937273a2dbSMatthew Boothrequired. 30947273a2dbSMatthew Booth 3095cbcc6336SAlon Levy@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 3096cbcc6336SAlon Levy 30973a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 30983a846906SStefan Hajnoczi 3099cbcc6336SAlon Levy@option{debug} debug level for spicevmc 3100cbcc6336SAlon Levy 3101cbcc6336SAlon Levy@option{name} name of spice channel to connect to 3102cbcc6336SAlon Levy 3103cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 3104cbcc6336SAlon Levy 31055a49d3e9SMarc-André Lureau@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 31065a49d3e9SMarc-André Lureau 31075a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 31085a49d3e9SMarc-André Lureau 31095a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 31105a49d3e9SMarc-André Lureau 31115a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 31125a49d3e9SMarc-André Lureau 31135a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 31145a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 31157273a2dbSMatthew BoothETEXI 31167273a2dbSMatthew Booth 3117c70a01e4SMarkus ArmbrusterSTEXI 3118c70a01e4SMarkus Armbruster@end table 3119c70a01e4SMarkus ArmbrusterETEXI 31207273a2dbSMatthew BoothDEFHEADING() 31217273a2dbSMatthew Booth 3122d1a0cf73SStefan Berger#ifdef CONFIG_TPM 3123de6b4f90SMarkus ArmbrusterDEFHEADING(TPM device options:) 3124d1a0cf73SStefan Berger 3125d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 312692dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 312792dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 312892dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 3129f4ede81eSAmarnath Valluri " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 3130f4ede81eSAmarnath Valluri "-tpmdev emulator,id=id,chardev=dev\n" 3131f4ede81eSAmarnath Valluri " configure the TPM device using chardev backend\n", 3132d1a0cf73SStefan Berger QEMU_ARCH_ALL) 3133d1a0cf73SStefan BergerSTEXI 3134d1a0cf73SStefan Berger 3135d1a0cf73SStefan BergerThe general form of a TPM device option is: 3136d1a0cf73SStefan Berger@table @option 3137d1a0cf73SStefan Berger 3138d1a0cf73SStefan Berger@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 3139d1a0cf73SStefan Berger@findex -tpmdev 3140d1a0cf73SStefan Berger 3141d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 314228c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 314328c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 3144d1a0cf73SStefan Berger 31452252aaf0SMarkus ArmbrusterUse @code{-tpmdev help} to print all available TPM backend types. 3146d1a0cf73SStefan Berger 31472252aaf0SMarkus Armbruster@end table 31482252aaf0SMarkus Armbruster 31492252aaf0SMarkus ArmbrusterThe available backends are: 31502252aaf0SMarkus Armbruster 31512252aaf0SMarkus Armbruster@table @option 3152d1a0cf73SStefan Berger 315392dcc234SStefan Berger@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 31544549a8b7SStefan Berger 31554549a8b7SStefan Berger(Linux-host only) Enable access to the host's TPM using the passthrough 31564549a8b7SStefan Bergerdriver. 31574549a8b7SStefan Berger 31584549a8b7SStefan Berger@option{path} specifies the path to the host's TPM device, i.e., on 31594549a8b7SStefan Bergera Linux host this would be @code{/dev/tpm0}. 31604549a8b7SStefan Berger@option{path} is optional and by default @code{/dev/tpm0} is used. 31614549a8b7SStefan Berger 316292dcc234SStefan Berger@option{cancel-path} specifies the path to the host TPM device's sysfs 316392dcc234SStefan Bergerentry allowing for cancellation of an ongoing TPM command. 316492dcc234SStefan Berger@option{cancel-path} is optional and by default QEMU will search for the 316592dcc234SStefan Bergersysfs entry to use. 316692dcc234SStefan Berger 31674549a8b7SStefan BergerSome notes about using the host's TPM with the passthrough driver: 31684549a8b7SStefan Berger 31694549a8b7SStefan BergerThe TPM device accessed by the passthrough driver must not be 31704549a8b7SStefan Bergerused by any other application on the host. 31714549a8b7SStefan Berger 31724549a8b7SStefan BergerSince the host's firmware (BIOS/UEFI) has already initialized the TPM, 31734549a8b7SStefan Bergerthe VM's firmware (BIOS/UEFI) will not be able to initialize the 31744549a8b7SStefan BergerTPM again and may therefore not show a TPM-specific menu that would 31754549a8b7SStefan Bergerotherwise allow the user to configure the TPM, e.g., allow the user to 31764549a8b7SStefan Bergerenable/disable or activate/deactivate the TPM. 31774549a8b7SStefan BergerFurther, if TPM ownership is released from within a VM then the host's TPM 31784549a8b7SStefan Bergerwill get disabled and deactivated. To enable and activate the 31794549a8b7SStefan BergerTPM again afterwards, the host has to be rebooted and the user is 31804549a8b7SStefan Bergerrequired to enter the firmware's menu to enable and activate the TPM. 31814549a8b7SStefan BergerIf the TPM is left disabled and/or deactivated most TPM commands will fail. 31824549a8b7SStefan Berger 31834549a8b7SStefan BergerTo create a passthrough TPM use the following two options: 31844549a8b7SStefan Berger@example 31854549a8b7SStefan Berger-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 31864549a8b7SStefan Berger@end example 31874549a8b7SStefan BergerNote that the @code{-tpmdev} id is @code{tpm0} and is referenced by 31884549a8b7SStefan Berger@code{tpmdev=tpm0} in the device option. 31894549a8b7SStefan Berger 3190f4ede81eSAmarnath Valluri@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 3191f4ede81eSAmarnath Valluri 3192f4ede81eSAmarnath Valluri(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 3193f4ede81eSAmarnath Vallurichardev backend. 3194f4ede81eSAmarnath Valluri 3195f4ede81eSAmarnath Valluri@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 3196f4ede81eSAmarnath Valluri 3197f4ede81eSAmarnath ValluriTo create a TPM emulator backend device with chardev socket backend: 3198f4ede81eSAmarnath Valluri@example 3199f4ede81eSAmarnath Valluri 3200f4ede81eSAmarnath Valluri-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 3201f4ede81eSAmarnath Valluri 3202f4ede81eSAmarnath Valluri@end example 3203f4ede81eSAmarnath Valluri 3204d1a0cf73SStefan BergerETEXI 3205d1a0cf73SStefan Berger 32062252aaf0SMarkus ArmbrusterSTEXI 32072252aaf0SMarkus Armbruster@end table 32082252aaf0SMarkus ArmbrusterETEXI 3209d1a0cf73SStefan BergerDEFHEADING() 3210d1a0cf73SStefan Berger 3211d1a0cf73SStefan Berger#endif 3212d1a0cf73SStefan Berger 3213de6b4f90SMarkus ArmbrusterDEFHEADING(Linux/Multiboot boot specific:) 32145824d651Sblueswir1STEXI 32157677f05dSAlexander Graf 32167677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 32177677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 32185824d651Sblueswir1for easier testing of various kernels. 32195824d651Sblueswir1 32205824d651Sblueswir1@table @option 32215824d651Sblueswir1ETEXI 32225824d651Sblueswir1 32235824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 3224ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 32255824d651Sblueswir1STEXI 32265824d651Sblueswir1@item -kernel @var{bzImage} 32276616b2adSStefan Weil@findex -kernel 32287677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 32297677f05dSAlexander Grafor in multiboot format. 32305824d651Sblueswir1ETEXI 32315824d651Sblueswir1 32325824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 3233ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 32345824d651Sblueswir1STEXI 32355824d651Sblueswir1@item -append @var{cmdline} 32366616b2adSStefan Weil@findex -append 32375824d651Sblueswir1Use @var{cmdline} as kernel command line 32385824d651Sblueswir1ETEXI 32395824d651Sblueswir1 32405824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 3241ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 32425824d651Sblueswir1STEXI 32435824d651Sblueswir1@item -initrd @var{file} 32446616b2adSStefan Weil@findex -initrd 32455824d651Sblueswir1Use @var{file} as initial ram disk. 32467677f05dSAlexander Graf 32477677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 32487677f05dSAlexander Graf 32497677f05dSAlexander GrafThis syntax is only available with multiboot. 32507677f05dSAlexander Graf 32517677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 32527677f05dSAlexander Graffirst module. 32535824d651Sblueswir1ETEXI 32545824d651Sblueswir1 3255412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 3256379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 3257412beee6SGrant LikelySTEXI 3258412beee6SGrant Likely@item -dtb @var{file} 3259412beee6SGrant Likely@findex -dtb 3260412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 3261412beee6SGrant Likelyon boot. 3262412beee6SGrant LikelyETEXI 3263412beee6SGrant Likely 32645824d651Sblueswir1STEXI 32655824d651Sblueswir1@end table 32665824d651Sblueswir1ETEXI 32675824d651Sblueswir1DEFHEADING() 32685824d651Sblueswir1 3269de6b4f90SMarkus ArmbrusterDEFHEADING(Debug/Expert options:) 32705824d651Sblueswir1STEXI 32715824d651Sblueswir1@table @option 32725824d651Sblueswir1ETEXI 32735824d651Sblueswir1 327481b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 327581b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 327663d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 32776407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 327863d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 327981b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 328081b2b810SGabriel L. SomloSTEXI 328163d3145aSMarkus Armbruster 328281b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 328381b2b810SGabriel L. Somlo@findex -fw_cfg 328463d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 32856407d76eSGabriel L. Somlo 32866407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 328763d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 328863d3145aSMarkus Armbruster 328963d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 329063d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 329163d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 329263d3145aSMarkus Armbruster 329363d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 329463d3145aSMarkus Armbruster 329563d3145aSMarkus ArmbrusterExample: 329663d3145aSMarkus Armbruster@example 329763d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 329863d3145aSMarkus Armbruster@end example 329963d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 330063d3145aSMarkus Armbrusterfrom ./my_blob.bin. 330163d3145aSMarkus Armbruster 330281b2b810SGabriel L. SomloETEXI 330381b2b810SGabriel L. Somlo 33045824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3305ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 3306ad96090aSBlue Swirl QEMU_ARCH_ALL) 33075824d651Sblueswir1STEXI 33085824d651Sblueswir1@item -serial @var{dev} 33096616b2adSStefan Weil@findex -serial 33105824d651Sblueswir1Redirect the virtual serial port to host character device 33115824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 33125824d651Sblueswir1@code{stdio} in non graphical mode. 33135824d651Sblueswir1 33145824d651Sblueswir1This option can be used several times to simulate up to 4 serial 33155824d651Sblueswir1ports. 33165824d651Sblueswir1 33175824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 33185824d651Sblueswir1 33195824d651Sblueswir1Available character devices are: 3320b3f046c2SKevin Wolf@table @option 33214e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 33225824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 33235824d651Sblueswir1@example 33245824d651Sblueswir1vc:800x600 33255824d651Sblueswir1@end example 33265824d651Sblueswir1It is also possible to specify width or height in characters: 33275824d651Sblueswir1@example 33285824d651Sblueswir1vc:80Cx24C 33295824d651Sblueswir1@end example 33305824d651Sblueswir1@item pty 33315824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 33325824d651Sblueswir1@item none 33335824d651Sblueswir1No device is allocated. 33345824d651Sblueswir1@item null 33355824d651Sblueswir1void device 333688e020e5SIngo van Lil@item chardev:@var{id} 333788e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 33385824d651Sblueswir1@item /dev/XXX 33395824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 33405824d651Sblueswir1parameters are set according to the emulated ones. 33415824d651Sblueswir1@item /dev/parport@var{N} 33425824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 33435824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 33445824d651Sblueswir1@item file:@var{filename} 33455824d651Sblueswir1Write output to @var{filename}. No character can be read. 33465824d651Sblueswir1@item stdio 33475824d651Sblueswir1[Unix only] standard input/output 33485824d651Sblueswir1@item pipe:@var{filename} 33495824d651Sblueswir1name pipe @var{filename} 33505824d651Sblueswir1@item COM@var{n} 33515824d651Sblueswir1[Windows only] Use host serial port @var{n} 33525824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 33535824d651Sblueswir1This implements UDP Net Console. 33545824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 33555824d651Sblueswir1they default to @code{0.0.0.0}. 33565824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 33575824d651Sblueswir1 33585824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3359b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3360b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 33615824d651Sblueswir1will appear in the netconsole session. 33625824d651Sblueswir1 33635824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3364b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 33655824d651Sblueswir1source port each time by using something like @code{-serial 3366b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 33675824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 33685824d651Sblueswir1characters via udp. If you have a patched version of netcat which 33695824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3370bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3371b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 33725824d651Sblueswir1@table @code 3373071c9394SStefan Weil@item QEMU Options: 33745824d651Sblueswir1-serial udp::4555@@:4556 33755824d651Sblueswir1@item netcat options: 33765824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 33775824d651Sblueswir1@item telnet options: 33785824d651Sblueswir1localhost 5555 33795824d651Sblueswir1@end table 33805824d651Sblueswir1 33815dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 33825824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 33835824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 33845824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 33855824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 33865824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 33875824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 33885dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 33895dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 33905dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 33915824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 33925824d651Sblueswir1connect to the corresponding character device. 33935824d651Sblueswir1@table @code 33945824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 33955824d651Sblueswir1-serial tcp:192.168.0.2:4444 33965824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 33975824d651Sblueswir1-serial tcp::4444,server 33985824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 33995824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 34005824d651Sblueswir1@end table 34015824d651Sblueswir1 34025824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 34035824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 34045824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 34055824d651Sblueswir1difference is that the port acts like a telnet server or client using 34065824d651Sblueswir1telnet option negotiation. This will also allow you to send the 34075824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 34085824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 34095824d651Sblueswir1type "send break" followed by pressing the enter key. 34105824d651Sblueswir1 3411981b06e7SJulia Suvorova@item websocket:@var{host}:@var{port},server[,nowait][,nodelay] 3412981b06e7SJulia SuvorovaThe WebSocket protocol is used instead of raw tcp socket. The port acts as 3413981b06e7SJulia Suvorovaa WebSocket server. Client mode is not supported. 3414981b06e7SJulia Suvorova 34155dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 34165824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 34175824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 34185824d651Sblueswir1@var{path} is used for connections. 34195824d651Sblueswir1 34205824d651Sblueswir1@item mon:@var{dev_string} 34215824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 34225824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 342302c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 34245824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 34255824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 34265824d651Sblueswir1listening on port 4444 would be: 34275824d651Sblueswir1@table @code 34285824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 34295824d651Sblueswir1@end table 3430be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 343102c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 34325824d651Sblueswir1 34335824d651Sblueswir1@item braille 34345824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 34355824d651Sblueswir1or fake device. 34365824d651Sblueswir1 3437be8b28a9SKevin Wolf@item msmouse 3438be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 34395824d651Sblueswir1@end table 34405824d651Sblueswir1ETEXI 34415824d651Sblueswir1 34425824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3443ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3444ad96090aSBlue Swirl QEMU_ARCH_ALL) 34455824d651Sblueswir1STEXI 34465824d651Sblueswir1@item -parallel @var{dev} 34476616b2adSStefan Weil@findex -parallel 34485824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 34495824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 34505824d651Sblueswir1be used to use hardware devices connected on the corresponding host 34515824d651Sblueswir1parallel port. 34525824d651Sblueswir1 34535824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 34545824d651Sblueswir1ports. 34555824d651Sblueswir1 34565824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 34575824d651Sblueswir1ETEXI 34585824d651Sblueswir1 34595824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3460ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3461ad96090aSBlue Swirl QEMU_ARCH_ALL) 34625824d651Sblueswir1STEXI 34634e307fc8SGerd Hoffmann@item -monitor @var{dev} 34646616b2adSStefan Weil@findex -monitor 34655824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 34665824d651Sblueswir1serial port). 34675824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 34685824d651Sblueswir1non graphical mode. 346970e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 34705824d651Sblueswir1ETEXI 34716ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3472ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3473ad96090aSBlue Swirl QEMU_ARCH_ALL) 347495d5f08bSStefan WeilSTEXI 347595d5f08bSStefan Weil@item -qmp @var{dev} 34766616b2adSStefan Weil@findex -qmp 347795d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 347895d5f08bSStefan WeilETEXI 34794821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 34804821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 34814821cd4cSMax Reitz QEMU_ARCH_ALL) 34824821cd4cSMax ReitzSTEXI 34834821cd4cSMax Reitz@item -qmp-pretty @var{dev} 34844821cd4cSMax Reitz@findex -qmp-pretty 34854821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 34864821cd4cSMax ReitzETEXI 34875824d651Sblueswir1 348822a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3489ef670726SVicente Jimenez Aguilar "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 349022a0e04bSGerd HoffmannSTEXI 3491ef670726SVicente Jimenez Aguilar@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 34926616b2adSStefan Weil@findex -mon 3493ef670726SVicente Jimenez AguilarSetup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 3494ef670726SVicente Jimenez Aguilareasing human reading and debugging. 349522a0e04bSGerd HoffmannETEXI 349622a0e04bSGerd Hoffmann 3497c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3498ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3499ad96090aSBlue Swirl QEMU_ARCH_ALL) 3500c9f398e5SH. Peter AnvinSTEXI 3501c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 35026616b2adSStefan Weil@findex -debugcon 3503c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3504c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3505c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3506c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3507c9f398e5SH. Peter Anvinnon graphical mode. 3508c9f398e5SH. Peter AnvinETEXI 3509c9f398e5SH. Peter Anvin 35105824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3511ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 35125824d651Sblueswir1STEXI 35135824d651Sblueswir1@item -pidfile @var{file} 35146616b2adSStefan Weil@findex -pidfile 35155824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 35165824d651Sblueswir1from a script. 35175824d651Sblueswir1ETEXI 35185824d651Sblueswir1 35191b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3520ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 35211b530a6dSaurel32STEXI 35221b530a6dSaurel32@item -singlestep 35236616b2adSStefan Weil@findex -singlestep 35241b530a6dSaurel32Run the emulation in single step mode. 35251b530a6dSaurel32ETEXI 35261b530a6dSaurel32 3527047f7038SIgor MammedovDEF("preconfig", 0, QEMU_OPTION_preconfig, \ 3528361ac948SMarkus Armbruster "--preconfig pause QEMU before machine is initialized (experimental)\n", 3529047f7038SIgor Mammedov QEMU_ARCH_ALL) 3530047f7038SIgor MammedovSTEXI 3531047f7038SIgor Mammedov@item --preconfig 3532047f7038SIgor Mammedov@findex --preconfig 3533047f7038SIgor MammedovPause QEMU for interactive configuration before the machine is created, 3534047f7038SIgor Mammedovwhich allows querying and configuring properties that will affect 3535361ac948SMarkus Armbrustermachine initialization. Use QMP command 'x-exit-preconfig' to exit 3536361ac948SMarkus Armbrusterthe preconfig state and move to the next state (i.e. run guest if -S 3537361ac948SMarkus Armbrusterisn't used or pause the second time if -S is used). This option is 3538361ac948SMarkus Armbrusterexperimental. 3539047f7038SIgor MammedovETEXI 3540047f7038SIgor Mammedov 35415824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3542ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3543ad96090aSBlue Swirl QEMU_ARCH_ALL) 35445824d651Sblueswir1STEXI 35455824d651Sblueswir1@item -S 35466616b2adSStefan Weil@findex -S 35475824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 35485824d651Sblueswir1ETEXI 35495824d651Sblueswir1 3550888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3551888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3552888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3553888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3554888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3555888a6bc6SSatoru MoriyaSTEXI 3556888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3557888a6bc6SSatoru Moriya@findex -realtime 3558888a6bc6SSatoru MoriyaRun qemu with realtime features. 3559888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3560888a6bc6SSatoru Moriya(enabled by default). 3561888a6bc6SSatoru MoriyaETEXI 3562888a6bc6SSatoru Moriya 35636f131f13SMichael S. TsirkinDEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, 3564dfaa7d50SBALATON Zoltan "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" 35656f131f13SMichael S. Tsirkin " run qemu with overcommit hints\n" 35666f131f13SMichael S. Tsirkin " mem-lock=on|off controls memory lock support (default: off)\n" 35676f131f13SMichael S. Tsirkin " cpu-pm=on|off controls cpu power management (default: off)\n", 35686f131f13SMichael S. Tsirkin QEMU_ARCH_ALL) 35696f131f13SMichael S. TsirkinSTEXI 35706f131f13SMichael S. Tsirkin@item -overcommit mem-lock=on|off 35716f131f13SMichael S. Tsirkin@item -overcommit cpu-pm=on|off 35726f131f13SMichael S. Tsirkin@findex -overcommit 35736f131f13SMichael S. TsirkinRun qemu with hints about host resource overcommit. The default is 35746f131f13SMichael S. Tsirkinto assume that host overcommits all resources. 35756f131f13SMichael S. Tsirkin 35766f131f13SMichael S. TsirkinLocking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled 35776f131f13SMichael S. Tsirkinby default). This works when host memory is not overcommitted and reduces the 35786f131f13SMichael S. Tsirkinworst-case latency for guest. This is equivalent to @option{realtime}. 35796f131f13SMichael S. Tsirkin 35806f131f13SMichael S. TsirkinGuest ability to manage power state of host cpus (increasing latency for other 35816f131f13SMichael S. Tsirkinprocesses on the same host cpu, but decreasing latency for guest) can be 35826f131f13SMichael S. Tsirkinenabled via @option{cpu-pm=on} (disabled by default). This works best when 35836f131f13SMichael S. Tsirkinhost CPU is not overcommitted. When used, host estimates of CPU cycle and power 35846f131f13SMichael S. Tsirkinutilization will be incorrect, not taking into account guest idle time. 35856f131f13SMichael S. TsirkinETEXI 35866f131f13SMichael S. Tsirkin 358759030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3588ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 35895824d651Sblueswir1STEXI 359059030a8cSaliguori@item -gdb @var{dev} 35916616b2adSStefan Weil@findex -gdb 359259030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 359359030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3594b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 359559030a8cSaliguoriwithin gdb and establish the connection via a pipe: 359659030a8cSaliguori@example 3597664785acSThomas Huth(gdb) target remote | exec @value{qemu_system} -gdb stdio ... 359859030a8cSaliguori@end example 35995824d651Sblueswir1ETEXI 36005824d651Sblueswir1 360159030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3602ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3603ad96090aSBlue Swirl QEMU_ARCH_ALL) 36045824d651Sblueswir1STEXI 360559030a8cSaliguori@item -s 36066616b2adSStefan Weil@findex -s 360759030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 360859030a8cSaliguori(@pxref{gdb_usage}). 36095824d651Sblueswir1ETEXI 36105824d651Sblueswir1 36115824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3612989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3613ad96090aSBlue Swirl QEMU_ARCH_ALL) 36145824d651Sblueswir1STEXI 3615989b697dSPeter Maydell@item -d @var{item1}[,...] 36166616b2adSStefan Weil@findex -d 3617989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 36185824d651Sblueswir1ETEXI 36195824d651Sblueswir1 3620c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3621989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3622c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3623c235d738SMatthew FernandezSTEXI 36248bd383b4SStefan Weil@item -D @var{logfile} 3625c235d738SMatthew Fernandez@findex -D 3626989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3627c235d738SMatthew FernandezETEXI 3628c235d738SMatthew Fernandez 36293514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 36303514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 36313514552eSAlex Bennée QEMU_ARCH_ALL) 36323514552eSAlex BennéeSTEXI 36333514552eSAlex Bennée@item -dfilter @var{range1}[,...] 36343514552eSAlex Bennée@findex -dfilter 36353514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 36363514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 36373514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 36383514552eSAlex Bennéeaddresses and sizes required. For example: 36393514552eSAlex Bennée@example 36403514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 36413514552eSAlex Bennée@end example 36423514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 36433514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 36443514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 36453514552eSAlex BennéeETEXI 36463514552eSAlex Bennée 36479c09a251SRichard HendersonDEF("seed", HAS_ARG, QEMU_OPTION_seed, \ 36489c09a251SRichard Henderson "-seed number seed the pseudo-random number generator\n", 36499c09a251SRichard Henderson QEMU_ARCH_ALL) 36509c09a251SRichard HendersonSTEXI 36519c09a251SRichard Henderson@item -seed @var{number} 36529c09a251SRichard Henderson@findex -seed 36539c09a251SRichard HendersonForce the guest to use a deterministic pseudo-random number generator, seeded 36549c09a251SRichard Hendersonwith @var{number}. This does not affect crypto routines within the host. 36559c09a251SRichard HendersonETEXI 36569c09a251SRichard Henderson 36575824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3658ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3659ad96090aSBlue Swirl QEMU_ARCH_ALL) 36605824d651Sblueswir1STEXI 36615824d651Sblueswir1@item -L @var{path} 36626616b2adSStefan Weil@findex -L 36635824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 366437146e7eSRichard W.M. Jones 366537146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 36665824d651Sblueswir1ETEXI 36675824d651Sblueswir1 36685824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3669ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 36705824d651Sblueswir1STEXI 36715824d651Sblueswir1@item -bios @var{file} 36726616b2adSStefan Weil@findex -bios 36735824d651Sblueswir1Set the filename for the BIOS. 36745824d651Sblueswir1ETEXI 36755824d651Sblueswir1 36765824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3677ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 36785824d651Sblueswir1STEXI 36795824d651Sblueswir1@item -enable-kvm 36806616b2adSStefan Weil@findex -enable-kvm 36815824d651Sblueswir1Enable KVM full virtualization support. This option is only available 36825824d651Sblueswir1if KVM support is enabled when compiling. 36835824d651Sblueswir1ETEXI 36845824d651Sblueswir1 3685e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3686ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3687e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3688e37630caSaliguori "-xen-attach attach to existing xen domain\n" 36891077bcacSAnthony PERARD " libxl will use this when starting QEMU\n", 3690ad96090aSBlue Swirl QEMU_ARCH_ALL) 36911c599472SPaul DurrantDEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 36921c599472SPaul Durrant "-xen-domid-restrict restrict set of available xen operations\n" 36931c599472SPaul Durrant " to specified domain id. (Does not affect\n" 36941c599472SPaul Durrant " xenpv machine type).\n", 36951c599472SPaul Durrant QEMU_ARCH_ALL) 369695d5f08bSStefan WeilSTEXI 369795d5f08bSStefan Weil@item -xen-domid @var{id} 36986616b2adSStefan Weil@findex -xen-domid 369995d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 370095d5f08bSStefan Weil@item -xen-attach 37016616b2adSStefan Weil@findex -xen-attach 370295d5f08bSStefan WeilAttach to existing xen domain. 37031077bcacSAnthony PERARDlibxl will use this when starting QEMU (XEN only). 37041c599472SPaul Durrant@findex -xen-domid-restrict 37051c599472SPaul DurrantRestrict set of available xen operations to specified domain id (XEN only). 370695d5f08bSStefan WeilETEXI 3707e37630caSaliguori 37085824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3709ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 37105824d651Sblueswir1STEXI 37115824d651Sblueswir1@item -no-reboot 37126616b2adSStefan Weil@findex -no-reboot 37135824d651Sblueswir1Exit instead of rebooting. 37145824d651Sblueswir1ETEXI 37155824d651Sblueswir1 37165824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3717ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 37185824d651Sblueswir1STEXI 37195824d651Sblueswir1@item -no-shutdown 37206616b2adSStefan Weil@findex -no-shutdown 37215824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 37225824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 37235824d651Sblueswir1disk image. 37245824d651Sblueswir1ETEXI 37255824d651Sblueswir1 37265824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 37275824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3728ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3729ad96090aSBlue Swirl QEMU_ARCH_ALL) 37305824d651Sblueswir1STEXI 37315824d651Sblueswir1@item -loadvm @var{file} 37326616b2adSStefan Weil@findex -loadvm 37335824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 37345824d651Sblueswir1ETEXI 37355824d651Sblueswir1 37365824d651Sblueswir1#ifndef _WIN32 37375824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3738ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 37395824d651Sblueswir1#endif 37405824d651Sblueswir1STEXI 37415824d651Sblueswir1@item -daemonize 37426616b2adSStefan Weil@findex -daemonize 37435824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 37445824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 37455824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 37465824d651Sblueswir1to cope with initialization race conditions. 37475824d651Sblueswir1ETEXI 37485824d651Sblueswir1 37495824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3750ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3751ad96090aSBlue Swirl QEMU_ARCH_ALL) 37525824d651Sblueswir1STEXI 37535824d651Sblueswir1@item -option-rom @var{file} 37546616b2adSStefan Weil@findex -option-rom 37555824d651Sblueswir1Load the contents of @var{file} as an option ROM. 37565824d651Sblueswir1This option is useful to load things like EtherBoot. 37575824d651Sblueswir1ETEXI 37585824d651Sblueswir1 37591ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 3760238d1240SArtem Pisarenko "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3761ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3762ad96090aSBlue Swirl QEMU_ARCH_ALL) 37631ed2fc1fSJan Kiszka 37645824d651Sblueswir1STEXI 37655824d651Sblueswir1 3766238d1240SArtem Pisarenko@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew] 37676616b2adSStefan Weil@findex -rtc 37681ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 37691ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 3770238d1240SArtem PisarenkoMS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the 37711ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 37721ed2fc1fSJan Kiszka 37739d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 37746875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 37756875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 377678808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 3777238d1240SArtem Pisarenkoto @code{rt} instead, which provides a host monotonic clock if host support it. 3778238d1240SArtem PisarenkoTo even prevent the RTC from progressing during suspension, you can set @option{clock} 3779238d1240SArtem Pisarenkoto @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in 3780238d1240SArtem Pisarenkoicount mode in order to preserve determinism; however, note that in icount mode 3781238d1240SArtem Pisarenkothe speed of the virtual clock is variable and can in general differ from the 3782238d1240SArtem Pisarenkohost clock. 37836875204cSJan Kiszka 37841ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 37851ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 37861ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 37871ed2fc1fSJan Kiszkare-inject them. 37885824d651Sblueswir1ETEXI 37895824d651Sblueswir1 37905824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 37919c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3792bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3793f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3794f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 37955824d651Sblueswir1STEXI 37969c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 37976616b2adSStefan Weil@findex -icount 37985824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 37994e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 38005824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 38015824d651Sblueswir1time within a few seconds of real time. 38025824d651Sblueswir1 3803f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3804778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3805778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3806f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3807f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3808f1f4b57eSVictor CLEMENTthe guest point of view. 3809f1f4b57eSVictor CLEMENT 38105824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 38115824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 38125824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 38135824d651Sblueswir1executed often has little or no correlation with actual performance. 3814a8bfac37SSebastian Tanase 3815b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3816a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3817a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3818a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 381982597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3820a8bfac37SSebastian Tanaseto inform about the delay. 3821a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3822a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3823a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3824a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 38254c27b859SPavel Dovgalyuk 38264c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 38274c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 38284c27b859SPavel Dovgalyukread from this file in replay mode. 38299c2037d0SPavel Dovgalyuk 38309c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 38319c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 38329c2037d0SPavel Dovgalyukto load the initial VM state. 38335824d651Sblueswir1ETEXI 38345824d651Sblueswir1 38359dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3836d7933ef3SXu Wang "-watchdog model\n" \ 3837ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3838ad96090aSBlue Swirl QEMU_ARCH_ALL) 38399dd986ccSRichard W.M. JonesSTEXI 38409dd986ccSRichard W.M. Jones@item -watchdog @var{model} 38416616b2adSStefan Weil@findex -watchdog 38429dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 38439dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3844d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3845d7933ef3SXu Wangwhich your guest has drivers. 38469dd986ccSRichard W.M. Jones 3847d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3848d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 38499dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3850d7933ef3SXu Wang 3851d7933ef3SXu WangThe following models may be available: 3852d7933ef3SXu Wang@table @option 3853d7933ef3SXu Wang@item ib700 3854d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3855d7933ef3SXu Wang@item i6300esb 3856d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3857d7933ef3SXu Wangdual-timer watchdog. 3858188f24c2SXu Wang@item diag288 3859188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3860188f24c2SXu Wang(currently KVM only). 3861d7933ef3SXu Wang@end table 38629dd986ccSRichard W.M. JonesETEXI 38639dd986ccSRichard W.M. Jones 38649dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 38657ad9270eSMarkus Armbruster "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 3866ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3867ad96090aSBlue Swirl QEMU_ARCH_ALL) 38689dd986ccSRichard W.M. JonesSTEXI 38699dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3870b8f490ebSMarkus Armbruster@findex -watchdog-action 38719dd986ccSRichard W.M. Jones 38729dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 38739dd986ccSRichard W.M. Jonesexpires. 38749dd986ccSRichard W.M. JonesThe default is 38759dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 38769dd986ccSRichard W.M. JonesOther possible actions are: 38779dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 38789dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 38797ad9270eSMarkus Armbruster@code{inject-nmi} (inject a NMI into the guest), 38809dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 38819dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 38829dd986ccSRichard W.M. Jones@code{none} (do nothing). 38839dd986ccSRichard W.M. Jones 38849dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 38859dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 38869dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 38879dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 38889dd986ccSRichard W.M. Jones 38899dd986ccSRichard W.M. JonesExamples: 38909dd986ccSRichard W.M. Jones 38919dd986ccSRichard W.M. Jones@table @code 38929dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3893f9cfd655SMarkus Armbruster@itemx -watchdog ib700 38949dd986ccSRichard W.M. Jones@end table 38959dd986ccSRichard W.M. JonesETEXI 38969dd986ccSRichard W.M. Jones 38975824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3898ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3899ad96090aSBlue Swirl QEMU_ARCH_ALL) 39005824d651Sblueswir1STEXI 39015824d651Sblueswir1 39024e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 39036616b2adSStefan Weil@findex -echr 39045824d651Sblueswir1Change the escape character used for switching to the monitor when using 39055824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 39065824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 39075824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 39085824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 39095824d651Sblueswir1instance you could use the either of the following to change the escape 39105824d651Sblueswir1character to Control-t. 39115824d651Sblueswir1@table @code 39125824d651Sblueswir1@item -echr 0x14 3913f9cfd655SMarkus Armbruster@itemx -echr 20 39145824d651Sblueswir1@end table 39155824d651Sblueswir1ETEXI 39165824d651Sblueswir1 39175824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3918ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 39195824d651Sblueswir1STEXI 392095d5f08bSStefan Weil@item -show-cursor 39216616b2adSStefan Weil@findex -show-cursor 392295d5f08bSStefan WeilShow cursor. 39235824d651Sblueswir1ETEXI 39245824d651Sblueswir1 39255824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3926ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 39275824d651Sblueswir1STEXI 392895d5f08bSStefan Weil@item -tb-size @var{n} 39296616b2adSStefan Weil@findex -tb-size 3930fe174132SPaolo BonziniSet TCG translation block cache size. Deprecated, use @samp{-accel tcg,tb-size=@var{n}} 3931fe174132SPaolo Bonziniinstead. 39325824d651Sblueswir1ETEXI 39335824d651Sblueswir1 39345824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 39357c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 39367c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 39377c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 39387c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 39397c601803SMichael Tokarev " specified protocol and socket address\n" \ 39407c601803SMichael Tokarev "-incoming fd:fd\n" \ 39417c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 39427c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 39431597051bSDr. David Alan Gilbert " or from given external command\n" \ 39441597051bSDr. David Alan Gilbert "-incoming defer\n" \ 39451597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3946ad96090aSBlue Swirl QEMU_ARCH_ALL) 39475824d651Sblueswir1STEXI 39487c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3949f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 39506616b2adSStefan Weil@findex -incoming 39517c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 39527c601803SMichael Tokarev 39537c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 39547c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 39557c601803SMichael Tokarev 39567c601803SMichael Tokarev@item -incoming fd:@var{fd} 39577c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 39587c601803SMichael Tokarev 39597c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 39607c601803SMichael TokarevAccept incoming migration as an output from specified external command. 39611597051bSDr. David Alan Gilbert 39621597051bSDr. David Alan Gilbert@item -incoming defer 39631597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 39641597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 39651597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 39665824d651Sblueswir1ETEXI 39675824d651Sblueswir1 3968d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 3969d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 3970d15c05fcSAshijeet AcharyaSTEXI 3971d15c05fcSAshijeet Acharya@item -only-migratable 3972d15c05fcSAshijeet Acharya@findex -only-migratable 3973d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 3974d15c05fcSAshijeet Acharyaunmigratable state. 3975d15c05fcSAshijeet AcharyaETEXI 3976d15c05fcSAshijeet Acharya 3977d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3978ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3979d8c208ddSGerd HoffmannSTEXI 39803dbf2c7fSStefan Weil@item -nodefaults 39816616b2adSStefan Weil@findex -nodefaults 398266c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 398366c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 398466c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 398566c19bf1SMichal Novotnydefault devices. 3986d8c208ddSGerd HoffmannETEXI 3987d8c208ddSGerd Hoffmann 39885824d651Sblueswir1#ifndef _WIN32 39895824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3990ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3991ad96090aSBlue Swirl QEMU_ARCH_ALL) 39925824d651Sblueswir1#endif 39935824d651Sblueswir1STEXI 39944e257e5eSKevin Wolf@item -chroot @var{dir} 39956616b2adSStefan Weil@findex -chroot 39965824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 39975824d651Sblueswir1directory. Especially useful in combination with -runas. 39985824d651Sblueswir1ETEXI 39995824d651Sblueswir1 40005824d651Sblueswir1#ifndef _WIN32 40015824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 40022c42f1e8SIan Jackson "-runas user change to user id user just before starting the VM\n" \ 40032c42f1e8SIan Jackson " user can be numeric uid:gid instead\n", 4004ad96090aSBlue Swirl QEMU_ARCH_ALL) 40055824d651Sblueswir1#endif 40065824d651Sblueswir1STEXI 40074e257e5eSKevin Wolf@item -runas @var{user} 40086616b2adSStefan Weil@findex -runas 40095824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 40105824d651Sblueswir1to the specified user. 40115824d651Sblueswir1ETEXI 40125824d651Sblueswir1 40135824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 40145824d651Sblueswir1 "-prom-env variable=value\n" 4015ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 4016ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 401795d5f08bSStefan WeilSTEXI 401895d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 40196616b2adSStefan Weil@findex -prom-env 402095d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 402195d5f08bSStefan WeilETEXI 40225824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 4023f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 40243b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 4025413a99a9SSandra Loosemore QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 402695d5f08bSStefan WeilSTEXI 402795d5f08bSStefan Weil@item -semihosting 40286616b2adSStefan Weil@findex -semihosting 4029413a99a9SSandra LoosemoreEnable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only). 4030a38bb079SLiviu IonescuETEXI 4031a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 40324e7f9032SAlex Bennée "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \ 4033a59d31a1SLeon Alrae " semihosting configuration\n", 40343b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 4035413a99a9SSandra LoosemoreQEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 4036a38bb079SLiviu IonescuSTEXI 40374e7f9032SAlex Bennée@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]] 4038a38bb079SLiviu Ionescu@findex -semihosting-config 4039413a99a9SSandra LoosemoreEnable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only). 4040a59d31a1SLeon Alrae@table @option 4041a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 4042a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 4043a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 4044a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 40454e7f9032SAlex Bennée@item chardev=@var{str1} 40464e7f9032SAlex BennéeSend the output to a chardev backend output for native or auto output when not in gdb 4047a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 4048a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 4049a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 4050a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 4051a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 4052a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 4053a59d31a1SLeon Alrae@end table 405495d5f08bSStefan WeilETEXI 40555824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 4056ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 405795d5f08bSStefan WeilSTEXI 405895d5f08bSStefan Weil@item -old-param 40596616b2adSStefan Weil@findex -old-param (ARM) 406095d5f08bSStefan WeilOld param mode (ARM only). 406195d5f08bSStefan WeilETEXI 406295d5f08bSStefan Weil 40637d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 406473a1e647SEduardo Otubo "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 406524f8cdc5SEduardo Otubo " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 40662b716fa6SEduardo Otubo " Enable seccomp mode 2 system call filter (default 'off').\n" \ 40672b716fa6SEduardo Otubo " use 'obsolete' to allow obsolete system calls that are provided\n" \ 40682b716fa6SEduardo Otubo " by the kernel, but typically no longer used by modern\n" \ 406973a1e647SEduardo Otubo " C library implementations.\n" \ 407073a1e647SEduardo Otubo " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 407173a1e647SEduardo Otubo " its privileges by blacklisting all set*uid|gid system calls.\n" \ 407273a1e647SEduardo Otubo " The value 'children' will deny set*uid|gid system calls for\n" \ 4073995a226fSEduardo Otubo " main QEMU process but will allow forks and execves to run unprivileged\n" \ 4074995a226fSEduardo Otubo " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 407524f8cdc5SEduardo Otubo " blacklisting *fork and execve\n" \ 407624f8cdc5SEduardo Otubo " use 'resourcecontrol' to disable process affinity and schedular priority\n", 40777d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 40787d76ad4fSEduardo OtuboSTEXI 407924f8cdc5SEduardo Otubo@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 40807d76ad4fSEduardo Otubo@findex -sandbox 40817d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 40827d76ad4fSEduardo Otubodisable it. The default is 'off'. 40832b716fa6SEduardo Otubo@table @option 40842b716fa6SEduardo Otubo@item obsolete=@var{string} 40852b716fa6SEduardo OtuboEnable Obsolete system calls 408673a1e647SEduardo Otubo@item elevateprivileges=@var{string} 408773a1e647SEduardo OtuboDisable set*uid|gid system calls 4088995a226fSEduardo Otubo@item spawn=@var{string} 4089995a226fSEduardo OtuboDisable *fork and execve 409024f8cdc5SEduardo Otubo@item resourcecontrol=@var{string} 409124f8cdc5SEduardo OtuboDisable process affinity and schedular priority 40922b716fa6SEduardo Otubo@end table 40937d76ad4fSEduardo OtuboETEXI 40947d76ad4fSEduardo Otubo 4095715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 4096ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 40973dbf2c7fSStefan WeilSTEXI 40983dbf2c7fSStefan Weil@item -readconfig @var{file} 40996616b2adSStefan Weil@findex -readconfig 4100ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 4101ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 4102ed24cfacSMichal Novotnycharacter limit. 41033dbf2c7fSStefan WeilETEXI 4104715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 4105715a664aSGerd Hoffmann "-writeconfig <file>\n" 4106ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 41073dbf2c7fSStefan WeilSTEXI 41083dbf2c7fSStefan Weil@item -writeconfig @var{file} 41096616b2adSStefan Weil@findex -writeconfig 4110ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 4111ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 4112ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 41133dbf2c7fSStefan WeilETEXI 41142feac451SThomas Huth 4115f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 4116f29a5614SEduardo Habkost "-no-user-config\n" 41173478eae9SEduardo Habkost " do not load default user-provided config files at startup\n", 4118f29a5614SEduardo Habkost QEMU_ARCH_ALL) 4119f29a5614SEduardo HabkostSTEXI 4120f29a5614SEduardo Habkost@item -no-user-config 4121f29a5614SEduardo Habkost@findex -no-user-config 4122f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 41233478eae9SEduardo Habkostconfig files on @var{sysconfdir}. 4124292444cbSAnthony LiguoriETEXI 41252feac451SThomas Huth 4126ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 412710578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 412823d15e86SLluís " specify tracing options\n", 4129ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 4130ab6540d5SPrerna SaxenaSTEXI 413123d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 413223d15e86SLluísHXCOMM HX does not support conditional compilation of text. 4133e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 4134ab6540d5SPrerna Saxena@findex -trace 4135eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 4136ab6540d5SPrerna SaxenaETEXI 413742229a75SLluís VilanovaDEF("plugin", HAS_ARG, QEMU_OPTION_plugin, 413842229a75SLluís Vilanova "-plugin [file=]<file>[,arg=<string>]\n" 413942229a75SLluís Vilanova " load a plugin\n", 414042229a75SLluís Vilanova QEMU_ARCH_ALL) 414142229a75SLluís VilanovaSTEXI 414242229a75SLluís Vilanova@item -plugin file=@var{file}[,arg=@var{string}] 414342229a75SLluís Vilanova@findex -plugin 414442229a75SLluís Vilanova 414542229a75SLluís VilanovaLoad a plugin. 414642229a75SLluís Vilanova 414742229a75SLluís Vilanova@table @option 414842229a75SLluís Vilanova@item file=@var{file} 414942229a75SLluís VilanovaLoad the given plugin from a shared library file. 415042229a75SLluís Vilanova@item arg=@var{string} 415142229a75SLluís VilanovaArgument string passed to the plugin. (Can be given multiple times.) 415242229a75SLluís Vilanova@end table 415342229a75SLluís VilanovaETEXI 41543dbf2c7fSStefan Weil 415531e70d6cSMarkus ArmbrusterHXCOMM Internal use 415631e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 415731e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 4158c7f0f3b1SAnthony Liguori 41590f66998fSPaul Moore#ifdef __linux__ 41600f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 41610f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 41620f66998fSPaul Moore QEMU_ARCH_ALL) 41630f66998fSPaul Moore#endif 41640f66998fSPaul MooreSTEXI 41650f66998fSPaul Moore@item -enable-fips 41660f66998fSPaul Moore@findex -enable-fips 41670f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 41680f66998fSPaul MooreETEXI 41690f66998fSPaul Moore 4170976e8c54SThomas HuthHXCOMM Deprecated by -accel tcg 4171c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 4172a0dac021SJan Kiszka 41735e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 41745e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 41755e2ac519SSeiji Aguchi " change the format of messages\n" 41765e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 41775e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 41785e2ac519SSeiji AguchiSTEXI 41795e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 41805e2ac519SSeiji Aguchi@findex -msg 41815e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 41825e2ac519SSeiji AguchiETEXI 41835e2ac519SSeiji Aguchi 4184abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 4185abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 4186abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 4187abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 4188abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 41892382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 4190abfd9ce3SAmit Shah QEMU_ARCH_ALL) 4191abfd9ce3SAmit ShahSTEXI 4192abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 4193abfd9ce3SAmit Shah@findex -dump-vmstate 4194abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 4195abfd9ce3SAmit Shahin @var{file} 4196abfd9ce3SAmit ShahETEXI 4197abfd9ce3SAmit Shah 419812df189dSEmilio G. CotaDEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, 419912df189dSEmilio G. Cota "-enable-sync-profile\n" 420012df189dSEmilio G. Cota " enable synchronization profiling\n", 420112df189dSEmilio G. Cota QEMU_ARCH_ALL) 420212df189dSEmilio G. CotaSTEXI 420312df189dSEmilio G. Cota@item -enable-sync-profile 420412df189dSEmilio G. Cota@findex -enable-sync-profile 420512df189dSEmilio G. CotaEnable synchronization profiling. 420612df189dSEmilio G. CotaETEXI 420712df189dSEmilio G. Cota 420843f187a5SPaolo BonziniSTEXI 420943f187a5SPaolo Bonzini@end table 421043f187a5SPaolo BonziniETEXI 421143f187a5SPaolo BonziniDEFHEADING() 4212de6b4f90SMarkus Armbruster 4213de6b4f90SMarkus ArmbrusterDEFHEADING(Generic object creation:) 421443f187a5SPaolo BonziniSTEXI 421543f187a5SPaolo Bonzini@table @option 421643f187a5SPaolo BonziniETEXI 4217b9174d4fSDaniel P. Berrange 4218b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 4219b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 4220b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 4221b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 4222b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 4223b9174d4fSDaniel P. Berrange " '/objects' path.\n", 4224b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 4225b9174d4fSDaniel P. BerrangeSTEXI 4226b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 4227b9174d4fSDaniel P. Berrange@findex -object 4228b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 4229b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 4230b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 4231b9174d4fSDaniel P. Berrange'/objects' path. 4232b9174d4fSDaniel P. Berrange 4233b9174d4fSDaniel P. Berrange@table @option 4234b9174d4fSDaniel P. Berrange 423598376843SHaozhong 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} 4236b9174d4fSDaniel P. Berrange 4237b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 4238c7cddce1SStefan Hajnoczithe guest RAM with huge pages. 4239c7cddce1SStefan Hajnoczi 4240c7cddce1SStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 4241c7cddce1SStefan Hajnoczimemory region when configuring the @option{-numa} argument. 4242c7cddce1SStefan Hajnoczi 4243c7cddce1SStefan HajnocziThe @option{size} option provides the size of the memory region, and accepts 4244c7cddce1SStefan Hajnoczicommon suffixes, eg @option{500M}. 4245c7cddce1SStefan Hajnoczi 4246c7cddce1SStefan HajnocziThe @option{mem-path} provides the path to either a shared memory or huge page 4247c7cddce1SStefan Hajnoczifilesystem mount. 4248c7cddce1SStefan Hajnoczi 4249b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 4250b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 4251b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 4252c7cddce1SStefan Hajnoczi 425306329cceSMarcel ApfelbaumThe @option{share} is also required for pvrdma devices due to 425406329cceSMarcel Apfelbaumlimitations in the RDMA API provided by Linux. 425506329cceSMarcel Apfelbaum 425606329cceSMarcel ApfelbaumSetting share=on might affect the ability to configure NUMA 425706329cceSMarcel Apfelbaumbindings for the memory backend under some circumstances, see 425806329cceSMarcel ApfelbaumDocumentation/vm/numa_memory_policy.txt on the Linux kernel 425906329cceSMarcel Apfelbaumsource tree for additional details. 426006329cceSMarcel Apfelbaum 426111ae6ed8SEduardo HabkostSetting the @option{discard-data} boolean option to @var{on} 426211ae6ed8SEduardo Habkostindicates that file contents can be destroyed when QEMU exits, 426311ae6ed8SEduardo Habkostto avoid unnecessarily flushing data to the backing file. Note 426411ae6ed8SEduardo Habkostthat @option{discard-data} is only an optimization, and QEMU 426511ae6ed8SEduardo Habkostmight not discard file contents if it aborts unexpectedly or is 426611ae6ed8SEduardo Habkostterminated using SIGKILL. 4267b9174d4fSDaniel P. Berrange 4268c7cddce1SStefan HajnocziThe @option{merge} boolean option enables memory merge, also known as 4269c7cddce1SStefan HajnocziMADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 4270c7cddce1SStefan Hajnoczimemory deduplication. 4271c7cddce1SStefan Hajnoczi 4272c7cddce1SStefan HajnocziSetting the @option{dump} boolean option to @var{off} excludes the memory from 4273c7cddce1SStefan Hajnoczicore dumps. This feature is also known as MADV_DONTDUMP. 4274c7cddce1SStefan Hajnoczi 4275c7cddce1SStefan HajnocziThe @option{prealloc} boolean option enables memory preallocation. 4276c7cddce1SStefan Hajnoczi 4277c7cddce1SStefan HajnocziThe @option{host-nodes} option binds the memory range to a list of NUMA host 4278c7cddce1SStefan Hajnoczinodes. 4279c7cddce1SStefan Hajnoczi 4280c7cddce1SStefan HajnocziThe @option{policy} option sets the NUMA policy to one of the following values: 4281c7cddce1SStefan Hajnoczi 4282c7cddce1SStefan Hajnoczi@table @option 4283c7cddce1SStefan Hajnoczi@item @var{default} 4284c7cddce1SStefan Hajnoczidefault host policy 4285c7cddce1SStefan Hajnoczi 4286c7cddce1SStefan Hajnoczi@item @var{preferred} 4287c7cddce1SStefan Hajnocziprefer the given host node list for allocation 4288c7cddce1SStefan Hajnoczi 4289c7cddce1SStefan Hajnoczi@item @var{bind} 4290c7cddce1SStefan Hajnoczirestrict memory allocation to the given host node list 4291c7cddce1SStefan Hajnoczi 4292c7cddce1SStefan Hajnoczi@item @var{interleave} 4293c7cddce1SStefan Hajnocziinterleave memory allocations across the given host node list 4294c7cddce1SStefan Hajnoczi@end table 4295c7cddce1SStefan Hajnoczi 429698376843SHaozhong ZhangThe @option{align} option specifies the base address alignment when 429798376843SHaozhong ZhangQEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 429898376843SHaozhong Zhang@option{2M}. Some backend store specified by @option{mem-path} 429998376843SHaozhong Zhangrequires an alignment different than the default one used by QEMU, eg 430098376843SHaozhong Zhangthe device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 430198376843SHaozhong Zhangsuch cases, users can specify the required alignment via this option. 430298376843SHaozhong Zhang 4303a4de8552SJunyan HeThe @option{pmem} option specifies whether the backing file specified 4304a4de8552SJunyan Heby @option{mem-path} is in host persistent memory that can be accessed 4305a4de8552SJunyan Heusing the SNIA NVM programming model (e.g. Intel NVDIMM). 4306a4de8552SJunyan HeIf @option{pmem} is set to 'on', QEMU will take necessary operations to 4307a4de8552SJunyan Heguarantee the persistence of its own writes to @option{mem-path} 4308a4de8552SJunyan He(e.g. in vNVDIMM label emulation and live migration). 4309119906afSZhang YiAlso, we will map the backend-file with MAP_SYNC flag, which ensures the 4310119906afSZhang Yifile metadata is in sync for @option{mem-path} in case of host crash 4311119906afSZhang Yior a power failure. MAP_SYNC requires support from both the host kernel 4312119906afSZhang Yi(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted 4313119906afSZhang Yiwith DAX option. 4314a4de8552SJunyan He 431506329cceSMarcel 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} 4316cd19491aSStefan Hajnoczi 4317cd19491aSStefan HajnocziCreates a memory backend object, which can be used to back the guest RAM. 4318cd19491aSStefan HajnocziMemory backend objects offer more control than the @option{-m} option that is 4319cd19491aSStefan Hajnoczitraditionally used to define guest RAM. Please refer to 4320cd19491aSStefan Hajnoczi@option{memory-backend-file} for a description of the options. 4321cd19491aSStefan Hajnoczi 432236ea3979SMarc-André Lureau@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size} 4323dbb9e0f4SMarc-André Lureau 4324dbb9e0f4SMarc-André LureauCreates an anonymous memory file backend object, which allows QEMU to 4325dbb9e0f4SMarc-André Lureaushare the memory with an external process (e.g. when using 4326dbb9e0f4SMarc-André Lureauvhost-user). The memory is allocated with memfd and optional 4327dbb9e0f4SMarc-André Lureausealing. (Linux only) 4328dbb9e0f4SMarc-André Lureau 4329dbb9e0f4SMarc-André LureauThe @option{seal} option creates a sealed-file, that will block 4330dbb9e0f4SMarc-André Lureaufurther resizing the memory ('on' by default). 4331dbb9e0f4SMarc-André Lureau 4332dbb9e0f4SMarc-André LureauThe @option{hugetlb} option specify the file to be created resides in 4333dbb9e0f4SMarc-André Lureauthe hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 4334dbb9e0f4SMarc-André Lureauthe @option{hugetlb} option, the @option{hugetlbsize} option specify 4335dbb9e0f4SMarc-André Lureauthe hugetlb page size on systems that support multiple hugetlb page 4336dbb9e0f4SMarc-André Lureausizes (it must be a power of 2 value supported by the system). 4337dbb9e0f4SMarc-André Lureau 4338dbb9e0f4SMarc-André LureauIn some versions of Linux, the @option{hugetlb} option is incompatible 4339dbb9e0f4SMarc-André Lureauwith the @option{seal} option (requires at least Linux 4.16). 4340dbb9e0f4SMarc-André Lureau 4341dbb9e0f4SMarc-André LureauPlease refer to @option{memory-backend-file} for a description of the 4342dbb9e0f4SMarc-André Lureauother options. 4343dbb9e0f4SMarc-André Lureau 434436ea3979SMarc-André LureauThe @option{share} boolean option is @var{on} by default with memfd. 434536ea3979SMarc-André Lureau 43466c4e9d48SLaurent Vivier@item -object rng-builtin,id=@var{id} 43476c4e9d48SLaurent Vivier 43486c4e9d48SLaurent VivierCreates a random number generator backend which obtains entropy from 43496c4e9d48SLaurent VivierQEMU builtin functions. The @option{id} parameter is a unique ID that 43506c4e9d48SLaurent Vivierwill be used to reference this entropy backend from the @option{virtio-rng} 43510198c262SLaurent Vivierdevice. By default, the @option{virtio-rng} device uses this RNG backend. 43526c4e9d48SLaurent Vivier 4353b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4354b9174d4fSDaniel P. Berrange 4355b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4356b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 4357b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 4358b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 4359a2230bd7SKashyap Chamarthyentropy from and if omitted defaults to @option{/dev/urandom}. 4360b9174d4fSDaniel P. Berrange 4361b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4362b9174d4fSDaniel P. Berrange 4363b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4364b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 4365b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 4366b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 4367b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 4368b9174d4fSDaniel P. Berrangeto the RNG daemon. 4369b9174d4fSDaniel P. Berrange 4370e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4371e00adf6cSDaniel P. Berrange 4372e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 4373e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 4374e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 4375e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 4376e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 4377e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 4378e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 4379e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 4380e00adf6cSDaniel P. Berrange 4381e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 4382e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 4383e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 4384e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 4385e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 4386e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 4387e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 4388e00adf6cSDaniel P. Berrangeupfront and saved. 4389e00adf6cSDaniel P. Berrange 4390e1a6dc91SRichard W.M. Jones@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}] 4391e1a6dc91SRichard W.M. Jones 4392e1a6dc91SRichard W.M. JonesCreates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide 4393e1a6dc91SRichard W.M. JonesTLS support on network backends. The @option{id} parameter is a unique 4394e1a6dc91SRichard W.M. JonesID which network backends will use to access the credentials. The 4395e1a6dc91SRichard W.M. Jones@option{endpoint} is either @option{server} or @option{client} depending 4396e1a6dc91SRichard W.M. Joneson whether the QEMU network backend that uses the credentials will be 4397e1a6dc91SRichard W.M. Jonesacting as a client or as a server. For clients only, @option{username} 4398e1a6dc91SRichard W.M. Jonesis the username which will be sent to the server. If omitted 4399e1a6dc91SRichard W.M. Jonesit defaults to ``qemu''. 4400e1a6dc91SRichard W.M. Jones 4401e1a6dc91SRichard W.M. JonesThe @var{dir} parameter tells QEMU where to find the keys file. 4402e1a6dc91SRichard W.M. JonesIt is called ``@var{dir}/keys.psk'' and contains ``username:key'' 4403e1a6dc91SRichard W.M. Jonespairs. This file can most easily be created using the GnuTLS 4404e1a6dc91SRichard W.M. Jones@code{psktool} program. 4405e1a6dc91SRichard W.M. Jones 4406e1a6dc91SRichard W.M. JonesFor server endpoints, @var{dir} may also contain a file 4407e1a6dc91SRichard W.M. Jones@var{dh-params.pem} providing diffie-hellman parameters to use 4408e1a6dc91SRichard W.M. Jonesfor the TLS server. If the file is missing, QEMU will generate 4409e1a6dc91SRichard W.M. Jonesa set of DH parameters at startup. This is a computationally 4410e1a6dc91SRichard W.M. Jonesexpensive operation that consumes random pool entropy, so it is 4411e1a6dc91SRichard W.M. Jonesrecommended that a persistent set of parameters be generated 4412e1a6dc91SRichard W.M. Jonesup front and saved. 4413e1a6dc91SRichard W.M. Jones 441400e5e9dfSChristophe 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} 441585bcbc78SDaniel P. Berrange 441685bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 441785bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 441885bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 441985bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 442085bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 442185bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 442285bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 442385bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 442485bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 442585bcbc78SDaniel P. Berrange 442685bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 442785bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 442885bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 442985bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 443085bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 443185bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 443285bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 443385bcbc78SDaniel P. Berrangeupfront and saved. 443485bcbc78SDaniel P. Berrange 443585bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 443685bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 443785bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 443885bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 443985bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 444085bcbc78SDaniel P. Berrange 44411d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 44421d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 44431d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 44441d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 44451d7b5b4aSDaniel P. Berrangepassword for decryption. 44461d7b5b4aSDaniel P. Berrange 444700e5e9dfSChristophe FergeauThe @var{priority} parameter allows to override the global default 444800e5e9dfSChristophe Fergeaupriority used by gnutls. This can be useful if the system administrator 444900e5e9dfSChristophe Fergeauneeds to use a weaker set of crypto priorities for QEMU without 445000e5e9dfSChristophe Fergeaupotentially forcing the weakness onto all applications. Or conversely 445100e5e9dfSChristophe Fergeauif one wants wants a stronger default for QEMU than for all other 445200e5e9dfSChristophe Fergeauapplications, they can do this through this parameter. Its format is 445300e5e9dfSChristophe Fergeaua gnutls priority string as described at 445400e5e9dfSChristophe Fergeau@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 445500e5e9dfSChristophe Fergeau 4456338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 44577dbb11c8SYang Hongyang 44587dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 44597dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 44607dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 4461338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 4462338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 44637dbb11c8SYang Hongyang 44647dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 44657dbb11c8SYang Hongyang 44667dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 44677dbb11c8SYang Hongyang queue of the netdev (default). 44687dbb11c8SYang Hongyang 44697dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 44707dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 44717dbb11c8SYang Hongyang 44727dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 44737dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 44747dbb11c8SYang Hongyang 4475e2521f0eSZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4476f6d3afb5SZhang Chen 4477e2521f0eSZhang 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. 4478f6d3afb5SZhang Chen 447900d5c240SZhang 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] 4480d46f75b2SZhang Chen 4481d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 448200d5c240SZhang Chen@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 448300d5c240SZhang Chenfilter-redirector will redirect packet with vnet_hdr_len. 4484d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 4485d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 4486d46f75b2SZhang Chenneed to be specified. 4487d46f75b2SZhang Chen 44884b39bdceSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4489e6eee8abSZhang Chen 4490e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 4491e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 4492e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 44934b39bdceSZhang Chenclient.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4494e6eee8abSZhang Chen 4495e6eee8abSZhang Chenusage: 4496e6eee8abSZhang Chencolo secondary: 4497e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4498e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4499e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4500e6eee8abSZhang Chen 4501c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4502d3e0c032SThomas Huth 4503d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 4504d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4505d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 4506d3e0c032SThomas Huthor Wireshark. 4507d3e0c032SThomas Huth 4508cf6af766SZhang Chen@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid},iothread=@var{id}[,vnet_hdr_support][,notify_dev=@var{id}] 45097dce4e6fSZhang Chen 45107dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 45117dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 45127dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 45137dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 45145aede7f4SZhang ChenIn order to improve efficiency, we need to put the task of comparison 45155aede7f4SZhang Chenin another thread. If it has the vnet_hdr_support flag, colo compare 45165aede7f4SZhang Chenwill send/recv packet with vnet_hdr_len. 4517cf6af766SZhang ChenIf you want to use Xen COLO, will need the notify_dev to notify Xen 4518cf6af766SZhang Chencolo-frame to do checkpoint. 45197dce4e6fSZhang Chen 45207dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 45217dce4e6fSZhang Chen 45227dce4e6fSZhang Chen@example 45237dce4e6fSZhang Chen 4524cf6af766SZhang ChenKVM COLO 4525cf6af766SZhang Chen 45267dce4e6fSZhang Chenprimary: 45277dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 45287dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 45297dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 45307dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 45317dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 45327dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 45337dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 45347dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 45355aede7f4SZhang Chen-object iothread,id=iothread1 45367dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 45377dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 45387dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 45395aede7f4SZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 45407dce4e6fSZhang Chen 45417dce4e6fSZhang Chensecondary: 45427dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 45437dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 45447dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 45457dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 45467dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 45477dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 45487dce4e6fSZhang Chen 4549cf6af766SZhang Chen 4550cf6af766SZhang ChenXen COLO 4551cf6af766SZhang Chen 4552cf6af766SZhang Chenprimary: 4553cf6af766SZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 4554cf6af766SZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 4555cf6af766SZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 4556cf6af766SZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 4557cf6af766SZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 4558cf6af766SZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 4559cf6af766SZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 4560cf6af766SZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 4561cf6af766SZhang Chen-chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait 4562cf6af766SZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 4563cf6af766SZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 4564cf6af766SZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 4565cf6af766SZhang Chen-object iothread,id=iothread1 4566cf6af766SZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 4567cf6af766SZhang Chen 4568cf6af766SZhang Chensecondary: 4569cf6af766SZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 4570cf6af766SZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 4571cf6af766SZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 4572cf6af766SZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 4573cf6af766SZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4574cf6af766SZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4575cf6af766SZhang Chen 45767dce4e6fSZhang Chen@end example 45777dce4e6fSZhang Chen 45787dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 45797dce4e6fSZhang Chenthe colo-compare git log. 45807dce4e6fSZhang Chen 45811653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 45821653a5f3SGonglei 45831653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 45841653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 45851653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 45861653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 45871653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 45881653a5f3SGonglei@var{queues} is 1. 45891653a5f3SGonglei 45901653a5f3SGonglei@example 45911653a5f3SGonglei 4592664785acSThomas Huth # @value{qemu_system} \ 45931653a5f3SGonglei [...] \ 45941653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 45951653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 45961653a5f3SGonglei [...] 45971653a5f3SGonglei@end example 45981653a5f3SGonglei 4599042cea27SGonglei@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 4600042cea27SGonglei 4601042cea27SGongleiCreates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 4602042cea27SGongleiThe @var{id} parameter is a unique ID that will be used to reference this 4603042cea27SGongleicryptodev backend from the @option{virtio-crypto} device. 4604042cea27SGongleiThe chardev should be a unix domain socket backed one. The vhost-user uses 4605042cea27SGongleia specifically defined protocol to pass vhost ioctl replacement messages 4606042cea27SGongleito an application on the other end of the socket. 4607042cea27SGongleiThe @var{queues} parameter is optional, which specify the queue number 4608042cea27SGongleiof cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 4609042cea27SGonglei 4610042cea27SGonglei@example 4611042cea27SGonglei 4612664785acSThomas Huth # @value{qemu_system} \ 4613042cea27SGonglei [...] \ 4614042cea27SGonglei -chardev socket,id=chardev0,path=/path/to/socket \ 4615042cea27SGonglei -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 4616042cea27SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4617042cea27SGonglei [...] 4618042cea27SGonglei@end example 4619042cea27SGonglei 4620ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4621ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4622ac1d8878SDaniel P. Berrange 4623ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4624ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4625ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4626ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4627ac1d8878SDaniel P. Berrange 4628ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4629ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4630ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4631ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4632ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4633ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4634ac1d8878SDaniel P. Berrange 4635ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4636ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4637ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4638ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4639ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4640ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4641ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 464269c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4643ac1d8878SDaniel P. Berrange 4644ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4645ac1d8878SDaniel P. Berrange 4646ac1d8878SDaniel P. Berrange@example 4647ac1d8878SDaniel P. Berrange 4648664785acSThomas Huth # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw 4649ac1d8878SDaniel P. Berrange 4650ac1d8878SDaniel P. Berrange@end example 4651ac1d8878SDaniel P. Berrange 4652ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4653ac1d8878SDaniel P. Berrange 4654b43671f8SEric Blake # printf "letmein" > mypasswd.txt 4655664785acSThomas Huth # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw 4656ac1d8878SDaniel P. Berrange 4657ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4658ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4659ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4660ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4661ac1d8878SDaniel P. Berrange 4662ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4663ac1d8878SDaniel P. Berrange 4664ac1d8878SDaniel P. Berrange@example 4665ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4666ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4667ac1d8878SDaniel P. Berrange@end example 4668ac1d8878SDaniel P. Berrange 4669ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4670ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4671ac1d8878SDaniel P. Berrange 4672ac1d8878SDaniel P. Berrange@example 4673ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4674ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4675ac1d8878SDaniel P. Berrange@end example 4676ac1d8878SDaniel P. Berrange 4677ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4678ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4679ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4680ac1d8878SDaniel P. Berrange 4681ac1d8878SDaniel P. Berrange@example 4682b43671f8SEric Blake # SECRET=$(printf "letmein" | 4683ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4684ac1d8878SDaniel P. Berrange@end example 4685ac1d8878SDaniel P. Berrange 4686ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4687ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4688ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4689ac1d8878SDaniel P. Berrange 4690ac1d8878SDaniel P. Berrange@example 4691664785acSThomas Huth # @value{qemu_system} \ 4692ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4693ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4694ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4695ac1d8878SDaniel P. Berrange@end example 4696ac1d8878SDaniel P. Berrange 4697a9b4942fSBrijesh 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}] 4698a9b4942fSBrijesh Singh 4699a9b4942fSBrijesh SinghCreate a Secure Encrypted Virtualization (SEV) guest object, which can be used 4700a9b4942fSBrijesh Singhto provide the guest memory encryption support on AMD processors. 4701a9b4942fSBrijesh Singh 4702a9b4942fSBrijesh SinghWhen memory encryption is enabled, one of the physical address bit (aka the 4703a9b4942fSBrijesh SinghC-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 4704a9b4942fSBrijesh Singhis used to provide the C-bit position. The C-bit position is Host family dependent 4705a9b4942fSBrijesh Singhhence user must provide this value. On EPYC, the value should be 47. 4706a9b4942fSBrijesh Singh 4707a9b4942fSBrijesh SinghWhen memory encryption is enabled, we loose certain bits in physical address space. 4708a9b4942fSBrijesh SinghThe @option{reduced-phys-bits} is used to provide the number of bits we loose in 4709a9b4942fSBrijesh Singhphysical address space. Similar to C-bit, the value is Host family dependent. 4710a9b4942fSBrijesh SinghOn EPYC, the value should be 5. 4711a9b4942fSBrijesh Singh 4712a9b4942fSBrijesh SinghThe @option{sev-device} provides the device file to use for communicating with 4713a9b4942fSBrijesh Singhthe SEV firmware running inside AMD Secure Processor. The default device is 4714a9b4942fSBrijesh Singh'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 4715a9b4942fSBrijesh Singhcreated by CCP driver. 4716a9b4942fSBrijesh Singh 4717a9b4942fSBrijesh SinghThe @option{policy} provides the guest policy to be enforced by the SEV firmware 4718a9b4942fSBrijesh Singhand restrict what configuration and operational commands can be performed on this 4719a9b4942fSBrijesh Singhguest by the hypervisor. The policy should be provided by the guest owner and is 4720a9b4942fSBrijesh Singhbound to the guest and cannot be changed throughout the lifetime of the guest. 4721a9b4942fSBrijesh SinghThe default is 0. 4722a9b4942fSBrijesh Singh 4723a9b4942fSBrijesh SinghIf guest @option{policy} allows sharing the key with another SEV guest then 4724a9b4942fSBrijesh Singh@option{handle} can be use to provide handle of the guest from which to share 4725a9b4942fSBrijesh Singhthe key. 4726a9b4942fSBrijesh Singh 4727a9b4942fSBrijesh SinghThe @option{dh-cert-file} and @option{session-file} provides the guest owner's 4728a9b4942fSBrijesh SinghPublic Diffie-Hillman key defined in SEV spec. The PDH and session parameters 4729a9b4942fSBrijesh Singhare used for establishing a cryptographic session with the guest owner to 4730a9b4942fSBrijesh Singhnegotiate keys used for attestation. The file must be encoded in base64. 4731a9b4942fSBrijesh Singh 4732a9b4942fSBrijesh Singhe.g to launch a SEV guest 4733a9b4942fSBrijesh Singh@example 4734664785acSThomas Huth # @value{qemu_system_x86} \ 4735a9b4942fSBrijesh Singh ...... 4736a9b4942fSBrijesh Singh -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 4737a9b4942fSBrijesh Singh -machine ...,memory-encryption=sev0 4738a9b4942fSBrijesh Singh ..... 4739a9b4942fSBrijesh Singh 4740a9b4942fSBrijesh Singh@end example 4741fb5c4ebcSDaniel P. Berrangé 4742fb5c4ebcSDaniel P. Berrangé 4743fb5c4ebcSDaniel P. Berrangé@item -object authz-simple,id=@var{id},identity=@var{string} 4744fb5c4ebcSDaniel P. Berrangé 4745fb5c4ebcSDaniel P. BerrangéCreate an authorization object that will control access to network services. 4746fb5c4ebcSDaniel P. Berrangé 4747fb5c4ebcSDaniel P. BerrangéThe @option{identity} parameter is identifies the user and its format 4748fb5c4ebcSDaniel P. Berrangédepends on the network service that authorization object is associated 4749fb5c4ebcSDaniel P. Berrangéwith. For authorizing based on TLS x509 certificates, the identity must 4750fb5c4ebcSDaniel P. Berrangébe the x509 distinguished name. Note that care must be taken to escape 4751fb5c4ebcSDaniel P. Berrangéany commas in the distinguished name. 4752fb5c4ebcSDaniel P. Berrangé 4753fb5c4ebcSDaniel P. BerrangéAn example authorization object to validate a x509 distinguished name 4754fb5c4ebcSDaniel P. Berrangéwould look like: 4755fb5c4ebcSDaniel P. Berrangé@example 4756664785acSThomas Huth # @value{qemu_system} \ 4757fb5c4ebcSDaniel P. Berrangé ... 4758fb5c4ebcSDaniel P. Berrangé -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \ 4759fb5c4ebcSDaniel P. Berrangé ... 4760fb5c4ebcSDaniel P. Berrangé@end example 4761fb5c4ebcSDaniel P. Berrangé 4762fb5c4ebcSDaniel P. BerrangéNote the use of quotes due to the x509 distinguished name containing 4763fb5c4ebcSDaniel P. Berrangéwhitespace, and escaping of ','. 4764fb5c4ebcSDaniel P. Berrangé 476555d86984SDaniel P. Berrangé@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no} 476655d86984SDaniel P. Berrangé 476755d86984SDaniel P. BerrangéCreate an authorization object that will control access to network services. 476855d86984SDaniel P. Berrangé 476955d86984SDaniel P. BerrangéThe @option{filename} parameter is the fully qualified path to a file 477055d86984SDaniel P. Berrangécontaining the access control list rules in JSON format. 477155d86984SDaniel P. Berrangé 477255d86984SDaniel P. BerrangéAn example set of rules that match against SASL usernames might look 477355d86984SDaniel P. Berrangélike: 477455d86984SDaniel P. Berrangé 477555d86984SDaniel P. Berrangé@example 477655d86984SDaniel P. Berrangé @{ 477755d86984SDaniel P. Berrangé "rules": [ 477855d86984SDaniel P. Berrangé @{ "match": "fred", "policy": "allow", "format": "exact" @}, 477955d86984SDaniel P. Berrangé @{ "match": "bob", "policy": "allow", "format": "exact" @}, 478055d86984SDaniel P. Berrangé @{ "match": "danb", "policy": "deny", "format": "glob" @}, 478155d86984SDaniel P. Berrangé @{ "match": "dan*", "policy": "allow", "format": "exact" @}, 478255d86984SDaniel P. Berrangé ], 478355d86984SDaniel P. Berrangé "policy": "deny" 478455d86984SDaniel P. Berrangé @} 478555d86984SDaniel P. Berrangé@end example 478655d86984SDaniel P. Berrangé 478755d86984SDaniel P. BerrangéWhen checking access the object will iterate over all the rules and 478855d86984SDaniel P. Berrangéthe first rule to match will have its @option{policy} value returned 478955d86984SDaniel P. Berrangéas the result. If no rules match, then the default @option{policy} 479055d86984SDaniel P. Berrangévalue is returned. 479155d86984SDaniel P. Berrangé 479255d86984SDaniel P. BerrangéThe rules can either be an exact string match, or they can use the 479355d86984SDaniel P. Berrangésimple UNIX glob pattern matching to allow wildcards to be used. 479455d86984SDaniel P. Berrangé 479555d86984SDaniel P. BerrangéIf @option{refresh} is set to true the file will be monitored 479655d86984SDaniel P. Berrangéand automatically reloaded whenever its content changes. 479755d86984SDaniel P. Berrangé 479855d86984SDaniel P. BerrangéAs with the @code{authz-simple} object, the format of the identity 479955d86984SDaniel P. Berrangéstrings being matched depends on the network service, but is usually 480055d86984SDaniel P. Berrangéa TLS x509 distinguished name, or a SASL username. 480155d86984SDaniel P. Berrangé 480255d86984SDaniel P. BerrangéAn example authorization object to validate a SASL username 480355d86984SDaniel P. Berrangéwould look like: 480455d86984SDaniel P. Berrangé@example 4805664785acSThomas Huth # @value{qemu_system} \ 480655d86984SDaniel P. Berrangé ... 480755d86984SDaniel P. Berrangé -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes 480855d86984SDaniel P. Berrangé ... 480955d86984SDaniel P. Berrangé@end example 481055d86984SDaniel P. Berrangé 48118953caf3SDaniel P. Berrange@item -object authz-pam,id=@var{id},service=@var{string} 48128953caf3SDaniel P. Berrange 48138953caf3SDaniel P. BerrangeCreate an authorization object that will control access to network services. 48148953caf3SDaniel P. Berrange 48158953caf3SDaniel P. BerrangeThe @option{service} parameter provides the name of a PAM service to use 48168953caf3SDaniel P. Berrangefor authorization. It requires that a file @code{/etc/pam.d/@var{service}} 48178953caf3SDaniel P. Berrangeexist to provide the configuration for the @code{account} subsystem. 48188953caf3SDaniel P. Berrange 48198953caf3SDaniel P. BerrangeAn example authorization object to validate a TLS x509 distinguished 48208953caf3SDaniel P. Berrangename would look like: 48218953caf3SDaniel P. Berrange 48228953caf3SDaniel P. Berrange@example 4823664785acSThomas Huth # @value{qemu_system} \ 48248953caf3SDaniel P. Berrange ... 48258953caf3SDaniel P. Berrange -object authz-pam,id=auth0,service=qemu-vnc 48268953caf3SDaniel P. Berrange ... 48278953caf3SDaniel P. Berrange@end example 48288953caf3SDaniel P. Berrange 48298953caf3SDaniel P. BerrangeThere would then be a corresponding config file for PAM at 48308953caf3SDaniel P. Berrange@code{/etc/pam.d/qemu-vnc} that contains: 48318953caf3SDaniel P. Berrange 48328953caf3SDaniel P. Berrange@example 48338953caf3SDaniel P. Berrangeaccount requisite pam_listfile.so item=user sense=allow \ 48348953caf3SDaniel P. Berrange file=/etc/qemu/vnc.allow 48358953caf3SDaniel P. Berrange@end example 48368953caf3SDaniel P. Berrange 48378953caf3SDaniel P. BerrangeFinally the @code{/etc/qemu/vnc.allow} file would contain 48388953caf3SDaniel P. Berrangethe list of x509 distingished names that are permitted 48398953caf3SDaniel P. Berrangeaccess 48408953caf3SDaniel P. Berrange 48418953caf3SDaniel P. Berrange@example 48428953caf3SDaniel P. BerrangeCN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB 48438953caf3SDaniel P. Berrange@end example 48448953caf3SDaniel P. Berrange 484586d2a49bSStefan Hajnoczi@item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink} 484686d2a49bSStefan Hajnoczi 484786d2a49bSStefan HajnocziCreates a dedicated event loop thread that devices can be assigned to. This is 484886d2a49bSStefan Hajnocziknown as an IOThread. By default device emulation happens in vCPU threads or 484986d2a49bSStefan Hajnoczithe main event loop thread. This can become a scalability bottleneck. 485086d2a49bSStefan HajnocziIOThreads allow device emulation and I/O to run on other host CPUs. 485186d2a49bSStefan Hajnoczi 485286d2a49bSStefan HajnocziThe @option{id} parameter is a unique ID that will be used to reference this 485386d2a49bSStefan HajnocziIOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be 485486d2a49bSStefan Hajnocziassigned to an IOThread. Note that not all devices support an 485586d2a49bSStefan Hajnoczi@option{iothread} parameter. 485686d2a49bSStefan Hajnoczi 485786d2a49bSStefan HajnocziThe @code{query-iothreads} QMP command lists IOThreads and reports their thread 485886d2a49bSStefan HajnocziIDs so that the user can configure host CPU pinning/affinity. 485986d2a49bSStefan Hajnoczi 486086d2a49bSStefan HajnocziIOThreads use an adaptive polling algorithm to reduce event loop latency. 486186d2a49bSStefan HajnocziInstead of entering a blocking system call to monitor file descriptors and then 486286d2a49bSStefan Hajnoczipay the cost of being woken up when an event occurs, the polling algorithm 486386d2a49bSStefan Hajnoczispins waiting for events for a short time. The algorithm's default parameters 486486d2a49bSStefan Hajnocziare suitable for many cases but can be adjusted based on knowledge of the 486586d2a49bSStefan Hajnocziworkload and/or host device latency. 486686d2a49bSStefan Hajnoczi 486786d2a49bSStefan HajnocziThe @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy 486886d2a49bSStefan Hajnocziwait for events. Polling can be disabled by setting this value to 0. 486986d2a49bSStefan Hajnoczi 487086d2a49bSStefan HajnocziThe @option{poll-grow} parameter is the multiplier used to increase the polling 487186d2a49bSStefan Hajnoczitime when the algorithm detects it is missing events due to not polling long 487286d2a49bSStefan Hajnoczienough. 487386d2a49bSStefan Hajnoczi 487486d2a49bSStefan HajnocziThe @option{poll-shrink} parameter is the divisor used to decrease the polling 487586d2a49bSStefan Hajnoczitime when the algorithm detects it is spending too long polling without 487686d2a49bSStefan Hajnocziencountering events. 487786d2a49bSStefan Hajnoczi 487886d2a49bSStefan HajnocziThe polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}): 487986d2a49bSStefan Hajnoczi 488086d2a49bSStefan Hajnoczi@example 488186d2a49bSStefan Hajnoczi(qemu) qom-set /objects/iothread1 poll-max-ns 100000 488286d2a49bSStefan Hajnoczi@end example 48838953caf3SDaniel P. Berrange 4884b9174d4fSDaniel P. Berrange@end table 4885b9174d4fSDaniel P. Berrange 4886b9174d4fSDaniel P. BerrangeETEXI 4887b9174d4fSDaniel P. Berrange 4888b9174d4fSDaniel P. Berrange 48893dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 48903dbf2c7fSStefan WeilSTEXI 48913dbf2c7fSStefan Weil@end table 48923dbf2c7fSStefan WeilETEXI 4893