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 943f187a5SPaolo BonziniDEFHEADING(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" 34bde4d920SThomas Huth " supported accelerators are kvm, xen, hax or tcg (default: tcg)\n" 3532c18a2dSMatt Gingell " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n" 36d1048befSDon Slutz " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 3796404013SPeter Maydell " kvm_shadow_mem=size of KVM shadow MMU in bytes\n" 388490fc78SLuiz Capitulino " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 39a52a7fdfSLe Tan " mem-merge=on|off controls memory merge support (default: on)\n" 4079814179STiejun Chen " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n" 412eb1cd07STony Krowiak " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 429850c604SAlexander Graf " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 4387252e1bSXiao Guangrong " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 44902c053dSGreg Kurz " nvdimm=on|off controls NVDIMM support (default=off)\n" 45274250c3SXiao Feng Ren " enforce-config-section=on|off enforce configuration section migration (default=off)\n" 46274250c3SXiao Feng Ren " s390-squash-mcss=on|off controls support for squashing into default css (default=off)\n", 4780f52a66SJan Kiszka QEMU_ARCH_ALL) 485824d651Sblueswir1STEXI 4980f52a66SJan Kiszka@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 5080f52a66SJan Kiszka@findex -machine 51585f6036SPeter MaydellSelect the emulated machine by @var{name}. Use @code{-machine help} to list 528bfce83aSDaniel P. Berrangeavailable machines. 538bfce83aSDaniel P. Berrange 548bfce83aSDaniel P. BerrangeFor architectures which aim to support live migration compatibility 558bfce83aSDaniel P. Berrangeacross releases, each release will introduce a new versioned machine 568bfce83aSDaniel P. Berrangetype. For example, the 2.8.0 release introduced machine types 578bfce83aSDaniel P. Berrange``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 588bfce83aSDaniel P. Berrange 598bfce83aSDaniel P. BerrangeTo allow live migration of guests from QEMU version 2.8.0, to QEMU 608bfce83aSDaniel P. Berrangeversion 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 618bfce83aSDaniel P. Berrangeand ``pc-q35-2.8'' machines too. To allow users live migrating VMs 628bfce83aSDaniel P. Berrangeto skip multiple intermediate releases when upgrading, new releases 638bfce83aSDaniel P. Berrangeof QEMU will support machine types from many previous versions. 648bfce83aSDaniel P. Berrange 658bfce83aSDaniel P. BerrangeSupported machine properties are: 6680f52a66SJan Kiszka@table @option 6780f52a66SJan Kiszka@item accel=@var{accels1}[:@var{accels2}[:...]] 6880f52a66SJan KiszkaThis is used to enable an accelerator. Depending on the target architecture, 69bde4d920SThomas Huthkvm, xen, hax or tcg can be available. By default, tcg is used. If there is 70bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 71bde4d920SThomas Huthfails to initialize. 726a48ffaaSJan Kiszka@item kernel_irqchip=on|off 7332c18a2dSMatt GingellControls in-kernel irqchip support for the chosen accelerator when available. 7479814179STiejun Chen@item gfx_passthru=on|off 7579814179STiejun ChenEnables IGD GFX passthrough support for the chosen machine when available. 76d1048befSDon Slutz@item vmport=on|off|auto 77d1048befSDon SlutzEnables emulation of VMWare IO port, for vmmouse etc. auto says to select the 78d1048befSDon Slutzvalue based on accel. For accel=xen the default is off otherwise the default 79d1048befSDon Slutzis on. 8039d6960aSJan Kiszka@item kvm_shadow_mem=size 8139d6960aSJan KiszkaDefines the size of the KVM shadow MMU. 82ddb97f1dSJason Baron@item dump-guest-core=on|off 83ddb97f1dSJason BaronInclude guest memory in a core dump. The default is on. 848490fc78SLuiz Capitulino@item mem-merge=on|off 858490fc78SLuiz CapitulinoEnables or disables memory merge support. This feature, when supported by 868490fc78SLuiz Capitulinothe host, de-duplicates identical memory pages among VMs instances 878490fc78SLuiz Capitulino(enabled by default). 882eb1cd07STony Krowiak@item aes-key-wrap=on|off 892eb1cd07STony KrowiakEnables or disables AES key wrapping support on s390-ccw hosts. This feature 902eb1cd07STony Krowiakcontrols whether AES wrapping keys will be created to allow 912eb1cd07STony Krowiakexecution of AES cryptographic functions. The default is on. 922eb1cd07STony Krowiak@item dea-key-wrap=on|off 932eb1cd07STony KrowiakEnables or disables DEA key wrapping support on s390-ccw hosts. This feature 942eb1cd07STony Krowiakcontrols whether DEA wrapping keys will be created to allow 952eb1cd07STony Krowiakexecution of DEA cryptographic functions. The default is on. 9687252e1bSXiao Guangrong@item nvdimm=on|off 9787252e1bSXiao GuangrongEnables or disables NVDIMM support. The default is off. 98274250c3SXiao Feng Ren@item s390-squash-mcss=on|off 99274250c3SXiao Feng RenEnables or disables squashing subchannels into the default css. 100274250c3SXiao Feng RenThe default is off. 10116f72448SPeter Xu@item enforce-config-section=on|off 10216f72448SPeter XuIf @option{enforce-config-section} is set to @var{on}, force migration 10316f72448SPeter Xucode to send configuration section even if the machine-type sets the 10416f72448SPeter Xu@option{migration.send-configuration} property to @var{off}. 10516f72448SPeter XuNOTE: this parameter is deprecated. Please use @option{-global} 10616f72448SPeter Xu@option{migration.send-configuration}=@var{on|off} instead. 10780f52a66SJan Kiszka@end table 1085824d651Sblueswir1ETEXI 1095824d651Sblueswir1 11080f52a66SJan KiszkaHXCOMM Deprecated by -machine 11180f52a66SJan KiszkaDEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 11280f52a66SJan Kiszka 1135824d651Sblueswir1DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 114585f6036SPeter Maydell "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 1155824d651Sblueswir1STEXI 1165824d651Sblueswir1@item -cpu @var{model} 1176616b2adSStefan Weil@findex -cpu 118585f6036SPeter MaydellSelect CPU model (@code{-cpu help} for list and additional feature selection) 1195824d651Sblueswir1ETEXI 1205824d651Sblueswir1 1218d4e9146SKONRAD FredericDEF("accel", HAS_ARG, QEMU_OPTION_accel, 1228d4e9146SKONRAD Frederic "-accel [accel=]accelerator[,thread=single|multi]\n" 123bde4d920SThomas Huth " select accelerator (kvm, xen, hax or tcg; use 'help' for a list)\n" 124f603164aSSuraj Jitindar Singh " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL) 1258d4e9146SKONRAD FredericSTEXI 1268d4e9146SKONRAD Frederic@item -accel @var{name}[,prop=@var{value}[,...]] 1278d4e9146SKONRAD Frederic@findex -accel 1288d4e9146SKONRAD FredericThis is used to enable an accelerator. Depending on the target architecture, 129bde4d920SThomas Huthkvm, xen, hax or tcg can be available. By default, tcg is used. If there is 130bde4d920SThomas Huthmore than one accelerator specified, the next one is used if the previous one 131bde4d920SThomas Huthfails to initialize. 1328d4e9146SKONRAD Frederic@table @option 1338d4e9146SKONRAD Frederic@item thread=single|multi 1348d4e9146SKONRAD FredericControls number of TCG threads. When the TCG is multi-threaded there will be one 1358d4e9146SKONRAD Fredericthread per vCPU therefor taking advantage of additional host cores. The default 1368d4e9146SKONRAD Fredericis to enable multi-threading where both the back-end and front-ends support it and 1378d4e9146SKONRAD Fredericno incompatible TCG features have been enabled (e.g. icount/replay). 1388d4e9146SKONRAD Frederic@end table 1398d4e9146SKONRAD FredericETEXI 1408d4e9146SKONRAD Frederic 1415824d651Sblueswir1DEF("smp", HAS_ARG, QEMU_OPTION_smp, 14212b7f57eSMichael Tokarev "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 1436be68d7eSJes Sorensen " set the number of CPUs to 'n' [default=1]\n" 1446be68d7eSJes Sorensen " maxcpus= maximum number of total cpus, including\n" 145ca1a8a06SBruce Rogers " offline CPUs for hotplug, etc\n" 14658a04db1SAndre Przywara " cores= number of CPU cores on one socket\n" 14758a04db1SAndre Przywara " threads= number of threads on one CPU core\n" 148ad96090aSBlue Swirl " sockets= number of discrete sockets in the system\n", 149ad96090aSBlue Swirl QEMU_ARCH_ALL) 1505824d651Sblueswir1STEXI 15112b7f57eSMichael Tokarev@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 1526616b2adSStefan Weil@findex -smp 1535824d651Sblueswir1Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 1545824d651Sblueswir1CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 1555824d651Sblueswir1to 4. 15658a04db1SAndre PrzywaraFor the PC target, the number of @var{cores} per socket, the number 15758a04db1SAndre Przywaraof @var{threads} per cores and the total number of @var{sockets} can be 15858a04db1SAndre Przywaraspecified. Missing values will be computed. If any on the three values is 15958a04db1SAndre Przywaragiven, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 16058a04db1SAndre Przywaraspecifies the maximum number of hotpluggable CPUs. 1615824d651Sblueswir1ETEXI 1625824d651Sblueswir1 163268a362cSaliguoriDEF("numa", HAS_ARG, QEMU_OPTION_numa, 164e0ee9fd0SEduardo Habkost "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1650f203430SHe Chen "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 1660f203430SHe Chen "-numa dist,src=source,dst=destination,val=distance\n", QEMU_ARCH_ALL) 167268a362cSaliguoriSTEXI 168e0ee9fd0SEduardo Habkost@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 169e0ee9fd0SEduardo Habkost@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 1700f203430SHe Chen@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 171419fcdecSIgor Mammedov@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 1726616b2adSStefan Weil@findex -numa 1734b9a5dd7SEduardo HabkostDefine a NUMA node and assign RAM and VCPUs to it. 1740f203430SHe ChenSet the NUMA distance from a source node to a destination node. 1757febe36fSPaolo Bonzini 176419fcdecSIgor MammedovLegacy VCPU assignment uses @samp{cpus} option where 1774b9a5dd7SEduardo Habkost@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 1784b9a5dd7SEduardo Habkost@samp{cpus} option represent a contiguous range of CPU indexes 1794b9a5dd7SEduardo Habkost(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 1804b9a5dd7SEduardo Habkostset of VCPUs can be represented by providing multiple @samp{cpus} 1814b9a5dd7SEduardo Habkostoptions. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 1824b9a5dd7SEduardo Habkostsplit between them. 1834b9a5dd7SEduardo Habkost 1844b9a5dd7SEduardo HabkostFor example, the following option assigns VCPUs 0, 1, 2 and 5 to 1854b9a5dd7SEduardo Habkosta NUMA node: 1864b9a5dd7SEduardo Habkost@example 1874b9a5dd7SEduardo Habkost-numa node,cpus=0-2,cpus=5 1884b9a5dd7SEduardo Habkost@end example 1894b9a5dd7SEduardo Habkost 190419fcdecSIgor Mammedov@samp{cpu} option is a new alternative to @samp{cpus} option 191419fcdecSIgor Mammedovwhich uses @samp{socket-id|core-id|thread-id} properties to assign 192419fcdecSIgor MammedovCPU objects to a @var{node} using topology layout properties of CPU. 193419fcdecSIgor MammedovThe set of properties is machine specific, and depends on used 194419fcdecSIgor Mammedovmachine type/@samp{smp} options. It could be queried with 195419fcdecSIgor Mammedov@samp{hotpluggable-cpus} monitor command. 196419fcdecSIgor Mammedov@samp{node-id} property specifies @var{node} to which CPU object 197419fcdecSIgor Mammedovwill be assigned, it's required for @var{node} to be declared 198419fcdecSIgor Mammedovwith @samp{node} option before it's used with @samp{cpu} option. 199419fcdecSIgor Mammedov 200419fcdecSIgor MammedovFor example: 201419fcdecSIgor Mammedov@example 202419fcdecSIgor Mammedov-M pc \ 203419fcdecSIgor Mammedov-smp 1,sockets=2,maxcpus=2 \ 204419fcdecSIgor Mammedov-numa node,nodeid=0 -numa node,nodeid=1 \ 205419fcdecSIgor Mammedov-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 206419fcdecSIgor Mammedov@end example 207419fcdecSIgor Mammedov 2084b9a5dd7SEduardo Habkost@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 2094b9a5dd7SEduardo Habkostassigns RAM from a given memory backend device to a node. If 2104b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 2114b9a5dd7SEduardo Habkostsplit equally between them. 2124b9a5dd7SEduardo Habkost 2134b9a5dd7SEduardo Habkost@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 2144b9a5dd7SEduardo Habkostif one node uses @samp{memdev}, all of them have to use it. 2154b9a5dd7SEduardo Habkost 2160f203430SHe Chen@var{source} and @var{destination} are NUMA node IDs. 2170f203430SHe Chen@var{distance} is the NUMA distance from @var{source} to @var{destination}. 2180f203430SHe ChenThe distance from a node to itself is always 10. If any pair of nodes is 2190f203430SHe Chengiven a distance, then all pairs must be given distances. Although, when 2200f203430SHe Chendistances are only given in one direction for each pair of nodes, then 2210f203430SHe Chenthe distances in the opposite directions are assumed to be the same. If, 2220f203430SHe Chenhowever, an asymmetrical pair of distances is given for even one node 2230f203430SHe Chenpair, then all node pairs must be provided distance values for both 2240f203430SHe Chendirections, even when they are symmetrical. When a node is unreachable 2250f203430SHe Chenfrom another node, set the pair's distance to 255. 2260f203430SHe Chen 2274b9a5dd7SEduardo HabkostNote that the -@option{numa} option doesn't allocate any of the 2284b9a5dd7SEduardo Habkostspecified resources, it just assigns existing resources to NUMA 2294b9a5dd7SEduardo Habkostnodes. This means that one still has to use the @option{-m}, 2304b9a5dd7SEduardo Habkost@option{-smp} options to allocate RAM and VCPUs respectively. 2314b9a5dd7SEduardo Habkost 232268a362cSaliguoriETEXI 233268a362cSaliguori 23410adb8beSMarkus ArmbrusterDEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 23510adb8beSMarkus Armbruster "-add-fd fd=fd,set=set[,opaque=opaque]\n" 23610adb8beSMarkus Armbruster " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 23710adb8beSMarkus ArmbrusterSTEXI 23810adb8beSMarkus Armbruster@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 23910adb8beSMarkus Armbruster@findex -add-fd 24010adb8beSMarkus Armbruster 24110adb8beSMarkus ArmbrusterAdd a file descriptor to an fd set. Valid options are: 24210adb8beSMarkus Armbruster 24310adb8beSMarkus Armbruster@table @option 24410adb8beSMarkus Armbruster@item fd=@var{fd} 24510adb8beSMarkus ArmbrusterThis option defines the file descriptor of which a duplicate is added to fd set. 24610adb8beSMarkus ArmbrusterThe file descriptor cannot be stdin, stdout, or stderr. 24710adb8beSMarkus Armbruster@item set=@var{set} 24810adb8beSMarkus ArmbrusterThis option defines the ID of the fd set to add the file descriptor to. 24910adb8beSMarkus Armbruster@item opaque=@var{opaque} 25010adb8beSMarkus ArmbrusterThis option defines a free-form string that can be used to describe @var{fd}. 25110adb8beSMarkus Armbruster@end table 25210adb8beSMarkus Armbruster 25310adb8beSMarkus ArmbrusterYou can open an image using pre-opened file descriptors from an fd set: 25410adb8beSMarkus Armbruster@example 25510adb8beSMarkus Armbrusterqemu-system-i386 25610adb8beSMarkus Armbruster-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 25710adb8beSMarkus Armbruster-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 25810adb8beSMarkus Armbruster-drive file=/dev/fdset/2,index=0,media=disk 25910adb8beSMarkus Armbruster@end example 26010adb8beSMarkus ArmbrusterETEXI 26110adb8beSMarkus Armbruster 26210adb8beSMarkus ArmbrusterDEF("set", HAS_ARG, QEMU_OPTION_set, 26310adb8beSMarkus Armbruster "-set group.id.arg=value\n" 26410adb8beSMarkus Armbruster " set <arg> parameter for item <id> of type <group>\n" 26510adb8beSMarkus Armbruster " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 26610adb8beSMarkus ArmbrusterSTEXI 26710adb8beSMarkus Armbruster@item -set @var{group}.@var{id}.@var{arg}=@var{value} 26810adb8beSMarkus Armbruster@findex -set 269e1f3b974SMichael TokarevSet parameter @var{arg} for item @var{id} of type @var{group} 27010adb8beSMarkus ArmbrusterETEXI 27110adb8beSMarkus Armbruster 27210adb8beSMarkus ArmbrusterDEF("global", HAS_ARG, QEMU_OPTION_global, 2733751d7c4SPaolo Bonzini "-global driver.property=value\n" 2743751d7c4SPaolo Bonzini "-global driver=driver,property=property,value=value\n" 27510adb8beSMarkus Armbruster " set a global default for a driver property\n", 27610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 27710adb8beSMarkus ArmbrusterSTEXI 27810adb8beSMarkus Armbruster@item -global @var{driver}.@var{prop}=@var{value} 2793751d7c4SPaolo Bonzini@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 28010adb8beSMarkus Armbruster@findex -global 28110adb8beSMarkus ArmbrusterSet default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 28210adb8beSMarkus Armbruster 28310adb8beSMarkus Armbruster@example 2841c9f3b88SMarkus Armbrusterqemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img 28510adb8beSMarkus Armbruster@end example 28610adb8beSMarkus Armbruster 28710adb8beSMarkus ArmbrusterIn particular, you can use this to set driver properties for devices which are 28810adb8beSMarkus Armbrustercreated automatically by the machine model. To create a device which is not 28910adb8beSMarkus Armbrustercreated automatically and set properties on it, use -@option{device}. 2903751d7c4SPaolo Bonzini 291ae08fd5aSMarkus Armbruster-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 292ae08fd5aSMarkus Armbrusterdriver=@var{driver},property=@var{prop},value=@var{value}. The 293ae08fd5aSMarkus Armbrusterlonghand syntax works even when @var{driver} contains a dot. 29410adb8beSMarkus ArmbrusterETEXI 29510adb8beSMarkus Armbruster 29610adb8beSMarkus ArmbrusterDEF("boot", HAS_ARG, QEMU_OPTION_boot, 29710adb8beSMarkus Armbruster "-boot [order=drives][,once=drives][,menu=on|off]\n" 298c8a6ae8bSAmos Kong " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 29910adb8beSMarkus Armbruster " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 30010adb8beSMarkus Armbruster " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 30110adb8beSMarkus Armbruster " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 30210adb8beSMarkus Armbruster " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 30310adb8beSMarkus Armbruster QEMU_ARCH_ALL) 30410adb8beSMarkus ArmbrusterSTEXI 305c8a6ae8bSAmos 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] 30610adb8beSMarkus Armbruster@findex -boot 30710adb8beSMarkus ArmbrusterSpecify boot order @var{drives} as a string of drive letters. Valid 308d274e07cSGongleidrive letters depend on the target architecture. The x86 PC uses: a, b 30910adb8beSMarkus Armbruster(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 31010adb8beSMarkus Armbrusterfrom network adapter 1-4), hard disk boot is the default. To apply a 31110adb8beSMarkus Armbrusterparticular boot order only on the first startup, specify it via 312c0d9f7d0SThomas Huth@option{once}. Note that the @option{order} or @option{once} parameter 313c0d9f7d0SThomas Huthshould not be used together with the @option{bootindex} property of 314c0d9f7d0SThomas Huthdevices, since the firmware implementations normally do not support both 315c0d9f7d0SThomas Huthat the same time. 31610adb8beSMarkus Armbruster 31710adb8beSMarkus ArmbrusterInteractive boot menus/prompts can be enabled via @option{menu=on} as far 31810adb8beSMarkus Armbrusteras firmware/BIOS supports them. The default is non-interactive boot. 31910adb8beSMarkus Armbruster 32010adb8beSMarkus ArmbrusterA splash picture could be passed to bios, enabling user to show it as logo, 32110adb8beSMarkus Armbrusterwhen option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 32210adb8beSMarkus Armbrustersupports them. Currently Seabios for X86 system support it. 32310adb8beSMarkus Armbrusterlimitation: The splash file could be a jpeg file or a BMP file in 24 BPP 32410adb8beSMarkus Armbrusterformat(true color). The resolution should be supported by the SVGA mode, so 32510adb8beSMarkus Armbrusterthe recommended is 320x240, 640x480, 800x640. 32610adb8beSMarkus Armbruster 32710adb8beSMarkus ArmbrusterA timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 32810adb8beSMarkus Armbrusterwhen boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 32910adb8beSMarkus Armbrusterreboot, qemu passes '-1' to bios by default. Currently Seabios for X86 33010adb8beSMarkus Armbrustersystem support it. 33110adb8beSMarkus Armbruster 332c8a6ae8bSAmos KongDo strict boot via @option{strict=on} as far as firmware/BIOS 333c8a6ae8bSAmos Kongsupports it. This only effects when boot priority is changed by 334c8a6ae8bSAmos Kongbootindex options. The default is non-strict boot. 335c8a6ae8bSAmos Kong 33610adb8beSMarkus Armbruster@example 33710adb8beSMarkus Armbruster# try to boot from network first, then from hard disk 33810adb8beSMarkus Armbrusterqemu-system-i386 -boot order=nc 33910adb8beSMarkus Armbruster# boot from CD-ROM first, switch back to default order after reboot 34010adb8beSMarkus Armbrusterqemu-system-i386 -boot once=d 34110adb8beSMarkus Armbruster# boot with a splash picture for 5 seconds. 34210adb8beSMarkus Armbrusterqemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 34310adb8beSMarkus Armbruster@end example 34410adb8beSMarkus Armbruster 34510adb8beSMarkus ArmbrusterNote: The legacy format '-boot @var{drives}' is still supported but its 34610adb8beSMarkus Armbrusteruse is discouraged as it may be removed from future versions. 34710adb8beSMarkus ArmbrusterETEXI 34810adb8beSMarkus Armbruster 34910adb8beSMarkus ArmbrusterDEF("m", HAS_ARG, QEMU_OPTION_m, 35089f3ea2bSMichael Tokarev "-m [size=]megs[,slots=n,maxmem=size]\n" 3516e1d3c1cSIgor Mammedov " configure guest RAM\n" 3520daba1f0SAlexander Graf " size: initial amount of guest memory\n" 353c270fb9eSIgor Mammedov " slots: number of hotplug slots (default: none)\n" 354b6fe0124SMatthew Rosato " maxmem: maximum amount of guest memory (default: none)\n" 355b6fe0124SMatthew Rosato "NOTE: Some architectures might enforce a specific granularity\n", 3566e1d3c1cSIgor Mammedov QEMU_ARCH_ALL) 35710adb8beSMarkus ArmbrusterSTEXI 3589fcc0794SLuiz Capitulino@item -m [size=]@var{megs}[,slots=n,maxmem=size] 35910adb8beSMarkus Armbruster@findex -m 3609fcc0794SLuiz CapitulinoSets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 3619fcc0794SLuiz CapitulinoOptionally, a suffix of ``M'' or ``G'' can be used to signify a value in 3629fcc0794SLuiz Capitulinomegabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 3639fcc0794SLuiz Capitulinocould be used to set amount of hotpluggable memory slots and maximum amount of 3649fcc0794SLuiz Capitulinomemory. Note that @var{maxmem} must be aligned to the page size. 3659fcc0794SLuiz Capitulino 3669fcc0794SLuiz CapitulinoFor example, the following command-line sets the guest startup RAM size to 3679fcc0794SLuiz Capitulino1GB, creates 3 slots to hotplug additional memory and sets the maximum 3689fcc0794SLuiz Capitulinomemory the guest can reach to 4GB: 3699fcc0794SLuiz Capitulino 3709fcc0794SLuiz Capitulino@example 3719fcc0794SLuiz Capitulinoqemu-system-x86_64 -m 1G,slots=3,maxmem=4G 3729fcc0794SLuiz Capitulino@end example 3739fcc0794SLuiz Capitulino 3749fcc0794SLuiz CapitulinoIf @var{slots} and @var{maxmem} are not specified, memory hotplug won't 3759fcc0794SLuiz Capitulinobe enabled and the guest startup RAM will never increase. 37610adb8beSMarkus ArmbrusterETEXI 37710adb8beSMarkus Armbruster 37810adb8beSMarkus ArmbrusterDEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 37910adb8beSMarkus Armbruster "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 38010adb8beSMarkus ArmbrusterSTEXI 38110adb8beSMarkus Armbruster@item -mem-path @var{path} 38210adb8beSMarkus Armbruster@findex -mem-path 38310adb8beSMarkus ArmbrusterAllocate guest RAM from a temporarily created file in @var{path}. 38410adb8beSMarkus ArmbrusterETEXI 38510adb8beSMarkus Armbruster 38610adb8beSMarkus ArmbrusterDEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 38710adb8beSMarkus Armbruster "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 38810adb8beSMarkus Armbruster QEMU_ARCH_ALL) 38910adb8beSMarkus ArmbrusterSTEXI 39010adb8beSMarkus Armbruster@item -mem-prealloc 39110adb8beSMarkus Armbruster@findex -mem-prealloc 39210adb8beSMarkus ArmbrusterPreallocate memory when using -mem-path. 39310adb8beSMarkus ArmbrusterETEXI 39410adb8beSMarkus Armbruster 39510adb8beSMarkus ArmbrusterDEF("k", HAS_ARG, QEMU_OPTION_k, 39610adb8beSMarkus Armbruster "-k language use keyboard layout (for example 'fr' for French)\n", 39710adb8beSMarkus Armbruster QEMU_ARCH_ALL) 39810adb8beSMarkus ArmbrusterSTEXI 39910adb8beSMarkus Armbruster@item -k @var{language} 40010adb8beSMarkus Armbruster@findex -k 40110adb8beSMarkus ArmbrusterUse keyboard layout @var{language} (for example @code{fr} for 40210adb8beSMarkus ArmbrusterFrench). This option is only needed where it is not easy to get raw PC 40332945472SSamuel Thibaultkeycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 40410adb8beSMarkus Armbrusterdisplay). You don't normally need to use it on PC/Linux or PC/Windows 40510adb8beSMarkus Armbrusterhosts. 40610adb8beSMarkus Armbruster 40710adb8beSMarkus ArmbrusterThe available layouts are: 40810adb8beSMarkus Armbruster@example 40910adb8beSMarkus Armbrusterar de-ch es fo fr-ca hu ja mk no pt-br sv 41010adb8beSMarkus Armbrusterda en-gb et fr fr-ch is lt nl pl ru th 41110adb8beSMarkus Armbrusterde en-us fi fr-be hr it lv nl-be pt sl tr 41210adb8beSMarkus Armbruster@end example 41310adb8beSMarkus Armbruster 41410adb8beSMarkus ArmbrusterThe default is @code{en-us}. 41510adb8beSMarkus ArmbrusterETEXI 41610adb8beSMarkus Armbruster 41710adb8beSMarkus Armbruster 41810adb8beSMarkus ArmbrusterDEF("audio-help", 0, QEMU_OPTION_audio_help, 41910adb8beSMarkus Armbruster "-audio-help print list of audio drivers and their options\n", 42010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 42110adb8beSMarkus ArmbrusterSTEXI 42210adb8beSMarkus Armbruster@item -audio-help 42310adb8beSMarkus Armbruster@findex -audio-help 42410adb8beSMarkus ArmbrusterWill show the audio subsystem help: list of drivers, tunable 42510adb8beSMarkus Armbrusterparameters. 42610adb8beSMarkus ArmbrusterETEXI 42710adb8beSMarkus Armbruster 42810adb8beSMarkus ArmbrusterDEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 42910adb8beSMarkus Armbruster "-soundhw c1,... enable audio support\n" 43010adb8beSMarkus Armbruster " and only specified sound cards (comma separated list)\n" 43110adb8beSMarkus Armbruster " use '-soundhw help' to get the list of supported cards\n" 43210adb8beSMarkus Armbruster " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 43310adb8beSMarkus ArmbrusterSTEXI 43410adb8beSMarkus Armbruster@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 43510adb8beSMarkus Armbruster@findex -soundhw 43610adb8beSMarkus ArmbrusterEnable audio and selected sound hardware. Use 'help' to print all 43710adb8beSMarkus Armbrusteravailable sound hardware. 43810adb8beSMarkus Armbruster 43910adb8beSMarkus Armbruster@example 44010adb8beSMarkus Armbrusterqemu-system-i386 -soundhw sb16,adlib disk.img 44110adb8beSMarkus Armbrusterqemu-system-i386 -soundhw es1370 disk.img 44210adb8beSMarkus Armbrusterqemu-system-i386 -soundhw ac97 disk.img 44310adb8beSMarkus Armbrusterqemu-system-i386 -soundhw hda disk.img 44410adb8beSMarkus Armbrusterqemu-system-i386 -soundhw all disk.img 44510adb8beSMarkus Armbrusterqemu-system-i386 -soundhw help 44610adb8beSMarkus Armbruster@end example 44710adb8beSMarkus Armbruster 44810adb8beSMarkus ArmbrusterNote that Linux's i810_audio OSS kernel (for AC97) module might 44910adb8beSMarkus Armbrusterrequire manually specifying clocking. 45010adb8beSMarkus Armbruster 45110adb8beSMarkus Armbruster@example 45210adb8beSMarkus Armbrustermodprobe i810_audio clocking=48000 45310adb8beSMarkus Armbruster@end example 45410adb8beSMarkus ArmbrusterETEXI 45510adb8beSMarkus Armbruster 45610adb8beSMarkus ArmbrusterDEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 45710adb8beSMarkus Armbruster "-balloon none disable balloon device\n" 45810adb8beSMarkus Armbruster "-balloon virtio[,addr=str]\n" 45910adb8beSMarkus Armbruster " enable virtio balloon device (default)\n", QEMU_ARCH_ALL) 46010adb8beSMarkus ArmbrusterSTEXI 46110adb8beSMarkus Armbruster@item -balloon none 46210adb8beSMarkus Armbruster@findex -balloon 46310adb8beSMarkus ArmbrusterDisable balloon device. 46410adb8beSMarkus Armbruster@item -balloon virtio[,addr=@var{addr}] 46510adb8beSMarkus ArmbrusterEnable virtio balloon device (default), optionally with PCI address 46610adb8beSMarkus Armbruster@var{addr}. 46710adb8beSMarkus ArmbrusterETEXI 46810adb8beSMarkus Armbruster 46910adb8beSMarkus ArmbrusterDEF("device", HAS_ARG, QEMU_OPTION_device, 47010adb8beSMarkus Armbruster "-device driver[,prop[=value][,...]]\n" 47110adb8beSMarkus Armbruster " add device (based on driver)\n" 47210adb8beSMarkus Armbruster " prop=value,... sets driver properties\n" 47310adb8beSMarkus Armbruster " use '-device help' to print all possible drivers\n" 47410adb8beSMarkus Armbruster " use '-device driver,help' to print all possible properties\n", 47510adb8beSMarkus Armbruster QEMU_ARCH_ALL) 47610adb8beSMarkus ArmbrusterSTEXI 47710adb8beSMarkus Armbruster@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 47810adb8beSMarkus Armbruster@findex -device 47910adb8beSMarkus ArmbrusterAdd device @var{driver}. @var{prop}=@var{value} sets driver 48010adb8beSMarkus Armbrusterproperties. Valid properties depend on the driver. To get help on 48110adb8beSMarkus Armbrusterpossible drivers and properties, use @code{-device help} and 48210adb8beSMarkus Armbruster@code{-device @var{driver},help}. 483f8490451SCorey Minyard 484f8490451SCorey MinyardSome drivers are: 485540c07d3SCédric Le Goater@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}] 486f8490451SCorey Minyard 487f8490451SCorey MinyardAdd an IPMI BMC. This is a simulation of a hardware management 488f8490451SCorey Minyardinterface processor that normally sits on a system. It provides 489f8490451SCorey Minyarda watchdog and the ability to reset and power control the system. 490f8490451SCorey MinyardYou need to connect this to an IPMI interface to make it useful 491f8490451SCorey Minyard 492f8490451SCorey MinyardThe IPMI slave address to use for the BMC. The default is 0x20. 493f8490451SCorey MinyardThis address is the BMC's address on the I2C network of management 494f8490451SCorey Minyardcontrollers. If you don't know what this means, it is safe to ignore 495f8490451SCorey Minyardit. 496f8490451SCorey Minyard 4978c6fd7f3SCédric Le Goater@table @option 4988c6fd7f3SCédric Le Goater@item bmc=@var{id} 4998c6fd7f3SCédric Le GoaterThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 5008c6fd7f3SCédric Le Goater@item slave_addr=@var{val} 5018c6fd7f3SCédric Le GoaterDefine slave address to use for the BMC. The default is 0x20. 5028c6fd7f3SCédric Le Goater@item sdrfile=@var{file} 5038c6fd7f3SCédric Le Goaterfile containing raw Sensor Data Records (SDR) data. The default is none. 504540c07d3SCédric Le Goater@item fruareasize=@var{val} 505540c07d3SCédric Le Goatersize of a Field Replaceable Unit (FRU) area. The default is 1024. 506540c07d3SCédric Le Goater@item frudatafile=@var{file} 507540c07d3SCédric Le Goaterfile containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 5088c6fd7f3SCédric Le Goater@end table 5098c6fd7f3SCédric Le Goater 510f8490451SCorey Minyard@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 511f8490451SCorey Minyard 512f8490451SCorey MinyardAdd a connection to an external IPMI BMC simulator. Instead of 513f8490451SCorey Minyardlocally emulating the BMC like the above item, instead connect 514f8490451SCorey Minyardto an external entity that provides the IPMI services. 515f8490451SCorey Minyard 516f8490451SCorey MinyardA connection is made to an external BMC simulator. If you do this, it 517f8490451SCorey Minyardis strongly recommended that you use the "reconnect=" chardev option 518f8490451SCorey Minyardto reconnect to the simulator if the connection is lost. Note that if 519f8490451SCorey Minyardthis is not used carefully, it can be a security issue, as the 520f8490451SCorey Minyardinterface has the ability to send resets, NMIs, and power off the VM. 521f8490451SCorey MinyardIt's best if QEMU makes a connection to an external simulator running 522f8490451SCorey Minyardon a secure port on localhost, so neither the simulator nor QEMU is 523f8490451SCorey Minyardexposed to any outside network. 524f8490451SCorey Minyard 525f8490451SCorey MinyardSee the "lanserv/README.vm" file in the OpenIPMI library for more 526f8490451SCorey Minyarddetails on the external interface. 527f8490451SCorey Minyard 528f8490451SCorey Minyard@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 529f8490451SCorey Minyard 530f8490451SCorey MinyardAdd a KCS IPMI interafce on the ISA bus. This also adds a 531f8490451SCorey Minyardcorresponding ACPI and SMBIOS entries, if appropriate. 532f8490451SCorey Minyard 533f8490451SCorey Minyard@table @option 534f8490451SCorey Minyard@item bmc=@var{id} 535f8490451SCorey MinyardThe BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 536f8490451SCorey Minyard@item ioport=@var{val} 537f8490451SCorey MinyardDefine the I/O address of the interface. The default is 0xca0 for KCS. 538f8490451SCorey Minyard@item irq=@var{val} 539f8490451SCorey MinyardDefine the interrupt to use. The default is 5. To disable interrupts, 540f8490451SCorey Minyardset this to 0. 541f8490451SCorey Minyard@end table 542f8490451SCorey Minyard 543f8490451SCorey Minyard@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 544f8490451SCorey Minyard 545f8490451SCorey MinyardLike the KCS interface, but defines a BT interface. The default port is 546f8490451SCorey Minyard0xe4 and the default interrupt is 5. 547f8490451SCorey Minyard 54810adb8beSMarkus ArmbrusterETEXI 54910adb8beSMarkus Armbruster 55010adb8beSMarkus ArmbrusterDEF("name", HAS_ARG, QEMU_OPTION_name, 5518f480de0SDr. David Alan Gilbert "-name string1[,process=string2][,debug-threads=on|off]\n" 55210adb8beSMarkus Armbruster " set the name of the guest\n" 5538f480de0SDr. David Alan Gilbert " string1 sets the window title and string2 the process name (on Linux)\n" 5548f480de0SDr. David Alan Gilbert " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 5558f480de0SDr. David Alan Gilbert " NOTE: The thread names are for debugging and not a stable API.\n", 55610adb8beSMarkus Armbruster QEMU_ARCH_ALL) 55710adb8beSMarkus ArmbrusterSTEXI 55810adb8beSMarkus Armbruster@item -name @var{name} 55910adb8beSMarkus Armbruster@findex -name 56010adb8beSMarkus ArmbrusterSets the @var{name} of the guest. 56110adb8beSMarkus ArmbrusterThis name will be displayed in the SDL window caption. 56210adb8beSMarkus ArmbrusterThe @var{name} will also be used for the VNC server. 56310adb8beSMarkus ArmbrusterAlso optionally set the top visible process name in Linux. 5648f480de0SDr. David Alan GilbertNaming of individual threads can also be enabled on Linux to aid debugging. 56510adb8beSMarkus ArmbrusterETEXI 56610adb8beSMarkus Armbruster 56710adb8beSMarkus ArmbrusterDEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 56810adb8beSMarkus Armbruster "-uuid %08x-%04x-%04x-%04x-%012x\n" 56910adb8beSMarkus Armbruster " specify machine UUID\n", QEMU_ARCH_ALL) 57010adb8beSMarkus ArmbrusterSTEXI 57110adb8beSMarkus Armbruster@item -uuid @var{uuid} 57210adb8beSMarkus Armbruster@findex -uuid 57310adb8beSMarkus ArmbrusterSet system UUID. 57410adb8beSMarkus ArmbrusterETEXI 57510adb8beSMarkus Armbruster 57610adb8beSMarkus ArmbrusterSTEXI 57710adb8beSMarkus Armbruster@end table 57810adb8beSMarkus ArmbrusterETEXI 57910adb8beSMarkus ArmbrusterDEFHEADING() 58010adb8beSMarkus Armbruster 58143f187a5SPaolo BonziniDEFHEADING(Block device options) 58210adb8beSMarkus ArmbrusterSTEXI 58310adb8beSMarkus Armbruster@table @option 58410adb8beSMarkus ArmbrusterETEXI 58510adb8beSMarkus Armbruster 5865824d651Sblueswir1DEF("fda", HAS_ARG, QEMU_OPTION_fda, 587ad96090aSBlue Swirl "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 588ad96090aSBlue SwirlDEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 5895824d651Sblueswir1STEXI 5905824d651Sblueswir1@item -fda @var{file} 591f9cfd655SMarkus Armbruster@itemx -fdb @var{file} 5926616b2adSStefan Weil@findex -fda 5936616b2adSStefan Weil@findex -fdb 59492a539d2SMarkus ArmbrusterUse @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 5955824d651Sblueswir1ETEXI 5965824d651Sblueswir1 5975824d651Sblueswir1DEF("hda", HAS_ARG, QEMU_OPTION_hda, 598ad96090aSBlue Swirl "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 599ad96090aSBlue SwirlDEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 6005824d651Sblueswir1DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 601ad96090aSBlue Swirl "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 602ad96090aSBlue SwirlDEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 6035824d651Sblueswir1STEXI 6045824d651Sblueswir1@item -hda @var{file} 605f9cfd655SMarkus Armbruster@itemx -hdb @var{file} 606f9cfd655SMarkus Armbruster@itemx -hdc @var{file} 607f9cfd655SMarkus Armbruster@itemx -hdd @var{file} 6086616b2adSStefan Weil@findex -hda 6096616b2adSStefan Weil@findex -hdb 6106616b2adSStefan Weil@findex -hdc 6116616b2adSStefan Weil@findex -hdd 6125824d651Sblueswir1Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 6135824d651Sblueswir1ETEXI 6145824d651Sblueswir1 6155824d651Sblueswir1DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 616ad96090aSBlue Swirl "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 617ad96090aSBlue Swirl QEMU_ARCH_ALL) 6185824d651Sblueswir1STEXI 6195824d651Sblueswir1@item -cdrom @var{file} 6206616b2adSStefan Weil@findex -cdrom 6215824d651Sblueswir1Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 6225824d651Sblueswir1@option{-cdrom} at the same time). You can use the host CD-ROM by 6235824d651Sblueswir1using @file{/dev/cdrom} as filename (@pxref{host_drives}). 6245824d651Sblueswir1ETEXI 6255824d651Sblueswir1 62642e5f393SMarkus ArmbrusterDEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 62742e5f393SMarkus Armbruster "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 62842e5f393SMarkus Armbruster " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 62942e5f393SMarkus Armbruster " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n" 63042e5f393SMarkus Armbruster " [,driver specific parameters...]\n" 63142e5f393SMarkus Armbruster " configure a block backend\n", QEMU_ARCH_ALL) 632dfaca464SKevin WolfSTEXI 633dfaca464SKevin Wolf@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 634dfaca464SKevin Wolf@findex -blockdev 635dfaca464SKevin Wolf 636370e8328SKevin WolfDefine a new block driver node. Some of the options apply to all block drivers, 637370e8328SKevin Wolfother options are only accepted for a specific block driver. See below for a 638370e8328SKevin Wolflist of generic options and options for the most common block drivers. 639370e8328SKevin Wolf 640370e8328SKevin WolfOptions that expect a reference to another node (e.g. @code{file}) can be 641370e8328SKevin Wolfgiven in two ways. Either you specify the node name of an already existing node 642370e8328SKevin Wolf(file=@var{node-name}), or you define a new node inline, adding options 643370e8328SKevin Wolffor the referenced node after a dot (file.filename=@var{path},file.aio=native). 644370e8328SKevin Wolf 645370e8328SKevin WolfA block driver node created with @option{-blockdev} can be used for a guest 646370e8328SKevin Wolfdevice by specifying its node name for the @code{drive} property in a 647370e8328SKevin Wolf@option{-device} argument that defines a block device. 648dfaca464SKevin Wolf 649dfaca464SKevin Wolf@table @option 650dfaca464SKevin Wolf@item Valid options for any block driver node: 651dfaca464SKevin Wolf 652dfaca464SKevin Wolf@table @code 653dfaca464SKevin Wolf@item driver 654dfaca464SKevin WolfSpecifies the block driver to use for the given node. 655dfaca464SKevin Wolf@item node-name 656dfaca464SKevin WolfThis defines the name of the block driver node by which it will be referenced 657dfaca464SKevin Wolflater. The name must be unique, i.e. it must not match the name of a different 658dfaca464SKevin Wolfblock driver node, or (if you use @option{-drive} as well) the ID of a drive. 659dfaca464SKevin Wolf 660dfaca464SKevin WolfIf no node name is specified, it is automatically generated. The generated node 661dfaca464SKevin Wolfname is not intended to be predictable and changes between QEMU invocations. 662dfaca464SKevin WolfFor the top level, an explicit node name must be specified. 663dfaca464SKevin Wolf@item read-only 664dfaca464SKevin WolfOpen the node read-only. Guest write attempts will fail. 665dfaca464SKevin Wolf@item cache.direct 666dfaca464SKevin WolfThe host page cache can be avoided with @option{cache.direct=on}. This will 667dfaca464SKevin Wolfattempt to do disk IO directly to the guest's memory. QEMU may still perform an 668dfaca464SKevin Wolfinternal copy of the data. 669dfaca464SKevin Wolf@item cache.no-flush 670dfaca464SKevin WolfIn case you don't care about data integrity over host failures, you can use 671dfaca464SKevin Wolf@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 672dfaca464SKevin Wolfany data to the disk but can instead keep things in cache. If anything goes 673dfaca464SKevin Wolfwrong, like your host losing power, the disk storage getting disconnected 674dfaca464SKevin Wolfaccidentally, etc. your image will most probably be rendered unusable. 675dfaca464SKevin Wolf@item discard=@var{discard} 676dfaca464SKevin Wolf@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 677dfaca464SKevin Wolfwhether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 678dfaca464SKevin Wolfignored or passed to the filesystem. Some machine types may not support 679dfaca464SKevin Wolfdiscard requests. 680dfaca464SKevin Wolf@item detect-zeroes=@var{detect-zeroes} 681dfaca464SKevin Wolf@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 682dfaca464SKevin Wolfconversion of plain zero writes by the OS to driver specific optimized 683dfaca464SKevin Wolfzero write commands. You may even choose "unmap" if @var{discard} is set 684dfaca464SKevin Wolfto "unmap" to allow a zero write to be converted to an @code{unmap} operation. 685dfaca464SKevin Wolf@end table 686dfaca464SKevin Wolf 687370e8328SKevin Wolf@item Driver-specific options for @code{file} 688370e8328SKevin Wolf 689370e8328SKevin WolfThis is the protocol-level block driver for accessing regular files. 690370e8328SKevin Wolf 691370e8328SKevin Wolf@table @code 692370e8328SKevin Wolf@item filename 693370e8328SKevin WolfThe path to the image file in the local filesystem 694370e8328SKevin Wolf@item aio 695370e8328SKevin WolfSpecifies the AIO backend (threads/native, default: threads) 696*1878eaffSFam Zheng@item locking 697*1878eaffSFam ZhengSpecifies whether the image file is protected with Linux OFD / POSIX locks. The 698*1878eaffSFam Zhengdefault is to use the Linux Open File Descriptor API if available, otherwise no 699*1878eaffSFam Zhenglock is applied. (auto/on/off, default: auto) 700370e8328SKevin Wolf@end table 701370e8328SKevin WolfExample: 702370e8328SKevin Wolf@example 703370e8328SKevin Wolf-blockdev driver=file,node-name=disk,filename=disk.img 704370e8328SKevin Wolf@end example 705370e8328SKevin Wolf 706370e8328SKevin Wolf@item Driver-specific options for @code{raw} 707370e8328SKevin Wolf 708370e8328SKevin WolfThis is the image format block driver for raw images. It is usually 709370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 710370e8328SKevin Wolf 711370e8328SKevin Wolf@table @code 712370e8328SKevin Wolf@item file 713370e8328SKevin WolfReference to or definition of the data source block driver node 714370e8328SKevin Wolf(e.g. a @code{file} driver node) 715370e8328SKevin Wolf@end table 716370e8328SKevin WolfExample 1: 717370e8328SKevin Wolf@example 718370e8328SKevin Wolf-blockdev driver=file,node-name=disk_file,filename=disk.img 719370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file=disk_file 720370e8328SKevin Wolf@end example 721370e8328SKevin WolfExample 2: 722370e8328SKevin Wolf@example 723370e8328SKevin Wolf-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 724370e8328SKevin Wolf@end example 725370e8328SKevin Wolf 726370e8328SKevin Wolf@item Driver-specific options for @code{qcow2} 727370e8328SKevin Wolf 728370e8328SKevin WolfThis is the image format block driver for qcow2 images. It is usually 729370e8328SKevin Wolfstacked on top of a protocol level block driver such as @code{file}. 730370e8328SKevin Wolf 731370e8328SKevin Wolf@table @code 732370e8328SKevin Wolf@item file 733370e8328SKevin WolfReference to or definition of the data source block driver node 734370e8328SKevin Wolf(e.g. a @code{file} driver node) 735370e8328SKevin Wolf 736370e8328SKevin Wolf@item backing 737370e8328SKevin WolfReference to or definition of the backing file block device (default is taken 738370e8328SKevin Wolffrom the image file). It is allowed to pass an empty string here in order to 739370e8328SKevin Wolfdisable the default backing file. 740370e8328SKevin Wolf 741370e8328SKevin Wolf@item lazy-refcounts 742370e8328SKevin WolfWhether to enable the lazy refcounts feature (on/off; default is taken from the 743370e8328SKevin Wolfimage file) 744370e8328SKevin Wolf 745370e8328SKevin Wolf@item cache-size 746370e8328SKevin WolfThe maximum total size of the L2 table and refcount block caches in bytes 747370e8328SKevin Wolf(default: 1048576 bytes or 8 clusters, whichever is larger) 748370e8328SKevin Wolf 749370e8328SKevin Wolf@item l2-cache-size 750370e8328SKevin WolfThe maximum size of the L2 table cache in bytes 751370e8328SKevin Wolf(default: 4/5 of the total cache size) 752370e8328SKevin Wolf 753370e8328SKevin Wolf@item refcount-cache-size 754370e8328SKevin WolfThe maximum size of the refcount block cache in bytes 755370e8328SKevin Wolf(default: 1/5 of the total cache size) 756370e8328SKevin Wolf 757370e8328SKevin Wolf@item cache-clean-interval 758370e8328SKevin WolfClean unused entries in the L2 and refcount caches. The interval is in seconds. 759370e8328SKevin WolfThe default value is 0 and it disables this feature. 760370e8328SKevin Wolf 761370e8328SKevin Wolf@item pass-discard-request 762370e8328SKevin WolfWhether discard requests to the qcow2 device should be forwarded to the data 763370e8328SKevin Wolfsource (on/off; default: on if discard=unmap is specified, off otherwise) 764370e8328SKevin Wolf 765370e8328SKevin Wolf@item pass-discard-snapshot 766370e8328SKevin WolfWhether discard requests for the data source should be issued when a snapshot 767370e8328SKevin Wolfoperation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 768370e8328SKevin Wolfdefault: on) 769370e8328SKevin Wolf 770370e8328SKevin Wolf@item pass-discard-other 771370e8328SKevin WolfWhether discard requests for the data source should be issued on other 772370e8328SKevin Wolfoccasions where a cluster gets freed (on/off; default: off) 773370e8328SKevin Wolf 774370e8328SKevin Wolf@item overlap-check 775370e8328SKevin WolfWhich overlap checks to perform for writes to the image 776370e8328SKevin Wolf(none/constant/cached/all; default: cached). For details or finer 777370e8328SKevin Wolfgranularity control refer to the QAPI documentation of @code{blockdev-add}. 778370e8328SKevin Wolf@end table 779370e8328SKevin Wolf 780370e8328SKevin WolfExample 1: 781370e8328SKevin Wolf@example 782370e8328SKevin Wolf-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 783370e8328SKevin Wolf-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 784370e8328SKevin Wolf@end example 785370e8328SKevin WolfExample 2: 786370e8328SKevin Wolf@example 787370e8328SKevin Wolf-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 788370e8328SKevin Wolf@end example 789370e8328SKevin Wolf 790370e8328SKevin Wolf@item Driver-specific options for other drivers 791370e8328SKevin WolfPlease refer to the QAPI documentation of the @code{blockdev-add} QMP command. 792370e8328SKevin Wolf 793dfaca464SKevin Wolf@end table 794dfaca464SKevin Wolf 795dfaca464SKevin WolfETEXI 79642e5f393SMarkus Armbruster 7975824d651Sblueswir1DEF("drive", HAS_ARG, QEMU_OPTION_drive, 7985824d651Sblueswir1 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 7995824d651Sblueswir1 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" 80092196b2fSStefan Hajnoczi " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 801d1db760dSStefan Hajnoczi " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n" 802d1db760dSStefan Hajnoczi " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 803fb0490f6SStefan Hajnoczi " [,readonly=on|off][,copy-on-read=on|off]\n" 8042f7133b2SPeter Lieven " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 8053e9fab69SBenoît Canet " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 8063e9fab69SBenoît Canet " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 8073e9fab69SBenoît Canet " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 8083e9fab69SBenoît Canet " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 8092024c1dfSBenoît Canet " [[,iops_size=is]]\n" 81076f4afb4SAlberto Garcia " [[,group=g]]\n" 811ad96090aSBlue Swirl " use 'file' as a drive image\n", QEMU_ARCH_ALL) 8125824d651Sblueswir1STEXI 8135824d651Sblueswir1@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 8146616b2adSStefan Weil@findex -drive 8155824d651Sblueswir1 816dfaca464SKevin WolfDefine a new drive. This includes creating a block driver node (the backend) as 817dfaca464SKevin Wolfwell as a guest device, and is mostly a shortcut for defining the corresponding 818dfaca464SKevin Wolf@option{-blockdev} and @option{-device} options. 819dfaca464SKevin Wolf 820dfaca464SKevin Wolf@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 821dfaca464SKevin Wolfaddition, it knows the following options: 8225824d651Sblueswir1 823b3f046c2SKevin Wolf@table @option 8245824d651Sblueswir1@item file=@var{file} 8255824d651Sblueswir1This option defines which disk image (@pxref{disk_images}) to use with 8265824d651Sblueswir1this drive. If the filename contains comma, you must double it 8275824d651Sblueswir1(for instance, "file=my,,file" to use file "my,file"). 8280f5314a2SRonnie Sahlberg 8290f5314a2SRonnie SahlbergSpecial files such as iSCSI devices can be specified using protocol 8300f5314a2SRonnie Sahlbergspecific URLs. See the section for "Device URL Syntax" for more information. 8315824d651Sblueswir1@item if=@var{interface} 8325824d651Sblueswir1This option defines on which type on interface the drive is connected. 833ed1fcd00SCraig JellickAvailable types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 8345824d651Sblueswir1@item bus=@var{bus},unit=@var{unit} 8355824d651Sblueswir1These options define where is connected the drive by defining the bus number and 8365824d651Sblueswir1the unit id. 8375824d651Sblueswir1@item index=@var{index} 8385824d651Sblueswir1This option defines where is connected the drive by using an index in the list 8395824d651Sblueswir1of available connectors of a given interface type. 8405824d651Sblueswir1@item media=@var{media} 8415824d651Sblueswir1This option defines the type of the media: disk or cdrom. 8425824d651Sblueswir1@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] 8435824d651Sblueswir1These options have the same definition as they have in @option{-hdachs}. 844c616f16eSThomas HuthThese parameters are deprecated, use the corresponding parameters 845c616f16eSThomas Huthof @code{-device} instead. 8465824d651Sblueswir1@item snapshot=@var{snapshot} 8479d85d557SMichael Tokarev@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 8489d85d557SMichael Tokarev(see @option{-snapshot}). 8495824d651Sblueswir1@item cache=@var{cache} 850dfaca464SKevin Wolf@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 851dfaca464SKevin Wolfand controls how the host cache is used to access block data. This is a 852dfaca464SKevin Wolfshortcut that sets the @option{cache.direct} and @option{cache.no-flush} 853dfaca464SKevin Wolfoptions (as in @option{-blockdev}), and additionally @option{cache.writeback}, 854dfaca464SKevin Wolfwhich provides a default for the @option{write-cache} option of block guest 855dfaca464SKevin Wolfdevices (as in @option{-device}). The modes correspond to the following 856dfaca464SKevin Wolfsettings: 857dfaca464SKevin Wolf 858dfaca464SKevin Wolf@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 859dfaca464SKevin Wolf@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 860dfaca464SKevin Wolf@c and the HTML output. 861dfaca464SKevin Wolf@example 862dfaca464SKevin Wolf@ │ cache.writeback cache.direct cache.no-flush 863dfaca464SKevin Wolf─────────────┼───────────────────────────────────────────────── 864dfaca464SKevin Wolfwriteback │ on off off 865dfaca464SKevin Wolfnone │ on on off 866dfaca464SKevin Wolfwritethrough │ off off off 867dfaca464SKevin Wolfdirectsync │ off on off 868dfaca464SKevin Wolfunsafe │ on off on 869dfaca464SKevin Wolf@end example 870dfaca464SKevin Wolf 871dfaca464SKevin WolfThe default mode is @option{cache=writeback}. 872dfaca464SKevin Wolf 8735c6c3a6cSChristoph Hellwig@item aio=@var{aio} 8745c6c3a6cSChristoph Hellwig@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 8755824d651Sblueswir1@item format=@var{format} 8765824d651Sblueswir1Specify which disk @var{format} will be used rather than detecting 877d33c8a7dSMichael Tokarevthe format. Can be used to specify format=raw to avoid interpreting 8785824d651Sblueswir1an untrusted format header. 8795824d651Sblueswir1@item serial=@var{serial} 880c616f16eSThomas HuthThis option specifies the serial number to assign to the device. This 881c616f16eSThomas Huthparameter is deprecated, use the corresponding parameter of @code{-device} 882c616f16eSThomas Huthinstead. 883c2cc47a4SMarkus Armbruster@item addr=@var{addr} 884c616f16eSThomas HuthSpecify the controller's PCI address (if=virtio only). This parameter is 885c616f16eSThomas Huthdeprecated, use the corresponding parameter of @code{-device} instead. 886ae73e591SLuiz Capitulino@item werror=@var{action},rerror=@var{action} 887ae73e591SLuiz CapitulinoSpecify which @var{action} to take on write and read errors. Valid actions are: 888ae73e591SLuiz Capitulino"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 889ae73e591SLuiz Capitulino"report" (report the error to the guest), "enospc" (pause QEMU only if the 890ae73e591SLuiz Capitulinohost disk is full; report the error to the guest otherwise). 891ae73e591SLuiz CapitulinoThe default setting is @option{werror=enospc} and @option{rerror=report}. 892fb0490f6SStefan Hajnoczi@item copy-on-read=@var{copy-on-read} 893fb0490f6SStefan Hajnoczi@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 894fb0490f6SStefan Hajnoczifile sectors into the image file. 89501f9cfabSStefan Hajnoczi@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 89601f9cfabSStefan HajnocziSpecify bandwidth throttling limits in bytes per second, either for all request 89701f9cfabSStefan Hajnoczitypes or for reads or writes only. Small values can lead to timeouts or hangs 89801f9cfabSStefan Hajnocziinside the guest. A safe minimum for disks is 2 MB/s. 89901f9cfabSStefan Hajnoczi@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 90001f9cfabSStefan HajnocziSpecify bursts in bytes per second, either for all request types or for reads 90101f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 90201f9cfabSStefan Hajnoczitemporarily. 90301f9cfabSStefan Hajnoczi@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 90401f9cfabSStefan HajnocziSpecify request rate limits in requests per second, either for all request 90501f9cfabSStefan Hajnoczitypes or for reads or writes only. 90601f9cfabSStefan Hajnoczi@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 90701f9cfabSStefan HajnocziSpecify bursts in requests per second, either for all request types or for reads 90801f9cfabSStefan Hajnoczior writes only. Bursts allow the guest I/O to spike above the limit 90901f9cfabSStefan Hajnoczitemporarily. 91001f9cfabSStefan Hajnoczi@item iops_size=@var{is} 91101f9cfabSStefan HajnocziLet every @var{is} bytes of a request count as a new request for iops 91201f9cfabSStefan Hajnoczithrottling purposes. Use this option to prevent guests from circumventing iops 91301f9cfabSStefan Hajnoczilimits by sending fewer but larger requests. 91401f9cfabSStefan Hajnoczi@item group=@var{g} 91501f9cfabSStefan HajnocziJoin a throttling quota group with given name @var{g}. All drives that are 91601f9cfabSStefan Hajnoczimembers of the same group are accounted for together. Use this option to 91701f9cfabSStefan Hajnocziprevent guests from circumventing throttling limits by using many small disks 91801f9cfabSStefan Hajnocziinstead of a single larger disk. 9195824d651Sblueswir1@end table 9205824d651Sblueswir1 921dfaca464SKevin WolfBy default, the @option{cache.writeback=on} mode is used. It will report data 922a13e5e05SKevin Wolfwrites as completed as soon as the data is present in the host page cache. 923a13e5e05SKevin WolfThis is safe as long as your guest OS makes sure to correctly flush disk caches 924a13e5e05SKevin Wolfwhere needed. If your guest OS does not handle volatile disk write caches 925a13e5e05SKevin Wolfcorrectly and your host crashes or loses power, then the guest may experience 926a13e5e05SKevin Wolfdata corruption. 9275824d651Sblueswir1 928dfaca464SKevin WolfFor such guests, you should consider using @option{cache.writeback=off}. This 929a13e5e05SKevin Wolfmeans that the host page cache will be used to read and write data, but write 930a13e5e05SKevin Wolfnotification will be sent to the guest only after QEMU has made sure to flush 931a13e5e05SKevin Wolfeach write to the disk. Be aware that this has a major impact on performance. 9325824d651Sblueswir1 933dfaca464SKevin WolfWhen using the @option{-snapshot} option, unsafe caching is always used. 934016f5cf6SAlexander Graf 935fb0490f6SStefan HajnocziCopy-on-read avoids accessing the same backing file sectors repeatedly and is 936fb0490f6SStefan Hajnocziuseful when the backing file is over a slow network. By default copy-on-read 937fb0490f6SStefan Hajnocziis off. 938fb0490f6SStefan Hajnoczi 9395824d651Sblueswir1Instead of @option{-cdrom} you can use: 9405824d651Sblueswir1@example 9413804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=cdrom 9425824d651Sblueswir1@end example 9435824d651Sblueswir1 9445824d651Sblueswir1Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 9455824d651Sblueswir1use: 9465824d651Sblueswir1@example 9473804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,media=disk 9483804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,media=disk 9493804da9dSStefan Weilqemu-system-i386 -drive file=file,index=2,media=disk 9503804da9dSStefan Weilqemu-system-i386 -drive file=file,index=3,media=disk 9515824d651Sblueswir1@end example 9525824d651Sblueswir1 953587ed6beSCorey BryantYou can open an image using pre-opened file descriptors from an fd set: 954587ed6beSCorey Bryant@example 955587ed6beSCorey Bryantqemu-system-i386 956587ed6beSCorey Bryant-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 957587ed6beSCorey Bryant-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 958587ed6beSCorey Bryant-drive file=/dev/fdset/2,index=0,media=disk 959587ed6beSCorey Bryant@end example 960587ed6beSCorey Bryant 9615824d651Sblueswir1You can connect a CDROM to the slave of ide0: 9625824d651Sblueswir1@example 9633804da9dSStefan Weilqemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 9645824d651Sblueswir1@end example 9655824d651Sblueswir1 9665824d651Sblueswir1If you don't specify the "file=" argument, you define an empty drive: 9675824d651Sblueswir1@example 9683804da9dSStefan Weilqemu-system-i386 -drive if=ide,index=1,media=cdrom 9695824d651Sblueswir1@end example 9705824d651Sblueswir1 9715824d651Sblueswir1Instead of @option{-fda}, @option{-fdb}, you can use: 9725824d651Sblueswir1@example 9733804da9dSStefan Weilqemu-system-i386 -drive file=file,index=0,if=floppy 9743804da9dSStefan Weilqemu-system-i386 -drive file=file,index=1,if=floppy 9755824d651Sblueswir1@end example 9765824d651Sblueswir1 9775824d651Sblueswir1By default, @var{interface} is "ide" and @var{index} is automatically 9785824d651Sblueswir1incremented: 9795824d651Sblueswir1@example 9803804da9dSStefan Weilqemu-system-i386 -drive file=a -drive file=b" 9815824d651Sblueswir1@end example 9825824d651Sblueswir1is interpreted like: 9835824d651Sblueswir1@example 9843804da9dSStefan Weilqemu-system-i386 -hda a -hdb b 9855824d651Sblueswir1@end example 9865824d651Sblueswir1ETEXI 9875824d651Sblueswir1 9885824d651Sblueswir1DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 989ad96090aSBlue Swirl "-mtdblock file use 'file' as on-board Flash memory image\n", 990ad96090aSBlue Swirl QEMU_ARCH_ALL) 9915824d651Sblueswir1STEXI 9924e257e5eSKevin Wolf@item -mtdblock @var{file} 9936616b2adSStefan Weil@findex -mtdblock 9944e257e5eSKevin WolfUse @var{file} as on-board Flash memory image. 9955824d651Sblueswir1ETEXI 9965824d651Sblueswir1 9975824d651Sblueswir1DEF("sd", HAS_ARG, QEMU_OPTION_sd, 998ad96090aSBlue Swirl "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 9995824d651Sblueswir1STEXI 10004e257e5eSKevin Wolf@item -sd @var{file} 10016616b2adSStefan Weil@findex -sd 10024e257e5eSKevin WolfUse @var{file} as SecureDigital card image. 10035824d651Sblueswir1ETEXI 10045824d651Sblueswir1 10055824d651Sblueswir1DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 1006ad96090aSBlue Swirl "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 10075824d651Sblueswir1STEXI 10084e257e5eSKevin Wolf@item -pflash @var{file} 10096616b2adSStefan Weil@findex -pflash 10104e257e5eSKevin WolfUse @var{file} as a parallel flash image. 10115824d651Sblueswir1ETEXI 10125824d651Sblueswir1 10135824d651Sblueswir1DEF("snapshot", 0, QEMU_OPTION_snapshot, 1014ad96090aSBlue Swirl "-snapshot write to temporary files instead of disk image files\n", 1015ad96090aSBlue Swirl QEMU_ARCH_ALL) 10165824d651Sblueswir1STEXI 10175824d651Sblueswir1@item -snapshot 10186616b2adSStefan Weil@findex -snapshot 10195824d651Sblueswir1Write to temporary files instead of disk image files. In this case, 10205824d651Sblueswir1the raw disk image you use is not written back. You can however force 10215824d651Sblueswir1the write back by pressing @key{C-a s} (@pxref{disk_images}). 10225824d651Sblueswir1ETEXI 10235824d651Sblueswir1 102410adb8beSMarkus ArmbrusterDEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ 102510adb8beSMarkus Armbruster "-hdachs c,h,s[,t]\n" \ 102610adb8beSMarkus Armbruster " force hard disk 0 physical geometry and the optional BIOS\n" \ 102710adb8beSMarkus Armbruster " translation (t=none or lba) (usually QEMU can guess them)\n", 1028ad96090aSBlue Swirl QEMU_ARCH_ALL) 1029c902760fSMarcelo TosattiSTEXI 103010adb8beSMarkus Armbruster@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] 103110adb8beSMarkus Armbruster@findex -hdachs 103210adb8beSMarkus ArmbrusterForce hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= 103310adb8beSMarkus Armbruster@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS 103410adb8beSMarkus Armbrustertranslation mode (@var{t}=none, lba or auto). Usually QEMU can guess 1035aab9e87eSThomas Huthall those parameters. This option is deprecated, please use 1036aab9e87eSThomas Huth@code{-device ide-hd,cyls=c,heads=h,secs=s,...} instead. 1037c70a01e4SMarkus ArmbrusterETEXI 103874db920cSGautham R Shenoy 103974db920cSGautham R ShenoyDEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 10402c30dd74SAneesh Kumar K.V "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 1041b96feb2cSTobias Schramm " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n" 1042b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1043b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1044b8bbdb88SPradeep Jagadeesh " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1045b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1046b8bbdb88SPradeep Jagadeesh " [[,throttling.iops-size=is]]\n", 104774db920cSGautham R Shenoy QEMU_ARCH_ALL) 104874db920cSGautham R Shenoy 104974db920cSGautham R ShenoySTEXI 105074db920cSGautham R Shenoy 1051b96feb2cSTobias Schramm@item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}] 105274db920cSGautham R Shenoy@findex -fsdev 10537c92a3d2SAneesh Kumar K.VDefine a new file system device. Valid options are: 10547c92a3d2SAneesh Kumar K.V@table @option 10557c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 10567c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 1057f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 10587c92a3d2SAneesh Kumar K.V@item id=@var{id} 10597c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 10607c92a3d2SAneesh Kumar K.V@item path=@var{path} 10617c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 10627c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 10637c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 10647c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 10652c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 10667c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1067b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 10682c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 10697c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 10702c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 10712c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 10727c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 10737c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1074d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory 1075f67e3ffdSM. Mohan Kumaronly for local fsdriver. Other fsdrivers (like handle, proxy) don't take 1076d9b36a6eSM. Mohan Kumarsecurity model as a parameter. 10777c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 10787c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 10797c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 10807c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 10817c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 10822c74c2cbSM. Mohan Kumar@item readonly 10832c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 10842c74c2cbSM. Mohan Kumarread-write access is given. 108584a87cc4SM. Mohan Kumar@item socket=@var{socket} 108684a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for communicating 108784a87cc4SM. Mohan Kumarwith virtfs-proxy-helper 1088f67e3ffdSM. Mohan Kumar@item sock_fd=@var{sock_fd} 1089f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed socket descriptor for 1090f67e3ffdSM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 1091f67e3ffdSM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 1092b96feb2cSTobias Schramm@item fmode=@var{fmode} 1093b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1094b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1095b96feb2cSTobias Schramm@item dmode=@var{dmode} 1096b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1097b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 109874db920cSGautham R Shenoy@end table 10997c92a3d2SAneesh Kumar K.V 11007c92a3d2SAneesh Kumar K.V-fsdev option is used along with -device driver "virtio-9p-pci". 11017c92a3d2SAneesh Kumar K.V@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 11027c92a3d2SAneesh Kumar K.VOptions for virtio-9p-pci driver are: 11037c92a3d2SAneesh Kumar K.V@table @option 11047c92a3d2SAneesh Kumar K.V@item fsdev=@var{id} 11057c92a3d2SAneesh Kumar K.VSpecifies the id value specified along with -fsdev option 11067c92a3d2SAneesh Kumar K.V@item mount_tag=@var{mount_tag} 11077c92a3d2SAneesh Kumar K.VSpecifies the tag name to be used by the guest to mount this export point 11087c92a3d2SAneesh Kumar K.V@end table 11097c92a3d2SAneesh Kumar K.V 111074db920cSGautham R ShenoyETEXI 111174db920cSGautham R Shenoy 11123d54abc7SGautham R ShenoyDEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 11132c30dd74SAneesh Kumar K.V "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 1114b96feb2cSTobias Schramm " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n", 11153d54abc7SGautham R Shenoy QEMU_ARCH_ALL) 11163d54abc7SGautham R Shenoy 11173d54abc7SGautham R ShenoySTEXI 11183d54abc7SGautham R Shenoy 1119b96feb2cSTobias Schramm@item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}] 11203d54abc7SGautham R Shenoy@findex -virtfs 11213d54abc7SGautham R Shenoy 11227c92a3d2SAneesh Kumar K.VThe general form of a Virtual File system pass-through options are: 11237c92a3d2SAneesh Kumar K.V@table @option 11247c92a3d2SAneesh Kumar K.V@item @var{fsdriver} 11257c92a3d2SAneesh Kumar K.VThis option specifies the fs driver backend to use. 1126f67e3ffdSM. Mohan KumarCurrently "local", "handle" and "proxy" file system drivers are supported. 11277c92a3d2SAneesh Kumar K.V@item id=@var{id} 11287c92a3d2SAneesh Kumar K.VSpecifies identifier for this device 11297c92a3d2SAneesh Kumar K.V@item path=@var{path} 11307c92a3d2SAneesh Kumar K.VSpecifies the export path for the file system device. Files under 11317c92a3d2SAneesh Kumar K.Vthis path will be available to the 9p client on the guest. 11327c92a3d2SAneesh Kumar K.V@item security_model=@var{security_model} 11337c92a3d2SAneesh Kumar K.VSpecifies the security model to be used for this export path. 11342c30dd74SAneesh Kumar K.VSupported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 11357c92a3d2SAneesh Kumar K.VIn "passthrough" security model, files are stored using the same 1136b65ee4faSStefan Weilcredentials as they are created on the guest. This requires QEMU 11372c30dd74SAneesh Kumar K.Vto run as root. In "mapped-xattr" security model, some of the file 11387c92a3d2SAneesh Kumar K.Vattributes like uid, gid, mode bits and link target are stored as 11392c30dd74SAneesh Kumar K.Vfile attributes. For "mapped-file" these attributes are stored in the 11402c30dd74SAneesh Kumar K.Vhidden .virtfs_metadata directory. Directories exported by this security model cannot 11417c92a3d2SAneesh Kumar K.Vinteract with other unix tools. "none" security model is same as 11427c92a3d2SAneesh Kumar K.Vpassthrough except the sever won't report failures if it fails to 1143d9b36a6eSM. Mohan Kumarset file attributes like ownership. Security model is mandatory only 1144f67e3ffdSM. Mohan Kumarfor local fsdriver. Other fsdrivers (like handle, proxy) don't take security 1145d9b36a6eSM. Mohan Kumarmodel as a parameter. 11467c92a3d2SAneesh Kumar K.V@item writeout=@var{writeout} 11477c92a3d2SAneesh Kumar K.VThis is an optional argument. The only supported value is "immediate". 11487c92a3d2SAneesh Kumar K.VThis means that host page cache will be used to read and write data but 11497c92a3d2SAneesh Kumar K.Vwrite notification will be sent to the guest only when the data has been 11507c92a3d2SAneesh Kumar K.Vreported as written by the storage subsystem. 11512c74c2cbSM. Mohan Kumar@item readonly 11522c74c2cbSM. Mohan KumarEnables exporting 9p share as a readonly mount for guests. By default 11532c74c2cbSM. Mohan Kumarread-write access is given. 115484a87cc4SM. Mohan Kumar@item socket=@var{socket} 115584a87cc4SM. Mohan KumarEnables proxy filesystem driver to use passed socket file for 115684a87cc4SM. Mohan Kumarcommunicating with virtfs-proxy-helper. Usually a helper like libvirt 115784a87cc4SM. Mohan Kumarwill create socketpair and pass one of the fds as sock_fd 1158f67e3ffdSM. Mohan Kumar@item sock_fd 1159f67e3ffdSM. Mohan KumarEnables proxy filesystem driver to use passed 'sock_fd' as the socket 1160f67e3ffdSM. Mohan Kumardescriptor for interfacing with virtfs-proxy-helper 1161b96feb2cSTobias Schramm@item fmode=@var{fmode} 1162b96feb2cSTobias SchrammSpecifies the default mode for newly created files on the host. Works only 1163b96feb2cSTobias Schrammwith security models "mapped-xattr" and "mapped-file". 1164b96feb2cSTobias Schramm@item dmode=@var{dmode} 1165b96feb2cSTobias SchrammSpecifies the default mode for newly created directories on the host. Works 1166b96feb2cSTobias Schrammonly with security models "mapped-xattr" and "mapped-file". 11673d54abc7SGautham R Shenoy@end table 11683d54abc7SGautham R ShenoyETEXI 11693d54abc7SGautham R Shenoy 11709db221aeSAneesh Kumar K.VDEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 11719db221aeSAneesh Kumar K.V "-virtfs_synth Create synthetic file system image\n", 11729db221aeSAneesh Kumar K.V QEMU_ARCH_ALL) 11739db221aeSAneesh Kumar K.VSTEXI 11749db221aeSAneesh Kumar K.V@item -virtfs_synth 11759db221aeSAneesh Kumar K.V@findex -virtfs_synth 11769db221aeSAneesh Kumar K.VCreate synthetic file system image 11779db221aeSAneesh Kumar K.VETEXI 11789db221aeSAneesh Kumar K.V 11795824d651Sblueswir1STEXI 11805824d651Sblueswir1@end table 11815824d651Sblueswir1ETEXI 11825824d651Sblueswir1DEFHEADING() 11835824d651Sblueswir1 118443f187a5SPaolo BonziniDEFHEADING(USB options) 118510adb8beSMarkus ArmbrusterSTEXI 118610adb8beSMarkus Armbruster@table @option 118710adb8beSMarkus ArmbrusterETEXI 118810adb8beSMarkus Armbruster 118910adb8beSMarkus ArmbrusterDEF("usb", 0, QEMU_OPTION_usb, 1190a358a3afSThomas Huth "-usb enable the USB driver (if it is not used by default yet)\n", 119110adb8beSMarkus Armbruster QEMU_ARCH_ALL) 119210adb8beSMarkus ArmbrusterSTEXI 119310adb8beSMarkus Armbruster@item -usb 119410adb8beSMarkus Armbruster@findex -usb 1195a358a3afSThomas HuthEnable the USB driver (if it is not used by default yet). 119610adb8beSMarkus ArmbrusterETEXI 119710adb8beSMarkus Armbruster 119810adb8beSMarkus ArmbrusterDEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 119910adb8beSMarkus Armbruster "-usbdevice name add the host or guest USB device 'name'\n", 120010adb8beSMarkus Armbruster QEMU_ARCH_ALL) 120110adb8beSMarkus ArmbrusterSTEXI 120210adb8beSMarkus Armbruster 120310adb8beSMarkus Armbruster@item -usbdevice @var{devname} 120410adb8beSMarkus Armbruster@findex -usbdevice 1205a358a3afSThomas HuthAdd the USB device @var{devname}. Note that this option is deprecated, 1206a358a3afSThomas Huthplease use @code{-device usb-...} instead. @xref{usb_devices}. 120710adb8beSMarkus Armbruster 120810adb8beSMarkus Armbruster@table @option 120910adb8beSMarkus Armbruster 121010adb8beSMarkus Armbruster@item mouse 121110adb8beSMarkus ArmbrusterVirtual Mouse. This will override the PS/2 mouse emulation when activated. 121210adb8beSMarkus Armbruster 121310adb8beSMarkus Armbruster@item tablet 121410adb8beSMarkus ArmbrusterPointer device that uses absolute coordinates (like a touchscreen). This 121510adb8beSMarkus Armbrustermeans QEMU is able to report the mouse position without having to grab the 121610adb8beSMarkus Armbrustermouse. Also overrides the PS/2 mouse emulation when activated. 121710adb8beSMarkus Armbruster 121810adb8beSMarkus Armbruster@item disk:[format=@var{format}]:@var{file} 121910adb8beSMarkus ArmbrusterMass storage device based on file. The optional @var{format} argument 1220d33c8a7dSMichael Tokarevwill be used rather than detecting the format. Can be used to specify 122110adb8beSMarkus Armbruster@code{format=raw} to avoid interpreting an untrusted format header. 122210adb8beSMarkus Armbruster 122310adb8beSMarkus Armbruster@item host:@var{bus}.@var{addr} 122410adb8beSMarkus ArmbrusterPass through the host device identified by @var{bus}.@var{addr} (Linux only). 122510adb8beSMarkus Armbruster 122610adb8beSMarkus Armbruster@item host:@var{vendor_id}:@var{product_id} 122710adb8beSMarkus ArmbrusterPass through the host device identified by @var{vendor_id}:@var{product_id} 122810adb8beSMarkus Armbruster(Linux only). 122910adb8beSMarkus Armbruster 123010adb8beSMarkus Armbruster@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} 123110adb8beSMarkus ArmbrusterSerial converter to host character device @var{dev}, see @code{-serial} for the 123210adb8beSMarkus Armbrusteravailable devices. 123310adb8beSMarkus Armbruster 123410adb8beSMarkus Armbruster@item braille 123510adb8beSMarkus ArmbrusterBraille device. This will use BrlAPI to display the braille output on a real 123610adb8beSMarkus Armbrusteror fake device. 123710adb8beSMarkus Armbruster 123810adb8beSMarkus Armbruster@item net:@var{options} 123910adb8beSMarkus ArmbrusterNetwork adapter that supports CDC ethernet and RNDIS protocols. 124010adb8beSMarkus Armbruster 124110adb8beSMarkus Armbruster@end table 124210adb8beSMarkus ArmbrusterETEXI 124310adb8beSMarkus Armbruster 124410adb8beSMarkus ArmbrusterSTEXI 124510adb8beSMarkus Armbruster@end table 124610adb8beSMarkus ArmbrusterETEXI 124710adb8beSMarkus ArmbrusterDEFHEADING() 124810adb8beSMarkus Armbruster 124943f187a5SPaolo BonziniDEFHEADING(Display options) 12505824d651Sblueswir1STEXI 12515824d651Sblueswir1@table @option 12525824d651Sblueswir1ETEXI 12535824d651Sblueswir1 12541472a95bSJes SorensenDEF("display", HAS_ARG, QEMU_OPTION_display, 12551472a95bSJes Sorensen "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 125687eb2bacSSamuel Thibault " [,window_close=on|off][,gl=on|off]\n" 1257f04ec5afSRobert Ho "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 1258f04ec5afSRobert Ho "-display vnc=<display>[,<optargs>]\n" 1259f04ec5afSRobert Ho "-display curses\n" 1260f04ec5afSRobert Ho "-display none" 1261f04ec5afSRobert Ho " select display type\n" 1262f04ec5afSRobert Ho "The default display is equivalent to\n" 1263f04ec5afSRobert Ho#if defined(CONFIG_GTK) 1264f04ec5afSRobert Ho "\t\"-display gtk\"\n" 1265f04ec5afSRobert Ho#elif defined(CONFIG_SDL) 1266f04ec5afSRobert Ho "\t\"-display sdl\"\n" 1267f04ec5afSRobert Ho#elif defined(CONFIG_COCOA) 1268f04ec5afSRobert Ho "\t\"-display cocoa\"\n" 1269f04ec5afSRobert Ho#elif defined(CONFIG_VNC) 1270f04ec5afSRobert Ho "\t\"-vnc localhost:0,to=99,id=default\"\n" 1271f04ec5afSRobert Ho#else 1272f04ec5afSRobert Ho "\t\"-display none\"\n" 1273f04ec5afSRobert Ho#endif 1274f04ec5afSRobert Ho , QEMU_ARCH_ALL) 12751472a95bSJes SorensenSTEXI 12761472a95bSJes Sorensen@item -display @var{type} 12771472a95bSJes Sorensen@findex -display 12781472a95bSJes SorensenSelect type of display to use. This option is a replacement for the 12791472a95bSJes Sorensenold style -sdl/-curses/... options. Valid values for @var{type} are 12801472a95bSJes Sorensen@table @option 12811472a95bSJes Sorensen@item sdl 12821472a95bSJes SorensenDisplay video output via SDL (usually in a separate graphics 12831472a95bSJes Sorensenwindow; see the SDL documentation for other possibilities). 12841472a95bSJes Sorensen@item curses 12851472a95bSJes SorensenDisplay video output via curses. For graphics device models which 12861472a95bSJes Sorensensupport a text mode, QEMU can display this output using a 12871472a95bSJes Sorensencurses/ncurses interface. Nothing is displayed when the graphics 12881472a95bSJes Sorensendevice is in graphical mode or if the graphics device does not support 12891472a95bSJes Sorensena text mode. Generally only the VGA device models support text mode. 12904171d32eSJes Sorensen@item none 12914171d32eSJes SorensenDo not display video output. The guest will still see an emulated 12924171d32eSJes Sorensengraphics card, but its output will not be displayed to the QEMU 12934171d32eSJes Sorensenuser. This option differs from the -nographic option in that it 12944171d32eSJes Sorensenonly affects what is done with video output; -nographic also changes 12954171d32eSJes Sorensenthe destination of the serial and parallel port data. 1296881249c7SJan Kiszka@item gtk 1297881249c7SJan KiszkaDisplay video output in a GTK window. This interface provides drop-down 1298881249c7SJan Kiszkamenus and other UI elements to configure and control the VM during 1299881249c7SJan Kiszkaruntime. 13003264ff12SJes Sorensen@item vnc 13013264ff12SJes SorensenStart a VNC server on display <arg> 13021472a95bSJes Sorensen@end table 13031472a95bSJes SorensenETEXI 13041472a95bSJes Sorensen 13055824d651Sblueswir1DEF("nographic", 0, QEMU_OPTION_nographic, 1306ad96090aSBlue Swirl "-nographic disable graphical output and redirect serial I/Os to console\n", 1307ad96090aSBlue Swirl QEMU_ARCH_ALL) 13085824d651Sblueswir1STEXI 13095824d651Sblueswir1@item -nographic 13106616b2adSStefan Weil@findex -nographic 1311dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1312dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1313dc0a3e44SColin Lordwindow. With this option, you can totally disable graphical output so 1314dc0a3e44SColin Lordthat QEMU is a simple command line application. The emulated serial port 1315dc0a3e44SColin Lordis redirected on the console and muxed with the monitor (unless 1316dc0a3e44SColin Lordredirected elsewhere explicitly). Therefore, you can still use QEMU to 1317dc0a3e44SColin Lorddebug a Linux kernel with a serial console. Use @key{C-a h} for help on 1318dc0a3e44SColin Lordswitching between the console and monitor. 13195824d651Sblueswir1ETEXI 13205824d651Sblueswir1 13215824d651Sblueswir1DEF("curses", 0, QEMU_OPTION_curses, 1322f04ec5afSRobert Ho "-curses shorthand for -display curses\n", 1323ad96090aSBlue Swirl QEMU_ARCH_ALL) 13245824d651Sblueswir1STEXI 13255824d651Sblueswir1@item -curses 1326b8f490ebSMarkus Armbruster@findex -curses 1327dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1328dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1329dc0a3e44SColin Lordwindow. With this option, QEMU can display the VGA output when in text 1330dc0a3e44SColin Lordmode using a curses/ncurses interface. Nothing is displayed in graphical 1331dc0a3e44SColin Lordmode. 13325824d651Sblueswir1ETEXI 13335824d651Sblueswir1 13345824d651Sblueswir1DEF("no-frame", 0, QEMU_OPTION_no_frame, 1335ad96090aSBlue Swirl "-no-frame open SDL window without a frame and window decorations\n", 1336ad96090aSBlue Swirl QEMU_ARCH_ALL) 13375824d651Sblueswir1STEXI 13385824d651Sblueswir1@item -no-frame 13396616b2adSStefan Weil@findex -no-frame 13405824d651Sblueswir1Do not use decorations for SDL windows and start them using the whole 13415824d651Sblueswir1available screen space. This makes the using QEMU in a dedicated desktop 13425824d651Sblueswir1workspace more convenient. 13435824d651Sblueswir1ETEXI 13445824d651Sblueswir1 13455824d651Sblueswir1DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1346ad96090aSBlue Swirl "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1347ad96090aSBlue Swirl QEMU_ARCH_ALL) 13485824d651Sblueswir1STEXI 13495824d651Sblueswir1@item -alt-grab 13506616b2adSStefan Weil@findex -alt-grab 1351de1db2a1SBrad HardsUse Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1352de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 13535824d651Sblueswir1ETEXI 13545824d651Sblueswir1 13550ca9f8a4SDustin KirklandDEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1356ad96090aSBlue Swirl "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1357ad96090aSBlue Swirl QEMU_ARCH_ALL) 13580ca9f8a4SDustin KirklandSTEXI 13590ca9f8a4SDustin Kirkland@item -ctrl-grab 13606616b2adSStefan Weil@findex -ctrl-grab 1361de1db2a1SBrad HardsUse Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1362de1db2a1SBrad Hardsaffects the special keys (for fullscreen, monitor-mode switching, etc). 13630ca9f8a4SDustin KirklandETEXI 13640ca9f8a4SDustin Kirkland 13655824d651Sblueswir1DEF("no-quit", 0, QEMU_OPTION_no_quit, 1366ad96090aSBlue Swirl "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 13675824d651Sblueswir1STEXI 13685824d651Sblueswir1@item -no-quit 13696616b2adSStefan Weil@findex -no-quit 13705824d651Sblueswir1Disable SDL window close capability. 13715824d651Sblueswir1ETEXI 13725824d651Sblueswir1 13735824d651Sblueswir1DEF("sdl", 0, QEMU_OPTION_sdl, 1374f04ec5afSRobert Ho "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 13755824d651Sblueswir1STEXI 13765824d651Sblueswir1@item -sdl 13776616b2adSStefan Weil@findex -sdl 13785824d651Sblueswir1Enable SDL. 13795824d651Sblueswir1ETEXI 13805824d651Sblueswir1 138129b0040bSGerd HoffmannDEF("spice", HAS_ARG, QEMU_OPTION_spice, 138227af7788SYonit Halperin "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 138327af7788SYonit Halperin " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 138427af7788SYonit Halperin " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1385fe4831b1SMarc-André Lureau " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 138627af7788SYonit Halperin " [,tls-ciphers=<list>]\n" 138727af7788SYonit Halperin " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 138827af7788SYonit Halperin " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 138927af7788SYonit Halperin " [,sasl][,password=<secret>][,disable-ticketing]\n" 139027af7788SYonit Halperin " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 139127af7788SYonit Halperin " [,jpeg-wan-compression=[auto|never|always]]\n" 139227af7788SYonit Halperin " [,zlib-glz-wan-compression=[auto|never|always]]\n" 139327af7788SYonit Halperin " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 13945ad24e5fSHans de Goede " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 13955ad24e5fSHans de Goede " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 13967b525508SMarc-André Lureau " [,gl=[on|off]][,rendernode=<file>]\n" 139727af7788SYonit Halperin " enable spice\n" 139827af7788SYonit Halperin " at least one of {port, tls-port} is mandatory\n", 139927af7788SYonit Halperin QEMU_ARCH_ALL) 140029b0040bSGerd HoffmannSTEXI 140129b0040bSGerd Hoffmann@item -spice @var{option}[,@var{option}[,...]] 140229b0040bSGerd Hoffmann@findex -spice 140329b0040bSGerd HoffmannEnable the spice remote desktop protocol. Valid options are 140429b0040bSGerd Hoffmann 140529b0040bSGerd Hoffmann@table @option 140629b0040bSGerd Hoffmann 140729b0040bSGerd Hoffmann@item port=<nr> 1408c448e855SGerd HoffmannSet the TCP port spice is listening on for plaintext channels. 140929b0040bSGerd Hoffmann 1410333b0eebSGerd Hoffmann@item addr=<addr> 1411333b0eebSGerd HoffmannSet the IP address spice is listening on. Default is any address. 1412333b0eebSGerd Hoffmann 1413333b0eebSGerd Hoffmann@item ipv4 1414f9cfd655SMarkus Armbruster@itemx ipv6 1415f9cfd655SMarkus Armbruster@itemx unix 1416333b0eebSGerd HoffmannForce using the specified IP version. 1417333b0eebSGerd Hoffmann 141829b0040bSGerd Hoffmann@item password=<secret> 141929b0040bSGerd HoffmannSet the password you need to authenticate. 142029b0040bSGerd Hoffmann 142148b3ed0aSMarc-André Lureau@item sasl 142248b3ed0aSMarc-André LureauRequire that the client use SASL to authenticate with the spice. 142348b3ed0aSMarc-André LureauThe exact choice of authentication method used is controlled from the 142448b3ed0aSMarc-André Lureausystem / user's SASL configuration file for the 'qemu' service. This 142548b3ed0aSMarc-André Lureauis typically found in /etc/sasl2/qemu.conf. If running QEMU as an 142648b3ed0aSMarc-André Lureauunprivileged user, an environment variable SASL_CONF_PATH can be used 142748b3ed0aSMarc-André Lureauto make it search alternate locations for the service config. 142848b3ed0aSMarc-André LureauWhile some SASL auth methods can also provide data encryption (eg GSSAPI), 142948b3ed0aSMarc-André Lureauit is recommended that SASL always be combined with the 'tls' and 143048b3ed0aSMarc-André Lureau'x509' settings to enable use of SSL and server certificates. This 143148b3ed0aSMarc-André Lureauensures a data encryption preventing compromise of authentication 143248b3ed0aSMarc-André Lureaucredentials. 143348b3ed0aSMarc-André Lureau 143429b0040bSGerd Hoffmann@item disable-ticketing 143529b0040bSGerd HoffmannAllow client connects without authentication. 143629b0040bSGerd Hoffmann 1437d4970b07SHans de Goede@item disable-copy-paste 1438d4970b07SHans de GoedeDisable copy paste between the client and the guest. 1439d4970b07SHans de Goede 14405ad24e5fSHans de Goede@item disable-agent-file-xfer 14415ad24e5fSHans de GoedeDisable spice-vdagent based file-xfer between the client and the guest. 14425ad24e5fSHans de Goede 1443c448e855SGerd Hoffmann@item tls-port=<nr> 1444c448e855SGerd HoffmannSet the TCP port spice is listening on for encrypted channels. 1445c448e855SGerd Hoffmann 1446c448e855SGerd Hoffmann@item x509-dir=<dir> 1447c448e855SGerd HoffmannSet the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1448c448e855SGerd Hoffmann 1449c448e855SGerd Hoffmann@item x509-key-file=<file> 1450f9cfd655SMarkus Armbruster@itemx x509-key-password=<file> 1451f9cfd655SMarkus Armbruster@itemx x509-cert-file=<file> 1452f9cfd655SMarkus Armbruster@itemx x509-cacert-file=<file> 1453f9cfd655SMarkus Armbruster@itemx x509-dh-key-file=<file> 1454c448e855SGerd HoffmannThe x509 file names can also be configured individually. 1455c448e855SGerd Hoffmann 1456c448e855SGerd Hoffmann@item tls-ciphers=<list> 1457c448e855SGerd HoffmannSpecify which ciphers to use. 1458c448e855SGerd Hoffmann 1459d70d6b31SAlon Levy@item tls-channel=[main|display|cursor|inputs|record|playback] 1460f9cfd655SMarkus Armbruster@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 146117b6dea0SGerd HoffmannForce specific channel to be used with or without TLS encryption. The 146217b6dea0SGerd Hoffmannoptions can be specified multiple times to configure multiple 146317b6dea0SGerd Hoffmannchannels. The special name "default" can be used to set the default 146417b6dea0SGerd Hoffmannmode. For channels which are not explicitly forced into one mode the 146517b6dea0SGerd Hoffmannspice client is allowed to pick tls/plaintext as he pleases. 146617b6dea0SGerd Hoffmann 14679f04e09eSYonit Halperin@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 14689f04e09eSYonit HalperinConfigure image compression (lossless). 14699f04e09eSYonit HalperinDefault is auto_glz. 14709f04e09eSYonit Halperin 14719f04e09eSYonit Halperin@item jpeg-wan-compression=[auto|never|always] 1472f9cfd655SMarkus Armbruster@itemx zlib-glz-wan-compression=[auto|never|always] 14739f04e09eSYonit HalperinConfigure wan image compression (lossy for slow links). 14749f04e09eSYonit HalperinDefault is auto. 14759f04e09eSYonit Halperin 147684a23f25SGerd Hoffmann@item streaming-video=[off|all|filter] 147793ca519eSLi ZhijianConfigure video stream detection. Default is off. 147884a23f25SGerd Hoffmann 147984a23f25SGerd Hoffmann@item agent-mouse=[on|off] 148084a23f25SGerd HoffmannEnable/disable passing mouse events via vdagent. Default is on. 148184a23f25SGerd Hoffmann 148284a23f25SGerd Hoffmann@item playback-compression=[on|off] 148384a23f25SGerd HoffmannEnable/disable audio stream compression (using celt 0.5.1). Default is on. 148484a23f25SGerd Hoffmann 14858c957053SYonit Halperin@item seamless-migration=[on|off] 14868c957053SYonit HalperinEnable/disable spice seamless migration. Default is off. 14878c957053SYonit Halperin 1488474114b7SGerd Hoffmann@item gl=[on|off] 1489474114b7SGerd HoffmannEnable/disable OpenGL context. Default is off. 1490474114b7SGerd Hoffmann 14917b525508SMarc-André Lureau@item rendernode=<file> 14927b525508SMarc-André LureauDRM render node for OpenGL rendering. If not specified, it will pick 14937b525508SMarc-André Lureauthe first available. (Since 2.9) 14947b525508SMarc-André Lureau 149529b0040bSGerd Hoffmann@end table 149629b0040bSGerd HoffmannETEXI 149729b0040bSGerd Hoffmann 14985824d651Sblueswir1DEF("portrait", 0, QEMU_OPTION_portrait, 1499ad96090aSBlue Swirl "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1500ad96090aSBlue Swirl QEMU_ARCH_ALL) 15015824d651Sblueswir1STEXI 15025824d651Sblueswir1@item -portrait 15036616b2adSStefan Weil@findex -portrait 15045824d651Sblueswir1Rotate graphical output 90 deg left (only PXA LCD). 15055824d651Sblueswir1ETEXI 15065824d651Sblueswir1 15079312805dSVasily KhoruzhickDEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 15089312805dSVasily Khoruzhick "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 15099312805dSVasily Khoruzhick QEMU_ARCH_ALL) 15109312805dSVasily KhoruzhickSTEXI 15116265c43bSMarkus Armbruster@item -rotate @var{deg} 15129312805dSVasily Khoruzhick@findex -rotate 15139312805dSVasily KhoruzhickRotate graphical output some deg left (only PXA LCD). 15149312805dSVasily KhoruzhickETEXI 15159312805dSVasily Khoruzhick 15165824d651Sblueswir1DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1517a94f0c5cSGerd Hoffmann "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1518ad96090aSBlue Swirl " select video card type\n", QEMU_ARCH_ALL) 15195824d651Sblueswir1STEXI 1520e4558dcaSmalc@item -vga @var{type} 15216616b2adSStefan Weil@findex -vga 15225824d651Sblueswir1Select type of VGA card to emulate. Valid values for @var{type} are 1523b3f046c2SKevin Wolf@table @option 15245824d651Sblueswir1@item cirrus 15255824d651Sblueswir1Cirrus Logic GD5446 Video card. All Windows versions starting from 15265824d651Sblueswir1Windows 95 should recognize and use this graphic card. For optimal 15275824d651Sblueswir1performances, use 16 bit color depth in the guest and the host OS. 152841eeb0e6SAlberto Garcia(This card was the default before QEMU 2.2) 15295824d651Sblueswir1@item std 15305824d651Sblueswir1Standard VGA card with Bochs VBE extensions. If your guest OS 15315824d651Sblueswir1supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 15325824d651Sblueswir1to use high resolution modes (>= 1280x1024x16) then you should use 153341eeb0e6SAlberto Garciathis option. (This card is the default since QEMU 2.2) 15345824d651Sblueswir1@item vmware 15355824d651Sblueswir1VMWare SVGA-II compatible adapter. Use it if you have sufficiently 15365824d651Sblueswir1recent XFree86/XOrg server or Windows guest with a driver for this 15375824d651Sblueswir1card. 1538a19cbfb3SGerd Hoffmann@item qxl 1539a19cbfb3SGerd HoffmannQXL paravirtual graphic card. It is VGA compatible (including VESA 1540a19cbfb3SGerd Hoffmann2.0 VBE support). Works best with qxl guest drivers installed though. 1541a19cbfb3SGerd HoffmannRecommended choice when using the spice protocol. 154233632788SMark Cave-Ayland@item tcx 154333632788SMark Cave-Ayland(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 154433632788SMark Cave-Aylandsun4m machines and offers both 8-bit and 24-bit colour depths at a 154533632788SMark Cave-Aylandfixed resolution of 1024x768. 154633632788SMark Cave-Ayland@item cg3 154733632788SMark Cave-Ayland(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 154833632788SMark Cave-Aylandfor sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 154933632788SMark Cave-Aylandresolutions aimed at people wishing to run older Solaris versions. 1550a94f0c5cSGerd Hoffmann@item virtio 1551a94f0c5cSGerd HoffmannVirtio VGA card. 15525824d651Sblueswir1@item none 15535824d651Sblueswir1Disable VGA card. 15545824d651Sblueswir1@end table 15555824d651Sblueswir1ETEXI 15565824d651Sblueswir1 15575824d651Sblueswir1DEF("full-screen", 0, QEMU_OPTION_full_screen, 1558ad96090aSBlue Swirl "-full-screen start in full screen\n", QEMU_ARCH_ALL) 15595824d651Sblueswir1STEXI 15605824d651Sblueswir1@item -full-screen 15616616b2adSStefan Weil@findex -full-screen 15625824d651Sblueswir1Start in full screen. 15635824d651Sblueswir1ETEXI 15645824d651Sblueswir1 15655824d651Sblueswir1DEF("g", 1, QEMU_OPTION_g , 1566ad96090aSBlue Swirl "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1567ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 15685824d651Sblueswir1STEXI 156995d5f08bSStefan Weil@item -g @var{width}x@var{height}[x@var{depth}] 15706616b2adSStefan Weil@findex -g 157195d5f08bSStefan WeilSet the initial graphical resolution and depth (PPC, SPARC only). 15725824d651Sblueswir1ETEXI 15735824d651Sblueswir1 15745824d651Sblueswir1DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1575f04ec5afSRobert Ho "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 15765824d651Sblueswir1STEXI 15775824d651Sblueswir1@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 15786616b2adSStefan Weil@findex -vnc 1579dc0a3e44SColin LordNormally, if QEMU is compiled with graphical window support, it displays 1580dc0a3e44SColin Lordoutput such as guest graphics, guest console, and the QEMU monitor in a 1581dc0a3e44SColin Lordwindow. With this option, you can have QEMU listen on VNC display 1582dc0a3e44SColin Lord@var{display} and redirect the VGA display over the VNC session. It is 1583dc0a3e44SColin Lordvery useful to enable the usb tablet device when using this option 1584a358a3afSThomas Huth(option @option{-device usb-tablet}). When using the VNC display, you 1585dc0a3e44SColin Lordmust use the @option{-k} parameter to set the keyboard layout if you are 1586dc0a3e44SColin Lordnot using en-us. Valid syntax for the @var{display} is 15875824d651Sblueswir1 1588b3f046c2SKevin Wolf@table @option 15895824d651Sblueswir1 159099a9a52aSRobert Ho@item to=@var{L} 159199a9a52aSRobert Ho 159299a9a52aSRobert HoWith this option, QEMU will try next available VNC @var{display}s, until the 159399a9a52aSRobert Honumber @var{L}, if the origianlly defined "-vnc @var{display}" is not 159499a9a52aSRobert Hoavailable, e.g. port 5900+@var{display} is already used by another 159599a9a52aSRobert Hoapplication. By default, to=0. 159699a9a52aSRobert Ho 15975824d651Sblueswir1@item @var{host}:@var{d} 15985824d651Sblueswir1 15995824d651Sblueswir1TCP connections will only be allowed from @var{host} on display @var{d}. 16005824d651Sblueswir1By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 16015824d651Sblueswir1be omitted in which case the server will accept connections from any host. 16025824d651Sblueswir1 16034e257e5eSKevin Wolf@item unix:@var{path} 16045824d651Sblueswir1 16055824d651Sblueswir1Connections will be allowed over UNIX domain sockets where @var{path} is the 16065824d651Sblueswir1location of a unix socket to listen for connections on. 16075824d651Sblueswir1 16085824d651Sblueswir1@item none 16095824d651Sblueswir1 16105824d651Sblueswir1VNC is initialized but not started. The monitor @code{change} command 16115824d651Sblueswir1can be used to later start the VNC server. 16125824d651Sblueswir1 16135824d651Sblueswir1@end table 16145824d651Sblueswir1 16155824d651Sblueswir1Following the @var{display} value there may be one or more @var{option} flags 16165824d651Sblueswir1separated by commas. Valid options are 16175824d651Sblueswir1 1618b3f046c2SKevin Wolf@table @option 16195824d651Sblueswir1 16205824d651Sblueswir1@item reverse 16215824d651Sblueswir1 16225824d651Sblueswir1Connect to a listening VNC client via a ``reverse'' connection. The 16235824d651Sblueswir1client is specified by the @var{display}. For reverse network 16245824d651Sblueswir1connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 16255824d651Sblueswir1is a TCP port number, not a display number. 16265824d651Sblueswir1 16277536ee4bSTim Hardeck@item websocket 16287536ee4bSTim Hardeck 16297536ee4bSTim HardeckOpens an additional TCP listening port dedicated to VNC Websocket connections. 1630275e0d61SDaniel P. BerrangeIf a bare @var{websocket} option is given, the Websocket port is 1631275e0d61SDaniel P. Berrange5700+@var{display}. An alternative port can be specified with the 1632275e0d61SDaniel P. Berrangesyntax @code{websocket}=@var{port}. 1633275e0d61SDaniel P. Berrange 1634275e0d61SDaniel P. BerrangeIf @var{host} is specified connections will only be allowed from this host. 1635275e0d61SDaniel P. BerrangeIt is possible to control the websocket listen address independently, using 1636275e0d61SDaniel P. Berrangethe syntax @code{websocket}=@var{host}:@var{port}. 1637275e0d61SDaniel P. Berrange 16383e305e4aSDaniel P. BerrangeIf no TLS credentials are provided, the websocket connection runs in 16393e305e4aSDaniel P. Berrangeunencrypted mode. If TLS credentials are provided, the websocket connection 16403e305e4aSDaniel P. Berrangerequires encrypted client connections. 16417536ee4bSTim Hardeck 16425824d651Sblueswir1@item password 16435824d651Sblueswir1 16445824d651Sblueswir1Require that password based authentication is used for client connections. 164586ee5bc3SMichal Novotny 164686ee5bc3SMichal NovotnyThe password must be set separately using the @code{set_password} command in 164786ee5bc3SMichal Novotnythe @ref{pcsys_monitor}. The syntax to change your password is: 164886ee5bc3SMichal Novotny@code{set_password <protocol> <password>} where <protocol> could be either 164986ee5bc3SMichal Novotny"vnc" or "spice". 165086ee5bc3SMichal Novotny 165186ee5bc3SMichal NovotnyIf you would like to change <protocol> password expiration, you should use 165286ee5bc3SMichal Novotny@code{expire_password <protocol> <expiration-time>} where expiration time could 165386ee5bc3SMichal Novotnybe one of the following options: now, never, +seconds or UNIX time of 165486ee5bc3SMichal Novotnyexpiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 165586ee5bc3SMichal Novotnyto make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 165686ee5bc3SMichal Novotnydate and time). 165786ee5bc3SMichal Novotny 165886ee5bc3SMichal NovotnyYou can also use keywords "now" or "never" for the expiration time to 165986ee5bc3SMichal Novotnyallow <protocol> password to expire immediately or never expire. 16605824d651Sblueswir1 16613e305e4aSDaniel P. Berrange@item tls-creds=@var{ID} 16623e305e4aSDaniel P. Berrange 16633e305e4aSDaniel P. BerrangeProvides the ID of a set of TLS credentials to use to secure the 16643e305e4aSDaniel P. BerrangeVNC server. They will apply to both the normal VNC server socket 16653e305e4aSDaniel P. Berrangeand the websocket socket (if enabled). Setting TLS credentials 16663e305e4aSDaniel P. Berrangewill cause the VNC server socket to enable the VeNCrypt auth 16673e305e4aSDaniel P. Berrangemechanism. The credentials should have been previously created 16683e305e4aSDaniel P. Berrangeusing the @option{-object tls-creds} argument. 16693e305e4aSDaniel P. Berrange 16703e305e4aSDaniel P. BerrangeThe @option{tls-creds} parameter obsoletes the @option{tls}, 16713e305e4aSDaniel P. Berrange@option{x509}, and @option{x509verify} options, and as such 16723e305e4aSDaniel P. Berrangeit is not permitted to set both new and old type options at 16733e305e4aSDaniel P. Berrangethe same time. 16743e305e4aSDaniel P. Berrange 16755824d651Sblueswir1@item tls 16765824d651Sblueswir1 16775824d651Sblueswir1Require that client use TLS when communicating with the VNC server. This 16785824d651Sblueswir1uses anonymous TLS credentials so is susceptible to a man-in-the-middle 16795824d651Sblueswir1attack. It is recommended that this option be combined with either the 16804e257e5eSKevin Wolf@option{x509} or @option{x509verify} options. 16815824d651Sblueswir1 16823e305e4aSDaniel P. BerrangeThis option is now deprecated in favor of using the @option{tls-creds} 16833e305e4aSDaniel P. Berrangeargument. 16843e305e4aSDaniel P. Berrange 16855824d651Sblueswir1@item x509=@var{/path/to/certificate/dir} 16865824d651Sblueswir1 16875824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 16885824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 16895824d651Sblueswir1to the client. It is recommended that a password be set on the VNC server 16905824d651Sblueswir1to provide authentication of the client when this is used. The path following 16915824d651Sblueswir1this option specifies where the x509 certificates are to be loaded from. 16925824d651Sblueswir1See the @ref{vnc_security} section for details on generating certificates. 16935824d651Sblueswir1 16943e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 16953e305e4aSDaniel P. Berrangeargument. 16963e305e4aSDaniel P. Berrange 16975824d651Sblueswir1@item x509verify=@var{/path/to/certificate/dir} 16985824d651Sblueswir1 16995824d651Sblueswir1Valid if @option{tls} is specified. Require that x509 credentials are used 17005824d651Sblueswir1for negotiating the TLS session. The server will send its x509 certificate 17015824d651Sblueswir1to the client, and request that the client send its own x509 certificate. 17025824d651Sblueswir1The server will validate the client's certificate against the CA certificate, 17035824d651Sblueswir1and reject clients when validation fails. If the certificate authority is 17045824d651Sblueswir1trusted, this is a sufficient authentication mechanism. You may still wish 17055824d651Sblueswir1to set a password on the VNC server as a second authentication layer. The 17065824d651Sblueswir1path following this option specifies where the x509 certificates are to 17075824d651Sblueswir1be loaded from. See the @ref{vnc_security} section for details on generating 17085824d651Sblueswir1certificates. 17095824d651Sblueswir1 17103e305e4aSDaniel P. BerrangeThis option is now deprecated in favour of using the @option{tls-creds} 17113e305e4aSDaniel P. Berrangeargument. 17123e305e4aSDaniel P. Berrange 17135824d651Sblueswir1@item sasl 17145824d651Sblueswir1 17155824d651Sblueswir1Require that the client use SASL to authenticate with the VNC server. 17165824d651Sblueswir1The exact choice of authentication method used is controlled from the 17175824d651Sblueswir1system / user's SASL configuration file for the 'qemu' service. This 17185824d651Sblueswir1is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 17195824d651Sblueswir1unprivileged user, an environment variable SASL_CONF_PATH can be used 17205824d651Sblueswir1to make it search alternate locations for the service config. 17215824d651Sblueswir1While some SASL auth methods can also provide data encryption (eg GSSAPI), 17225824d651Sblueswir1it is recommended that SASL always be combined with the 'tls' and 17235824d651Sblueswir1'x509' settings to enable use of SSL and server certificates. This 17245824d651Sblueswir1ensures a data encryption preventing compromise of authentication 17255824d651Sblueswir1credentials. See the @ref{vnc_security} section for details on using 17265824d651Sblueswir1SASL authentication. 17275824d651Sblueswir1 17285824d651Sblueswir1@item acl 17295824d651Sblueswir1 17305824d651Sblueswir1Turn on access control lists for checking of the x509 client certificate 17315824d651Sblueswir1and SASL party. For x509 certs, the ACL check is made against the 17325824d651Sblueswir1certificate's distinguished name. This is something that looks like 17335824d651Sblueswir1@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 17345824d651Sblueswir1made against the username, which depending on the SASL plugin, may 17355824d651Sblueswir1include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 17365824d651Sblueswir1When the @option{acl} flag is set, the initial access list will be 17375824d651Sblueswir1empty, with a @code{deny} policy. Thus no one will be allowed to 17385824d651Sblueswir1use the VNC server until the ACLs have been loaded. This can be 17395824d651Sblueswir1achieved using the @code{acl} monitor command. 17405824d651Sblueswir1 17416f9c78c1SCorentin Chary@item lossy 17426f9c78c1SCorentin Chary 17436f9c78c1SCorentin CharyEnable lossy compression methods (gradient, JPEG, ...). If this 17446f9c78c1SCorentin Charyoption is set, VNC client may receive lossy framebuffer updates 17456f9c78c1SCorentin Charydepending on its encoding settings. Enabling this option can save 17466f9c78c1SCorentin Charya lot of bandwidth at the expense of quality. 17476f9c78c1SCorentin Chary 174880e0c8c3SCorentin Chary@item non-adaptive 174980e0c8c3SCorentin Chary 175080e0c8c3SCorentin CharyDisable adaptive encodings. Adaptive encodings are enabled by default. 175180e0c8c3SCorentin CharyAn adaptive encoding will try to detect frequently updated screen regions, 175280e0c8c3SCorentin Charyand send updates in these regions using a lossy encoding (like JPEG). 175361cc8701SStefan WeilThis can be really helpful to save bandwidth when playing videos. Disabling 17549d85d557SMichael Tokarevadaptive encodings restores the original static behavior of encodings 175580e0c8c3SCorentin Charylike Tight. 175680e0c8c3SCorentin Chary 17578cf36489SGerd Hoffmann@item share=[allow-exclusive|force-shared|ignore] 17588cf36489SGerd Hoffmann 17598cf36489SGerd HoffmannSet display sharing policy. 'allow-exclusive' allows clients to ask 17608cf36489SGerd Hoffmannfor exclusive access. As suggested by the rfb spec this is 17618cf36489SGerd Hoffmannimplemented by dropping other connections. Connecting multiple 17628cf36489SGerd Hoffmannclients in parallel requires all clients asking for a shared session 17638cf36489SGerd Hoffmann(vncviewer: -shared switch). This is the default. 'force-shared' 17648cf36489SGerd Hoffmanndisables exclusive client access. Useful for shared desktop sessions, 17658cf36489SGerd Hoffmannwhere you don't want someone forgetting specify -shared disconnect 17668cf36489SGerd Hoffmanneverybody else. 'ignore' completely ignores the shared flag and 17678cf36489SGerd Hoffmannallows everybody connect unconditionally. Doesn't conform to the rfb 1768b65ee4faSStefan Weilspec but is traditional QEMU behavior. 17698cf36489SGerd Hoffmann 1770c5ce8333SGerd Hoffmann@item key-delay-ms 1771c5ce8333SGerd Hoffmann 1772c5ce8333SGerd HoffmannSet keyboard delay, for key down and key up events, in milliseconds. 1773d3b0db6dSAlexander GrafDefault is 10. Keyboards are low-bandwidth devices, so this slowdown 1774c5ce8333SGerd Hoffmanncan help the device and guest to keep up and not lose events in case 1775c5ce8333SGerd Hoffmannevents are arriving in bulk. Possible causes for the latter are flaky 1776c5ce8333SGerd Hoffmannnetwork connections, or scripts for automated testing. 1777c5ce8333SGerd Hoffmann 17785824d651Sblueswir1@end table 17795824d651Sblueswir1ETEXI 17805824d651Sblueswir1 17815824d651Sblueswir1STEXI 17825824d651Sblueswir1@end table 17835824d651Sblueswir1ETEXI 1784a3adb7adSMichael EllermanARCHHEADING(, QEMU_ARCH_I386) 17855824d651Sblueswir1 178643f187a5SPaolo BonziniARCHHEADING(i386 target only, QEMU_ARCH_I386) 17875824d651Sblueswir1STEXI 17885824d651Sblueswir1@table @option 17895824d651Sblueswir1ETEXI 17905824d651Sblueswir1 17915824d651Sblueswir1DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1792ad96090aSBlue Swirl "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1793ad96090aSBlue Swirl QEMU_ARCH_I386) 17945824d651Sblueswir1STEXI 17955824d651Sblueswir1@item -win2k-hack 17966616b2adSStefan Weil@findex -win2k-hack 17975824d651Sblueswir1Use it when installing Windows 2000 to avoid a disk full bug. After 17985824d651Sblueswir1Windows 2000 is installed, you no longer need this option (this option 17995824d651Sblueswir1slows down the IDE transfers). 18005824d651Sblueswir1ETEXI 18015824d651Sblueswir1 18021ed2fc1fSJan KiszkaHXCOMM Deprecated by -rtc 1803ad96090aSBlue SwirlDEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 18045824d651Sblueswir1 18055824d651Sblueswir1DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1806ad96090aSBlue Swirl "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1807ad96090aSBlue Swirl QEMU_ARCH_I386) 18085824d651Sblueswir1STEXI 18095824d651Sblueswir1@item -no-fd-bootchk 18106616b2adSStefan Weil@findex -no-fd-bootchk 18114eda32f5SMarkus ArmbrusterDisable boot signature checking for floppy disks in BIOS. May 18125824d651Sblueswir1be needed to boot from old floppy disks. 18135824d651Sblueswir1ETEXI 18145824d651Sblueswir1 18155824d651Sblueswir1DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1816f5d8c8cdSShannon Zhao "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 18175824d651Sblueswir1STEXI 18185824d651Sblueswir1@item -no-acpi 18196616b2adSStefan Weil@findex -no-acpi 18205824d651Sblueswir1Disable ACPI (Advanced Configuration and Power Interface) support. Use 18215824d651Sblueswir1it if your guest OS complains about ACPI problems (PC target machine 18225824d651Sblueswir1only). 18235824d651Sblueswir1ETEXI 18245824d651Sblueswir1 18255824d651Sblueswir1DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1826ad96090aSBlue Swirl "-no-hpet disable HPET\n", QEMU_ARCH_I386) 18275824d651Sblueswir1STEXI 18285824d651Sblueswir1@item -no-hpet 18296616b2adSStefan Weil@findex -no-hpet 18305824d651Sblueswir1Disable HPET support. 18315824d651Sblueswir1ETEXI 18325824d651Sblueswir1 18335824d651Sblueswir1DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1834104bf02eSMichael 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" 1835ad96090aSBlue Swirl " ACPI table description\n", QEMU_ARCH_I386) 18365824d651Sblueswir1STEXI 18375824d651Sblueswir1@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}]...] 18386616b2adSStefan Weil@findex -acpitable 18395824d651Sblueswir1Add ACPI table with specified header fields and context from specified files. 1840104bf02eSMichael TokarevFor file=, take whole ACPI table from the specified files, including all 1841104bf02eSMichael TokarevACPI headers (possible overridden by other options). 1842104bf02eSMichael TokarevFor data=, only data 1843104bf02eSMichael Tokarevportion of the table is used, all header information is specified in the 1844104bf02eSMichael Tokarevcommand line. 1845ae123749SLaszlo ErsekIf a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 1846ae123749SLaszlo Ersekfields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 1847ae123749SLaszlo Ersekto ensure the field matches required by the Microsoft SLIC spec and the ACPI 1848ae123749SLaszlo Ersekspec. 18495824d651Sblueswir1ETEXI 18505824d651Sblueswir1 1851b6f6e3d3SaliguoriDEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1852b6f6e3d3Saliguori "-smbios file=binary\n" 1853ca1a8a06SBruce Rogers " load SMBIOS entry from binary file\n" 1854b155eb1dSGabriel L. Somlo "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1855b155eb1dSGabriel L. Somlo " [,uefi=on|off]\n" 1856ca1a8a06SBruce Rogers " specify SMBIOS type 0 fields\n" 1857b6f6e3d3Saliguori "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1858b6f6e3d3Saliguori " [,uuid=uuid][,sku=str][,family=str]\n" 1859b155eb1dSGabriel L. Somlo " specify SMBIOS type 1 fields\n" 1860b155eb1dSGabriel L. Somlo "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1861b155eb1dSGabriel L. Somlo " [,asset=str][,location=str]\n" 1862b155eb1dSGabriel L. Somlo " specify SMBIOS type 2 fields\n" 1863b155eb1dSGabriel L. Somlo "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1864b155eb1dSGabriel L. Somlo " [,sku=str]\n" 1865b155eb1dSGabriel L. Somlo " specify SMBIOS type 3 fields\n" 1866b155eb1dSGabriel L. Somlo "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1867b155eb1dSGabriel L. Somlo " [,asset=str][,part=str]\n" 1868b155eb1dSGabriel L. Somlo " specify SMBIOS type 4 fields\n" 1869b155eb1dSGabriel L. Somlo "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 18703ebd6cc8SGabriel L. Somlo " [,asset=str][,part=str][,speed=%d]\n" 1871b155eb1dSGabriel L. Somlo " specify SMBIOS type 17 fields\n", 1872c30e1565SWei Huang QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1873b6f6e3d3SaliguoriSTEXI 1874b6f6e3d3Saliguori@item -smbios file=@var{binary} 18756616b2adSStefan Weil@findex -smbios 1876b6f6e3d3SaliguoriLoad SMBIOS entry from binary file. 1877b6f6e3d3Saliguori 187884351843SGabriel L. Somlo@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1879b6f6e3d3SaliguoriSpecify SMBIOS type 0 fields 1880b6f6e3d3Saliguori 1881b6f6e3d3Saliguori@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}] 1882b6f6e3d3SaliguoriSpecify SMBIOS type 1 fields 1883b155eb1dSGabriel L. Somlo 1884b155eb1dSGabriel L. Somlo@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}] 1885b155eb1dSGabriel L. SomloSpecify SMBIOS type 2 fields 1886b155eb1dSGabriel L. Somlo 1887b155eb1dSGabriel L. Somlo@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1888b155eb1dSGabriel L. SomloSpecify SMBIOS type 3 fields 1889b155eb1dSGabriel L. Somlo 1890b155eb1dSGabriel 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}] 1891b155eb1dSGabriel L. SomloSpecify SMBIOS type 4 fields 1892b155eb1dSGabriel L. Somlo 18933ebd6cc8SGabriel 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}] 1894b155eb1dSGabriel L. SomloSpecify SMBIOS type 17 fields 1895b6f6e3d3SaliguoriETEXI 1896b6f6e3d3Saliguori 18975824d651Sblueswir1STEXI 18985824d651Sblueswir1@end table 18995824d651Sblueswir1ETEXI 1900c70a01e4SMarkus ArmbrusterDEFHEADING() 19015824d651Sblueswir1 190243f187a5SPaolo BonziniDEFHEADING(Network options) 19035824d651Sblueswir1STEXI 19045824d651Sblueswir1@table @option 19055824d651Sblueswir1ETEXI 19065824d651Sblueswir1 1907ad196a9dSJan KiszkaHXCOMM Legacy slirp options (now moved to -net user): 1908ad196a9dSJan Kiszka#ifdef CONFIG_SLIRP 1909ad96090aSBlue SwirlDEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1910ad96090aSBlue SwirlDEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1911ad96090aSBlue SwirlDEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1912ad196a9dSJan Kiszka#ifndef _WIN32 1913ad96090aSBlue SwirlDEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1914ad196a9dSJan Kiszka#endif 1915ad196a9dSJan Kiszka#endif 1916ad196a9dSJan Kiszka 19176a8b4a5bSThomas HuthDEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 19185824d651Sblueswir1#ifdef CONFIG_SLIRP 19190b11c036SSamuel Thibault "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 19200b11c036SSamuel Thibault " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 19210b11c036SSamuel Thibault " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 1922d8eb3864SSamuel Thibault " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n" 192363d2960bSKlaus Stengel " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1924ad196a9dSJan Kiszka#ifndef _WIN32 1925c92ef6a2SJan Kiszka "[,smb=dir[,smbserver=addr]]\n" 1926ad196a9dSJan Kiszka#endif 19276a8b4a5bSThomas Huth " configure a user mode network backend with ID 'str',\n" 19286a8b4a5bSThomas Huth " its DHCP server and optional services\n" 19295824d651Sblueswir1#endif 19305824d651Sblueswir1#ifdef _WIN32 19316a8b4a5bSThomas Huth "-netdev tap,id=str,ifname=name\n" 19326a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 19335824d651Sblueswir1#else 19346a8b4a5bSThomas Huth "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 1935584613eaSAlexey Kardashevskiy " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 19366a8b4a5bSThomas Huth " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 193769e87b32SJason Wang " [,poll-us=n]\n" 19386a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str'\n" 1939584613eaSAlexey Kardashevskiy " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 1940a7c36ee4SCorey Bryant " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1941a7c36ee4SCorey Bryant " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1942a7c36ee4SCorey Bryant " to deconfigure it\n" 1943ca1a8a06SBruce Rogers " use '[down]script=no' to disable script execution\n" 1944a7c36ee4SCorey Bryant " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1945a7c36ee4SCorey Bryant " configure it\n" 19465824d651Sblueswir1 " use 'fd=h' to connect to an already opened TAP interface\n" 19472ca81baaSJason Wang " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1948ca1a8a06SBruce Rogers " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1949f157ed20SMichael S. Tsirkin " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1950ca1a8a06SBruce Rogers " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1951ca1a8a06SBruce Rogers " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 195282b0d80eSMichael S. Tsirkin " use vhost=on to enable experimental in kernel accelerator\n" 19535430a28fSmst@redhat.com " (only has effect for virtio guests which use MSIX)\n" 19545430a28fSmst@redhat.com " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 195582b0d80eSMichael S. Tsirkin " use 'vhostfd=h' to connect to an already opened vhost net device\n" 19562ca81baaSJason Wang " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1957ec396014SJason Wang " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 195869e87b32SJason Wang " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 195969e87b32SJason Wang " spent on busy polling for vhost net\n" 19606a8b4a5bSThomas Huth "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 19616a8b4a5bSThomas Huth " configure a host TAP network backend with ID 'str' that is\n" 19626a8b4a5bSThomas Huth " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 19636a8b4a5bSThomas Huth " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 19640df0ff6dSMark McLoughlin#endif 19653fb69aa1SAnton Ivanov#ifdef __linux__ 19666a8b4a5bSThomas Huth "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 19676a8b4a5bSThomas Huth " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 19686a8b4a5bSThomas Huth " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 19696a8b4a5bSThomas Huth " [,rxcookie=rxcookie][,offset=offset]\n" 19706a8b4a5bSThomas Huth " configure a network backend with ID 'str' connected to\n" 19716a8b4a5bSThomas Huth " an Ethernet over L2TPv3 pseudowire.\n" 19723fb69aa1SAnton Ivanov " Linux kernel 3.3+ as well as most routers can talk\n" 19732f47b403SMichael Tokarev " L2TPv3. This transport allows connecting a VM to a VM,\n" 19743fb69aa1SAnton Ivanov " VM to a router and even VM to Host. It is a nearly-universal\n" 19753fb69aa1SAnton Ivanov " standard (RFC3391). Note - this implementation uses static\n" 19763fb69aa1SAnton Ivanov " pre-configured tunnels (same as the Linux kernel).\n" 19773fb69aa1SAnton Ivanov " use 'src=' to specify source address\n" 19783fb69aa1SAnton Ivanov " use 'dst=' to specify destination address\n" 19793fb69aa1SAnton Ivanov " use 'udp=on' to specify udp encapsulation\n" 19803952651aSGonglei " use 'srcport=' to specify source udp port\n" 19813fb69aa1SAnton Ivanov " use 'dstport=' to specify destination udp port\n" 19823fb69aa1SAnton Ivanov " use 'ipv6=on' to force v6\n" 19833fb69aa1SAnton Ivanov " L2TPv3 uses cookies to prevent misconfiguration as\n" 19843fb69aa1SAnton Ivanov " well as a weak security measure\n" 19853fb69aa1SAnton Ivanov " use 'rxcookie=0x012345678' to specify a rxcookie\n" 19863fb69aa1SAnton Ivanov " use 'txcookie=0x012345678' to specify a txcookie\n" 19873fb69aa1SAnton Ivanov " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 19883fb69aa1SAnton Ivanov " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 19893fb69aa1SAnton Ivanov " use 'pincounter=on' to work around broken counter handling in peer\n" 19903fb69aa1SAnton Ivanov " use 'offset=X' to add an extra offset between header and data\n" 19913fb69aa1SAnton Ivanov#endif 19926a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 19936a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 19946a8b4a5bSThomas Huth " using a socket connection\n" 19956a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 19966a8b4a5bSThomas Huth " configure a network backend to connect to a multicast maddr and port\n" 19973a75e74cSMike Ryan " use 'localaddr=addr' to specify the host address to send packets from\n" 19986a8b4a5bSThomas Huth "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 19996a8b4a5bSThomas Huth " configure a network backend to connect to another network\n" 20006a8b4a5bSThomas Huth " using an UDP tunnel\n" 20015824d651Sblueswir1#ifdef CONFIG_VDE 20026a8b4a5bSThomas Huth "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 20036a8b4a5bSThomas Huth " configure a network backend to connect to port 'n' of a vde switch\n" 20046a8b4a5bSThomas Huth " running on host and listening for incoming connections on 'socketpath'.\n" 20055824d651Sblueswir1 " Use group 'groupname' and mode 'octalmode' to change default\n" 20065824d651Sblueswir1 " ownership and permissions for communication port.\n" 20075824d651Sblueswir1#endif 200858952137SVincenzo Maffione#ifdef CONFIG_NETMAP 20096a8b4a5bSThomas Huth "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 201058952137SVincenzo Maffione " attach to the existing netmap-enabled network interface 'name', or to a\n" 201158952137SVincenzo Maffione " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 201258952137SVincenzo Maffione " netmap device, defaults to '/dev/netmap')\n" 201358952137SVincenzo Maffione#endif 20146a8b4a5bSThomas Huth "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 20156a8b4a5bSThomas Huth " configure a vhost-user network, backed by a chardev 'dev'\n" 20166a8b4a5bSThomas Huth "-netdev hubport,id=str,hubid=n\n" 20176a8b4a5bSThomas Huth " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL) 20186a8b4a5bSThomas HuthDEF("net", HAS_ARG, QEMU_OPTION_net, 20196a8b4a5bSThomas Huth "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 20206a8b4a5bSThomas Huth " old way to create a new NIC and connect it to VLAN 'n'\n" 20216a8b4a5bSThomas Huth " (use the '-device devtype,netdev=str' option if possible instead)\n" 2022bb9ea79eSaliguori "-net dump[,vlan=n][,file=f][,len=n]\n" 2023bb9ea79eSaliguori " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 2024ca1a8a06SBruce Rogers "-net none use it alone to have zero network devices. If no -net option\n" 20256a8b4a5bSThomas Huth " is provided, the default is '-net nic -net user'\n" 20266a8b4a5bSThomas Huth "-net [" 2027a1ea458fSMark McLoughlin#ifdef CONFIG_SLIRP 2028a1ea458fSMark McLoughlin "user|" 2029a1ea458fSMark McLoughlin#endif 2030a1ea458fSMark McLoughlin "tap|" 2031a7c36ee4SCorey Bryant "bridge|" 2032a1ea458fSMark McLoughlin#ifdef CONFIG_VDE 2033a1ea458fSMark McLoughlin "vde|" 2034a1ea458fSMark McLoughlin#endif 203558952137SVincenzo Maffione#ifdef CONFIG_NETMAP 203658952137SVincenzo Maffione "netmap|" 203758952137SVincenzo Maffione#endif 20386a8b4a5bSThomas Huth "socket][,vlan=n][,option][,option][,...]\n" 20396a8b4a5bSThomas Huth " old way to initialize a host network interface\n" 20406a8b4a5bSThomas Huth " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 20415824d651Sblueswir1STEXI 2042ffe6370cSMichael S. Tsirkin@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 20436616b2adSStefan Weil@findex -net 20445824d651Sblueswir1Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 20450d6b0b1dSAnthony Liguori= 0 is the default). The NIC is an e1000 by default on the PC 20465607c388SMarkus Armbrustertarget. Optionally, the MAC address can be changed to @var{mac}, the 20475607c388SMarkus Armbrusterdevice address set to @var{addr} (PCI cards only), 2048ffe6370cSMichael S. Tsirkinand a @var{name} can be assigned for use in monitor commands. 2049ffe6370cSMichael S. TsirkinOptionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2050ffe6370cSMichael S. Tsirkinthat the card should have; this option currently only affects virtio cards; set 2051ffe6370cSMichael S. Tsirkin@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2052071c9394SStefan WeilNIC is created. QEMU can emulate several different models of network card. 20535824d651Sblueswir1Valid values for @var{type} are 20542ec40552SJason Wang@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 20555824d651Sblueswir1@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 20565824d651Sblueswir1@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 2057585f6036SPeter MaydellNot all devices are supported on all targets. Use @code{-net nic,model=help} 20585824d651Sblueswir1for a list of available devices for your target. 20595824d651Sblueswir1 206008d12022SStefan Hajnoczi@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 2061b8f490ebSMarkus Armbruster@findex -netdev 2062ad196a9dSJan Kiszka@item -net user[,@var{option}][,@var{option}][,...] 20635824d651Sblueswir1Use the user mode network stack which requires no administrator 2064ad196a9dSJan Kiszkaprivilege to run. Valid options are: 20655824d651Sblueswir1 2066b3f046c2SKevin Wolf@table @option 2067ad196a9dSJan Kiszka@item vlan=@var{n} 2068ad196a9dSJan KiszkaConnect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 2069ad196a9dSJan Kiszka 207008d12022SStefan Hajnoczi@item id=@var{id} 2071f9cfd655SMarkus Armbruster@itemx name=@var{name} 2072ad196a9dSJan KiszkaAssign symbolic name for use in monitor commands. 2073ad196a9dSJan Kiszka 20740b11c036SSamuel Thibault@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must 20750b11c036SSamuel Thibaultbe enabled. If neither is specified both protocols are enabled. 20760b11c036SSamuel Thibault 2077c92ef6a2SJan Kiszka@item net=@var{addr}[/@var{mask}] 2078c92ef6a2SJan KiszkaSet IP network address the guest will see. Optionally specify the netmask, 2079c92ef6a2SJan Kiszkaeither in the form a.b.c.d or as number of valid top-most bits. Default is 2080b0b36e5dSBrad Hards10.0.2.0/24. 2081c92ef6a2SJan Kiszka 2082c92ef6a2SJan Kiszka@item host=@var{addr} 2083c92ef6a2SJan KiszkaSpecify the guest-visible address of the host. Default is the 2nd IP in the 2084c92ef6a2SJan Kiszkaguest network, i.e. x.x.x.2. 2085ad196a9dSJan Kiszka 2086d8eb3864SSamuel Thibault@item ipv6-net=@var{addr}[/@var{int}] 2087d8eb3864SSamuel ThibaultSet IPv6 network address the guest will see (default is fec0::/64). The 2088d8eb3864SSamuel Thibaultnetwork prefix is given in the usual hexadecimal IPv6 address 2089d8eb3864SSamuel Thibaultnotation. The prefix size is optional, and is given as the number of 2090d8eb3864SSamuel Thibaultvalid top-most bits (default is 64). 20917aac531eSYann Bordenave 2092d8eb3864SSamuel Thibault@item ipv6-host=@var{addr} 20937aac531eSYann BordenaveSpecify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 20947aac531eSYann Bordenavethe guest network, i.e. xxxx::2. 20957aac531eSYann Bordenave 2096c54ed5bcSJan Kiszka@item restrict=on|off 2097caef55edSBrad HardsIf this option is enabled, the guest will be isolated, i.e. it will not be 2098ad196a9dSJan Kiszkaable to contact the host and no guest IP packets will be routed over the host 2099caef55edSBrad Hardsto the outside. This option does not affect any explicitly set forwarding rules. 2100ad196a9dSJan Kiszka 2101ad196a9dSJan Kiszka@item hostname=@var{name} 210263d2960bSKlaus StengelSpecifies the client hostname reported by the built-in DHCP server. 2103ad196a9dSJan Kiszka 2104c92ef6a2SJan Kiszka@item dhcpstart=@var{addr} 2105c92ef6a2SJan KiszkaSpecify the first of the 16 IPs the built-in DHCP server can assign. Default 2106b0b36e5dSBrad Hardsis the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2107c92ef6a2SJan Kiszka 2108c92ef6a2SJan Kiszka@item dns=@var{addr} 2109c92ef6a2SJan KiszkaSpecify the guest-visible address of the virtual nameserver. The address must 2110c92ef6a2SJan Kiszkabe different from the host address. Default is the 3rd IP in the guest network, 2111c92ef6a2SJan Kiszkai.e. x.x.x.3. 2112c92ef6a2SJan Kiszka 2113d8eb3864SSamuel Thibault@item ipv6-dns=@var{addr} 21147aac531eSYann BordenaveSpecify the guest-visible address of the IPv6 virtual nameserver. The address 21157aac531eSYann Bordenavemust be different from the host address. Default is the 3rd IP in the guest 21167aac531eSYann Bordenavenetwork, i.e. xxxx::3. 21177aac531eSYann Bordenave 211863d2960bSKlaus Stengel@item dnssearch=@var{domain} 211963d2960bSKlaus StengelProvides an entry for the domain-search list sent by the built-in 212063d2960bSKlaus StengelDHCP server. More than one domain suffix can be transmitted by specifying 212163d2960bSKlaus Stengelthis option multiple times. If supported, this will cause the guest to 212263d2960bSKlaus Stengelautomatically try to append the given domain suffix(es) in case a domain name 212363d2960bSKlaus Stengelcan not be resolved. 212463d2960bSKlaus Stengel 212563d2960bSKlaus StengelExample: 212663d2960bSKlaus Stengel@example 212763d2960bSKlaus Stengelqemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 212863d2960bSKlaus Stengel@end example 212963d2960bSKlaus Stengel 2130ad196a9dSJan Kiszka@item tftp=@var{dir} 2131ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in TFTP 2132ad196a9dSJan Kiszkaserver. The files in @var{dir} will be exposed as the root of a TFTP server. 2133ad196a9dSJan KiszkaThe TFTP client on the guest must be configured in binary mode (use the command 2134c92ef6a2SJan Kiszka@code{bin} of the Unix TFTP client). 2135ad196a9dSJan Kiszka 2136ad196a9dSJan Kiszka@item bootfile=@var{file} 2137ad196a9dSJan KiszkaWhen using the user mode network stack, broadcast @var{file} as the BOOTP 2138ad196a9dSJan Kiszkafilename. In conjunction with @option{tftp}, this can be used to network boot 2139ad196a9dSJan Kiszkaa guest from a local directory. 2140ad196a9dSJan Kiszka 2141ad196a9dSJan KiszkaExample (using pxelinux): 2142ad196a9dSJan Kiszka@example 21433804da9dSStefan Weilqemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2144ad196a9dSJan Kiszka@end example 2145ad196a9dSJan Kiszka 2146c92ef6a2SJan Kiszka@item smb=@var{dir}[,smbserver=@var{addr}] 2147ad196a9dSJan KiszkaWhen using the user mode network stack, activate a built-in SMB 2148ad196a9dSJan Kiszkaserver so that Windows OSes can access to the host files in @file{@var{dir}} 2149c92ef6a2SJan Kiszkatransparently. The IP address of the SMB server can be set to @var{addr}. By 2150c92ef6a2SJan Kiszkadefault the 4th IP in the guest network is used, i.e. x.x.x.4. 2151ad196a9dSJan Kiszka 2152ad196a9dSJan KiszkaIn the guest Windows OS, the line: 2153ad196a9dSJan Kiszka@example 2154ad196a9dSJan Kiszka10.0.2.4 smbserver 2155ad196a9dSJan Kiszka@end example 2156ad196a9dSJan Kiszkamust be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2157ad196a9dSJan Kiszkaor @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2158ad196a9dSJan Kiszka 2159ad196a9dSJan KiszkaThen @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2160ad196a9dSJan Kiszka 2161e2d8830eSBradNote that a SAMBA server must be installed on the host OS. 2162e2d8830eSBradQEMU was tested successfully with smbd versions from Red Hat 9, 2163e2d8830eSBradFedora Core 3 and OpenSUSE 11.x. 2164ad196a9dSJan Kiszka 21653c6a0580SJan Kiszka@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2166c92ef6a2SJan KiszkaRedirect incoming TCP or UDP connections to the host port @var{hostport} to 2167c92ef6a2SJan Kiszkathe guest IP address @var{guestaddr} on guest port @var{guestport}. If 2168c92ef6a2SJan Kiszka@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 21693c6a0580SJan Kiszkagiven by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 21703c6a0580SJan Kiszkabe bound to a specific host interface. If no connection type is set, TCP is 2171c92ef6a2SJan Kiszkaused. This option can be given multiple times. 2172ad196a9dSJan Kiszka 2173ad196a9dSJan KiszkaFor example, to redirect host X11 connection from screen 1 to guest 2174ad196a9dSJan Kiszkascreen 0, use the following: 2175ad196a9dSJan Kiszka 2176ad196a9dSJan Kiszka@example 2177ad196a9dSJan Kiszka# on the host 21783804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 2179ad196a9dSJan Kiszka# this host xterm should open in the guest X11 server 2180ad196a9dSJan Kiszkaxterm -display :1 2181ad196a9dSJan Kiszka@end example 2182ad196a9dSJan Kiszka 2183ad196a9dSJan KiszkaTo redirect telnet connections from host port 5555 to telnet port on 2184ad196a9dSJan Kiszkathe guest, use the following: 2185ad196a9dSJan Kiszka 2186ad196a9dSJan Kiszka@example 2187ad196a9dSJan Kiszka# on the host 21883804da9dSStefan Weilqemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 2189ad196a9dSJan Kiszkatelnet localhost 5555 2190ad196a9dSJan Kiszka@end example 2191ad196a9dSJan Kiszka 2192ad196a9dSJan KiszkaThen when you use on the host @code{telnet localhost 5555}, you 2193ad196a9dSJan Kiszkaconnect to the guest telnet server. 2194ad196a9dSJan Kiszka 2195c92ef6a2SJan Kiszka@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2196f9cfd655SMarkus Armbruster@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 21973c6a0580SJan KiszkaForward guest TCP connections to the IP address @var{server} on port @var{port} 2198b412eb61SAlexander Grafto the character device @var{dev} or to a program executed by @var{cmd:command} 2199b412eb61SAlexander Grafwhich gets spawned for each connection. This option can be given multiple times. 2200b412eb61SAlexander Graf 220143ffe61fSStefan WeilYou can either use a chardev directly and have that one used throughout QEMU's 2202b412eb61SAlexander Graflifetime, like in the following example: 2203b412eb61SAlexander Graf 2204b412eb61SAlexander Graf@example 2205b412eb61SAlexander Graf# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2206b412eb61SAlexander Graf# the guest accesses it 2207b412eb61SAlexander Grafqemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 2208b412eb61SAlexander Graf@end example 2209b412eb61SAlexander Graf 2210b412eb61SAlexander GrafOr you can execute a command on every TCP connection established by the guest, 221143ffe61fSStefan Weilso that QEMU behaves similar to an inetd process for that virtual server: 2212b412eb61SAlexander Graf 2213b412eb61SAlexander Graf@example 2214b412eb61SAlexander Graf# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2215b412eb61SAlexander Graf# and connect the TCP stream to its stdin/stdout 2216b412eb61SAlexander Grafqemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2217b412eb61SAlexander Graf@end example 2218ad196a9dSJan Kiszka 2219ad196a9dSJan Kiszka@end table 2220ad196a9dSJan Kiszka 2221ad196a9dSJan KiszkaNote: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 2222ad196a9dSJan Kiszkaprocessed and applied to -net user. Mixing them with the new configuration 2223ad196a9dSJan Kiszkasyntax gives undefined results. Their use for new applications is discouraged 2224ad196a9dSJan Kiszkaas they will be removed from future versions. 22255824d651Sblueswir1 2226584613eaSAlexey 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}] 2227584613eaSAlexey Kardashevskiy@itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}] 2228a7c36ee4SCorey BryantConnect the host TAP network interface @var{name} to VLAN @var{n}. 2229a7c36ee4SCorey Bryant 2230a7c36ee4SCorey BryantUse the network script @var{file} to configure it and the network script 22315824d651Sblueswir1@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2232a7c36ee4SCorey Bryantautomatically provides one. The default network configure script is 2233a7c36ee4SCorey Bryant@file{/etc/qemu-ifup} and the default network deconfigure script is 2234a7c36ee4SCorey Bryant@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2235a7c36ee4SCorey Bryantto disable script execution. 2236a7c36ee4SCorey Bryant 2237a7c36ee4SCorey BryantIf running QEMU as an unprivileged user, use the network helper 2238584613eaSAlexey Kardashevskiy@var{helper} to configure the TAP interface and attach it to the bridge. 2239584613eaSAlexey KardashevskiyThe default network helper executable is @file{/path/to/qemu-bridge-helper} 2240584613eaSAlexey Kardashevskiyand the default bridge device is @file{br0}. 2241a7c36ee4SCorey Bryant 2242a7c36ee4SCorey Bryant@option{fd}=@var{h} can be used to specify the handle of an already 2243a7c36ee4SCorey Bryantopened host TAP interface. 2244a7c36ee4SCorey Bryant 2245a7c36ee4SCorey BryantExamples: 22465824d651Sblueswir1 22475824d651Sblueswir1@example 2248a7c36ee4SCorey Bryant#launch a QEMU instance with the default network script 22493804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net tap 22505824d651Sblueswir1@end example 22515824d651Sblueswir1 22525824d651Sblueswir1@example 2253a7c36ee4SCorey Bryant#launch a QEMU instance with two NICs, each one connected 2254a7c36ee4SCorey Bryant#to a TAP device 22553804da9dSStefan Weilqemu-system-i386 linux.img \ 22563804da9dSStefan Weil -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 22575824d651Sblueswir1 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 22585824d651Sblueswir1@end example 22595824d651Sblueswir1 2260a7c36ee4SCorey Bryant@example 2261a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2262a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 22633804da9dSStefan Weilqemu-system-i386 linux.img \ 2264420508fbSAmos Kong -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 2265a7c36ee4SCorey Bryant@end example 2266a7c36ee4SCorey Bryant 226708d12022SStefan Hajnoczi@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2268f9cfd655SMarkus Armbruster@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 2269a7c36ee4SCorey BryantConnect a host TAP network interface to a host bridge device. 2270a7c36ee4SCorey Bryant 2271a7c36ee4SCorey BryantUse the network helper @var{helper} to configure the TAP interface and 2272a7c36ee4SCorey Bryantattach it to the bridge. The default network helper executable is 2273420508fbSAmos Kong@file{/path/to/qemu-bridge-helper} and the default bridge 2274a7c36ee4SCorey Bryantdevice is @file{br0}. 2275a7c36ee4SCorey Bryant 2276a7c36ee4SCorey BryantExamples: 2277a7c36ee4SCorey Bryant 2278a7c36ee4SCorey Bryant@example 2279a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2280a7c36ee4SCorey Bryant#connect a TAP device to bridge br0 22813804da9dSStefan Weilqemu-system-i386 linux.img -net bridge -net nic,model=virtio 2282a7c36ee4SCorey Bryant@end example 2283a7c36ee4SCorey Bryant 2284a7c36ee4SCorey Bryant@example 2285a7c36ee4SCorey Bryant#launch a QEMU instance with the default network helper to 2286a7c36ee4SCorey Bryant#connect a TAP device to bridge qemubr0 22873804da9dSStefan Weilqemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 2288a7c36ee4SCorey Bryant@end example 2289a7c36ee4SCorey Bryant 229008d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 2291f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 22925824d651Sblueswir1 22935824d651Sblueswir1Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 22945824d651Sblueswir1machine using a TCP socket connection. If @option{listen} is 22955824d651Sblueswir1specified, QEMU waits for incoming connections on @var{port} 22965824d651Sblueswir1(@var{host} is optional). @option{connect} is used to connect to 22975824d651Sblueswir1another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 22985824d651Sblueswir1specifies an already opened TCP socket. 22995824d651Sblueswir1 23005824d651Sblueswir1Example: 23015824d651Sblueswir1@example 23025824d651Sblueswir1# launch a first QEMU instance 23033804da9dSStefan Weilqemu-system-i386 linux.img \ 23043804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 23055824d651Sblueswir1 -net socket,listen=:1234 23065824d651Sblueswir1# connect the VLAN 0 of this instance to the VLAN 0 23075824d651Sblueswir1# of the first instance 23083804da9dSStefan Weilqemu-system-i386 linux.img \ 23093804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 23105824d651Sblueswir1 -net socket,connect=127.0.0.1:1234 23115824d651Sblueswir1@end example 23125824d651Sblueswir1 231308d12022SStefan Hajnoczi@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 2314f9cfd655SMarkus Armbruster@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 23155824d651Sblueswir1 23165824d651Sblueswir1Create a VLAN @var{n} shared with another QEMU virtual 23175824d651Sblueswir1machines using a UDP multicast socket, effectively making a bus for 23185824d651Sblueswir1every QEMU with same multicast address @var{maddr} and @var{port}. 23195824d651Sblueswir1NOTES: 23205824d651Sblueswir1@enumerate 23215824d651Sblueswir1@item 23225824d651Sblueswir1Several QEMU can be running on different hosts and share same bus (assuming 23235824d651Sblueswir1correct multicast setup for these hosts). 23245824d651Sblueswir1@item 23255824d651Sblueswir1mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 23265824d651Sblueswir1@url{http://user-mode-linux.sf.net}. 23275824d651Sblueswir1@item 23285824d651Sblueswir1Use @option{fd=h} to specify an already opened UDP multicast socket. 23295824d651Sblueswir1@end enumerate 23305824d651Sblueswir1 23315824d651Sblueswir1Example: 23325824d651Sblueswir1@example 23335824d651Sblueswir1# launch one QEMU instance 23343804da9dSStefan Weilqemu-system-i386 linux.img \ 23353804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 23365824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 23375824d651Sblueswir1# launch another QEMU instance on same "bus" 23383804da9dSStefan Weilqemu-system-i386 linux.img \ 23393804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:57 \ 23405824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 23415824d651Sblueswir1# launch yet another QEMU instance on same "bus" 23423804da9dSStefan Weilqemu-system-i386 linux.img \ 23433804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:58 \ 23445824d651Sblueswir1 -net socket,mcast=230.0.0.1:1234 23455824d651Sblueswir1@end example 23465824d651Sblueswir1 23475824d651Sblueswir1Example (User Mode Linux compat.): 23485824d651Sblueswir1@example 23495824d651Sblueswir1# launch QEMU instance (note mcast address selected 23505824d651Sblueswir1# is UML's default) 23513804da9dSStefan Weilqemu-system-i386 linux.img \ 23523804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 23535824d651Sblueswir1 -net socket,mcast=239.192.168.1:1102 23545824d651Sblueswir1# launch UML 23555824d651Sblueswir1/path/to/linux ubd0=/path/to/root_fs eth0=mcast 23565824d651Sblueswir1@end example 23575824d651Sblueswir1 23583a75e74cSMike RyanExample (send packets from host's 1.2.3.4): 23593a75e74cSMike Ryan@example 23603804da9dSStefan Weilqemu-system-i386 linux.img \ 23613804da9dSStefan Weil -net nic,macaddr=52:54:00:12:34:56 \ 23623a75e74cSMike Ryan -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 23633a75e74cSMike Ryan@end example 23643a75e74cSMike Ryan 23653fb69aa1SAnton 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}] 2366f9cfd655SMarkus Armbruster@itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],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}] 23673fb69aa1SAnton IvanovConnect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular 23683fb69aa1SAnton Ivanovprotocol to transport Ethernet (and other Layer 2) data frames between 23693fb69aa1SAnton Ivanovtwo systems. It is present in routers, firewalls and the Linux kernel 23703fb69aa1SAnton Ivanov(from version 3.3 onwards). 23713fb69aa1SAnton Ivanov 23723fb69aa1SAnton IvanovThis transport allows a VM to communicate to another VM, router or firewall directly. 23733fb69aa1SAnton Ivanov 23743fb69aa1SAnton Ivanov@item src=@var{srcaddr} 23753fb69aa1SAnton Ivanov source address (mandatory) 23763fb69aa1SAnton Ivanov@item dst=@var{dstaddr} 23773fb69aa1SAnton Ivanov destination address (mandatory) 23783fb69aa1SAnton Ivanov@item udp 23793fb69aa1SAnton Ivanov select udp encapsulation (default is ip). 23803fb69aa1SAnton Ivanov@item srcport=@var{srcport} 23813fb69aa1SAnton Ivanov source udp port. 23823fb69aa1SAnton Ivanov@item dstport=@var{dstport} 23833fb69aa1SAnton Ivanov destination udp port. 23843fb69aa1SAnton Ivanov@item ipv6 23853fb69aa1SAnton Ivanov force v6, otherwise defaults to v4. 23863fb69aa1SAnton Ivanov@item rxcookie=@var{rxcookie} 2387f9cfd655SMarkus Armbruster@itemx txcookie=@var{txcookie} 23883fb69aa1SAnton Ivanov Cookies are a weak form of security in the l2tpv3 specification. 23893fb69aa1SAnton IvanovTheir function is mostly to prevent misconfiguration. By default they are 32 23903fb69aa1SAnton Ivanovbit. 23913fb69aa1SAnton Ivanov@item cookie64 23923fb69aa1SAnton Ivanov Set cookie size to 64 bit instead of the default 32 23933fb69aa1SAnton Ivanov@item counter=off 23943fb69aa1SAnton Ivanov Force a 'cut-down' L2TPv3 with no counter as in 23953fb69aa1SAnton Ivanovdraft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 23963fb69aa1SAnton Ivanov@item pincounter=on 23973fb69aa1SAnton Ivanov Work around broken counter handling in peer. This may also help on 23983fb69aa1SAnton Ivanovnetworks which have packet reorder. 23993fb69aa1SAnton Ivanov@item offset=@var{offset} 24003fb69aa1SAnton Ivanov Add an extra offset between header and data 24013fb69aa1SAnton Ivanov 24023fb69aa1SAnton IvanovFor example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 24033fb69aa1SAnton Ivanovon the remote Linux host 1.2.3.4: 24043fb69aa1SAnton Ivanov@example 24053fb69aa1SAnton Ivanov# Setup tunnel on linux host using raw ip as encapsulation 24063fb69aa1SAnton Ivanov# on 1.2.3.4 24073fb69aa1SAnton Ivanovip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 24083fb69aa1SAnton Ivanov encap udp udp_sport 16384 udp_dport 16384 24093fb69aa1SAnton Ivanovip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 24103fb69aa1SAnton Ivanov 0xFFFFFFFF peer_session_id 0xFFFFFFFF 24113fb69aa1SAnton Ivanovifconfig vmtunnel0 mtu 1500 24123fb69aa1SAnton Ivanovifconfig vmtunnel0 up 24133fb69aa1SAnton Ivanovbrctl addif br-lan vmtunnel0 24143fb69aa1SAnton Ivanov 24153fb69aa1SAnton Ivanov 24163fb69aa1SAnton Ivanov# on 4.3.2.1 24173fb69aa1SAnton Ivanov# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 24183fb69aa1SAnton Ivanov 24193fb69aa1SAnton Ivanovqemu-system-i386 linux.img -net nic -net l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 24203fb69aa1SAnton Ivanov 24213fb69aa1SAnton Ivanov 24223fb69aa1SAnton Ivanov@end example 24233fb69aa1SAnton Ivanov 242408d12022SStefan Hajnoczi@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2425f9cfd655SMarkus Armbruster@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 24265824d651Sblueswir1Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 24275824d651Sblueswir1listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 24285824d651Sblueswir1and MODE @var{octalmode} to change default ownership and permissions for 2429c1ba4e0bSStefan Weilcommunication port. This option is only available if QEMU has been compiled 24305824d651Sblueswir1with vde support enabled. 24315824d651Sblueswir1 24325824d651Sblueswir1Example: 24335824d651Sblueswir1@example 24345824d651Sblueswir1# launch vde switch 24355824d651Sblueswir1vde_switch -F -sock /tmp/myswitch 24365824d651Sblueswir1# launch QEMU instance 24373804da9dSStefan Weilqemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 24385824d651Sblueswir1@end example 24395824d651Sblueswir1 244040e8c26dSStefan Hajnoczi@item -netdev hubport,id=@var{id},hubid=@var{hubid} 244140e8c26dSStefan Hajnoczi 244240e8c26dSStefan HajnocziCreate a hub port on QEMU "vlan" @var{hubid}. 244340e8c26dSStefan Hajnoczi 244440e8c26dSStefan HajnocziThe hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 244540e8c26dSStefan Hajnoczinetdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 244640e8c26dSStefan Hajnoczirequired hub automatically. 244740e8c26dSStefan Hajnoczi 2448b931bfbfSChangchun Ouyang@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 244903ce5744SNikolay Nikolaev 245003ce5744SNikolay NikolaevEstablish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 245103ce5744SNikolay Nikolaevbe a unix domain socket backed one. The vhost-user uses a specifically defined 245203ce5744SNikolay Nikolaevprotocol to pass vhost ioctl replacement messages to an application on the other 245303ce5744SNikolay Nikolaevend of the socket. On non-MSIX guests, the feature can be forced with 2454b931bfbfSChangchun Ouyang@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2455b931bfbfSChangchun Ouyangbe created for multiqueue vhost-user. 245603ce5744SNikolay Nikolaev 245703ce5744SNikolay NikolaevExample: 245803ce5744SNikolay Nikolaev@example 245903ce5744SNikolay Nikolaevqemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 246003ce5744SNikolay Nikolaev -numa node,memdev=mem \ 246179cad2faSVincenzo Maffione -chardev socket,id=chr0,path=/path/to/socket \ 246203ce5744SNikolay Nikolaev -netdev type=vhost-user,id=net0,chardev=chr0 \ 246303ce5744SNikolay Nikolaev -device virtio-net-pci,netdev=net0 246403ce5744SNikolay Nikolaev@end example 246503ce5744SNikolay Nikolaev 2466bb9ea79eSaliguori@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 2467bb9ea79eSaliguoriDump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 2468bb9ea79eSaliguoriAt most @var{len} bytes (64k by default) per packet are stored. The file format is 2469bb9ea79eSaliguorilibpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 2470d3e0c032SThomas HuthNote: For devices created with '-netdev', use '-object filter-dump,...' instead. 2471bb9ea79eSaliguori 24725824d651Sblueswir1@item -net none 24735824d651Sblueswir1Indicate that no network devices should be configured. It is used to 24745824d651Sblueswir1override the default configuration (@option{-net nic -net user}) which 24755824d651Sblueswir1is activated if no @option{-net} options are provided. 24765824d651Sblueswir1ETEXI 24775824d651Sblueswir1 2478c70a01e4SMarkus ArmbrusterSTEXI 2479c70a01e4SMarkus Armbruster@end table 2480c70a01e4SMarkus ArmbrusterETEXI 24817273a2dbSMatthew BoothDEFHEADING() 24827273a2dbSMatthew Booth 248343f187a5SPaolo BonziniDEFHEADING(Character device options) 2484c70a01e4SMarkus ArmbrusterSTEXI 2485c70a01e4SMarkus Armbruster 2486c70a01e4SMarkus ArmbrusterThe general form of a character device option is: 2487c70a01e4SMarkus Armbruster@table @option 2488c70a01e4SMarkus ArmbrusterETEXI 24897273a2dbSMatthew Booth 24907273a2dbSMatthew BoothDEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2491517b3d40SLin Ma "-chardev help\n" 2492d0d7708bSDaniel P. Berrange "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 24935dd1f02bSCorey Minyard "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2494d0d7708bSDaniel P. Berrange " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n" 2495a8fb5427SDaniel P. Berrange " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n" 2496d0d7708bSDaniel P. Berrange "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n" 2497d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 24987273a2dbSMatthew Booth "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 249997331287SJan Kiszka " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2500d0d7708bSDaniel P. Berrange " [,logfile=PATH][,logappend=on|off]\n" 2501d0d7708bSDaniel P. Berrange "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25027273a2dbSMatthew Booth "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2503d0d7708bSDaniel P. Berrange " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2504d0d7708bSDaniel P. Berrange "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2505d0d7708bSDaniel P. Berrange "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2506d0d7708bSDaniel P. Berrange "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25077273a2dbSMatthew Booth#ifdef _WIN32 2508d0d7708bSDaniel P. Berrange "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2509d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25107273a2dbSMatthew Booth#else 2511d0d7708bSDaniel P. Berrange "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2512d0d7708bSDaniel P. Berrange "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 25137273a2dbSMatthew Booth#endif 25147273a2dbSMatthew Booth#ifdef CONFIG_BRLAPI 2515d0d7708bSDaniel P. Berrange "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25167273a2dbSMatthew Booth#endif 25177273a2dbSMatthew Booth#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 25187273a2dbSMatthew Booth || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2519d0d7708bSDaniel P. Berrange "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2520d0d7708bSDaniel P. Berrange "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25217273a2dbSMatthew Booth#endif 25227273a2dbSMatthew Booth#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2523d0d7708bSDaniel P. Berrange "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2524d0d7708bSDaniel P. Berrange "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 25257273a2dbSMatthew Booth#endif 2526cbcc6336SAlon Levy#if defined(CONFIG_SPICE) 2527d0d7708bSDaniel P. Berrange "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2528d0d7708bSDaniel P. Berrange "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2529cbcc6336SAlon Levy#endif 2530ad96090aSBlue Swirl , QEMU_ARCH_ALL 25317273a2dbSMatthew Booth) 25327273a2dbSMatthew Booth 25337273a2dbSMatthew BoothSTEXI 253497331287SJan Kiszka@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 25356616b2adSStefan Weil@findex -chardev 25367273a2dbSMatthew BoothBackend is one of: 25377273a2dbSMatthew Booth@option{null}, 25387273a2dbSMatthew Booth@option{socket}, 25397273a2dbSMatthew Booth@option{udp}, 25407273a2dbSMatthew Booth@option{msmouse}, 25417273a2dbSMatthew Booth@option{vc}, 25424f57378fSMarkus Armbruster@option{ringbuf}, 25437273a2dbSMatthew Booth@option{file}, 25447273a2dbSMatthew Booth@option{pipe}, 25457273a2dbSMatthew Booth@option{console}, 25467273a2dbSMatthew Booth@option{serial}, 25477273a2dbSMatthew Booth@option{pty}, 25487273a2dbSMatthew Booth@option{stdio}, 25497273a2dbSMatthew Booth@option{braille}, 25507273a2dbSMatthew Booth@option{tty}, 255188a946d3SGerd Hoffmann@option{parallel}, 2552cbcc6336SAlon Levy@option{parport}, 2553cbcc6336SAlon Levy@option{spicevmc}. 25545a49d3e9SMarc-André Lureau@option{spiceport}. 25557273a2dbSMatthew BoothThe specific backend will determine the applicable options. 25567273a2dbSMatthew Booth 2557517b3d40SLin MaUse "-chardev help" to print all available chardev backend types. 2558517b3d40SLin Ma 25597273a2dbSMatthew BoothAll devices must have an id, which can be any string up to 127 characters long. 25607273a2dbSMatthew BoothIt is used to uniquely identify this device in other command line directives. 25617273a2dbSMatthew Booth 256297331287SJan KiszkaA character device may be used in multiplexing mode by multiple front-ends. 2563a40db1b3SPeter MaydellSpecify @option{mux=on} to enable this mode. 2564a40db1b3SPeter MaydellA multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2565a40db1b3SPeter Maydellbackend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2566a40db1b3SPeter MaydellIf you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2567a40db1b3SPeter Maydellcreate a multiplexer with your specified ID, and you can then configure multiple 2568a40db1b3SPeter Maydellfront ends to use that chardev ID for their input/output. Up to four different 2569a40db1b3SPeter Maydellfront ends can be connected to a single multiplexed chardev. (Without 2570a40db1b3SPeter Maydellmultiplexing enabled, a chardev can only be used by a single front end.) 2571a40db1b3SPeter MaydellFor instance you could use this to allow a single stdio chardev to be used by 2572a40db1b3SPeter Maydelltwo serial ports and the QEMU monitor: 2573a40db1b3SPeter Maydell 2574a40db1b3SPeter Maydell@example 2575a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2576bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2577a40db1b3SPeter Maydell-serial chardev:char0 \ 2578a40db1b3SPeter Maydell-serial chardev:char0 2579a40db1b3SPeter Maydell@end example 2580a40db1b3SPeter Maydell 2581a40db1b3SPeter MaydellYou can have more than one multiplexer in a system configuration; for instance 2582a40db1b3SPeter Maydellyou could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2583a40db1b3SPeter Maydellmultiplexed between the QEMU monitor and a parallel port: 2584a40db1b3SPeter Maydell 2585a40db1b3SPeter Maydell@example 2586a40db1b3SPeter Maydell-chardev stdio,mux=on,id=char0 \ 2587bdbcb547SMarc-André Lureau-mon chardev=char0,mode=readline \ 2588a40db1b3SPeter Maydell-parallel chardev:char0 \ 2589a40db1b3SPeter Maydell-chardev tcp,...,mux=on,id=char1 \ 2590a40db1b3SPeter Maydell-serial chardev:char1 \ 2591a40db1b3SPeter Maydell-serial chardev:char1 2592a40db1b3SPeter Maydell@end example 2593a40db1b3SPeter Maydell 2594a40db1b3SPeter MaydellWhen you're using a multiplexed character device, some escape sequences are 2595a40db1b3SPeter Maydellinterpreted in the input. @xref{mux_keys, Keys in the character backend 2596a40db1b3SPeter Maydellmultiplexer}. 2597a40db1b3SPeter Maydell 2598a40db1b3SPeter MaydellNote that some other command line options may implicitly create multiplexed 2599a40db1b3SPeter Maydellcharacter backends; for instance @option{-serial mon:stdio} creates a 2600a40db1b3SPeter Maydellmultiplexed stdio backend connected to the serial port and the QEMU monitor, 2601a40db1b3SPeter Maydelland @option{-nographic} also multiplexes the console and the monitor to 2602a40db1b3SPeter Maydellstdio. 2603a40db1b3SPeter Maydell 2604a40db1b3SPeter MaydellThere is currently no support for multiplexing in the other direction 2605a40db1b3SPeter Maydell(where a single QEMU front end takes input and output from multiple chardevs). 260697331287SJan Kiszka 2607d0d7708bSDaniel P. BerrangeEvery backend supports the @option{logfile} option, which supplies the path 2608d0d7708bSDaniel P. Berrangeto a file to record all data transmitted via the backend. The @option{logappend} 2609d0d7708bSDaniel P. Berrangeoption controls whether the log file will be truncated or appended to when 2610d0d7708bSDaniel P. Berrangeopened. 2611d0d7708bSDaniel P. Berrange 2612d0d7708bSDaniel P. BerrangeFurther options to each backend are described below. 26137273a2dbSMatthew Booth 26147273a2dbSMatthew Booth@item -chardev null ,id=@var{id} 26157273a2dbSMatthew BoothA void device. This device will not emit any data, and will drop any data it 26167273a2dbSMatthew Boothreceives. The null backend does not take any options. 26177273a2dbSMatthew Booth 2618a8fb5427SDaniel P. Berrange@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}] 26197273a2dbSMatthew Booth 26207273a2dbSMatthew BoothCreate a two-way stream socket, which can be either a TCP or a unix socket. A 26217273a2dbSMatthew Boothunix socket will be created if @option{path} is specified. Behaviour is 26227273a2dbSMatthew Boothundefined if TCP options are specified for a unix socket. 26237273a2dbSMatthew Booth 26247273a2dbSMatthew Booth@option{server} specifies that the socket shall be a listening socket. 26257273a2dbSMatthew Booth 26267273a2dbSMatthew Booth@option{nowait} specifies that QEMU should not block waiting for a client to 26277273a2dbSMatthew Boothconnect to a listening socket. 26287273a2dbSMatthew Booth 26297273a2dbSMatthew Booth@option{telnet} specifies that traffic on the socket should interpret telnet 26307273a2dbSMatthew Boothescape sequences. 26317273a2dbSMatthew Booth 26325dd1f02bSCorey Minyard@option{reconnect} sets the timeout for reconnecting on non-server sockets when 26335dd1f02bSCorey Minyardthe remote end goes away. qemu will delay this many seconds and then attempt 26345dd1f02bSCorey Minyardto reconnect. Zero disables reconnecting, and is the default. 26355dd1f02bSCorey Minyard 2636a8fb5427SDaniel P. Berrange@option{tls-creds} requests enablement of the TLS protocol for encryption, 2637a8fb5427SDaniel P. Berrangeand specifies the id of the TLS credentials to use for the handshake. The 2638a8fb5427SDaniel P. Berrangecredentials must be previously created with the @option{-object tls-creds} 2639a8fb5427SDaniel P. Berrangeargument. 2640a8fb5427SDaniel P. Berrange 26417273a2dbSMatthew BoothTCP and unix socket options are given below: 26427273a2dbSMatthew Booth 26437273a2dbSMatthew Booth@table @option 26447273a2dbSMatthew Booth 26458d533561SAurelien Jarno@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 26467273a2dbSMatthew Booth 26477273a2dbSMatthew Booth@option{host} for a listening socket specifies the local address to be bound. 26487273a2dbSMatthew BoothFor a connecting socket species the remote host to connect to. @option{host} is 26497273a2dbSMatthew Boothoptional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 26507273a2dbSMatthew Booth 26517273a2dbSMatthew Booth@option{port} for a listening socket specifies the local port to be bound. For a 26527273a2dbSMatthew Boothconnecting socket specifies the port on the remote host to connect to. 26537273a2dbSMatthew Booth@option{port} can be given as either a port number or a service name. 26547273a2dbSMatthew Booth@option{port} is required. 26557273a2dbSMatthew Booth 26567273a2dbSMatthew Booth@option{to} is only relevant to listening sockets. If it is specified, and 26577273a2dbSMatthew Booth@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 26587273a2dbSMatthew Boothto and including @option{to} until it succeeds. @option{to} must be specified 26597273a2dbSMatthew Boothas a port number. 26607273a2dbSMatthew Booth 26617273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 26627273a2dbSMatthew BoothIf neither is specified the socket may use either protocol. 26637273a2dbSMatthew Booth 26647273a2dbSMatthew Booth@option{nodelay} disables the Nagle algorithm. 26657273a2dbSMatthew Booth 26667273a2dbSMatthew Booth@item unix options: path=@var{path} 26677273a2dbSMatthew Booth 26687273a2dbSMatthew Booth@option{path} specifies the local path of the unix socket. @option{path} is 26697273a2dbSMatthew Boothrequired. 26707273a2dbSMatthew Booth 26717273a2dbSMatthew Booth@end table 26727273a2dbSMatthew Booth 26737273a2dbSMatthew Booth@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 26747273a2dbSMatthew Booth 26757273a2dbSMatthew BoothSends all traffic from the guest to a remote host over UDP. 26767273a2dbSMatthew Booth 26777273a2dbSMatthew Booth@option{host} specifies the remote host to connect to. If not specified it 26787273a2dbSMatthew Boothdefaults to @code{localhost}. 26797273a2dbSMatthew Booth 26807273a2dbSMatthew Booth@option{port} specifies the port on the remote host to connect to. @option{port} 26817273a2dbSMatthew Boothis required. 26827273a2dbSMatthew Booth 26837273a2dbSMatthew Booth@option{localaddr} specifies the local address to bind to. If not specified it 26847273a2dbSMatthew Boothdefaults to @code{0.0.0.0}. 26857273a2dbSMatthew Booth 26867273a2dbSMatthew Booth@option{localport} specifies the local port to bind to. If not specified any 26877273a2dbSMatthew Boothavailable local port will be used. 26887273a2dbSMatthew Booth 26897273a2dbSMatthew Booth@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 26907273a2dbSMatthew BoothIf neither is specified the device may use either protocol. 26917273a2dbSMatthew Booth 26927273a2dbSMatthew Booth@item -chardev msmouse ,id=@var{id} 26937273a2dbSMatthew Booth 26947273a2dbSMatthew BoothForward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 26957273a2dbSMatthew Boothtake any options. 26967273a2dbSMatthew Booth 26977273a2dbSMatthew Booth@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 26987273a2dbSMatthew Booth 26997273a2dbSMatthew BoothConnect to a QEMU text console. @option{vc} may optionally be given a specific 27007273a2dbSMatthew Boothsize. 27017273a2dbSMatthew Booth 27027273a2dbSMatthew Booth@option{width} and @option{height} specify the width and height respectively of 27037273a2dbSMatthew Booththe console, in pixels. 27047273a2dbSMatthew Booth 27057273a2dbSMatthew Booth@option{cols} and @option{rows} specify that the console be sized to fit a text 27067273a2dbSMatthew Boothconsole with the given dimensions. 27077273a2dbSMatthew Booth 27084f57378fSMarkus Armbruster@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 270951767e7cSLei Li 27103949e594SMarkus ArmbrusterCreate a ring buffer with fixed size @option{size}. 2711e69f7d25SStefan Hajnoczi@var{size} must be a power of two and defaults to @code{64K}. 271251767e7cSLei Li 27137273a2dbSMatthew Booth@item -chardev file ,id=@var{id} ,path=@var{path} 27147273a2dbSMatthew Booth 27157273a2dbSMatthew BoothLog all traffic received from the guest to a file. 27167273a2dbSMatthew Booth 27177273a2dbSMatthew Booth@option{path} specifies the path of the file to be opened. This file will be 27187273a2dbSMatthew Boothcreated if it does not already exist, and overwritten if it does. @option{path} 27197273a2dbSMatthew Boothis required. 27207273a2dbSMatthew Booth 27217273a2dbSMatthew Booth@item -chardev pipe ,id=@var{id} ,path=@var{path} 27227273a2dbSMatthew Booth 27237273a2dbSMatthew BoothCreate a two-way connection to the guest. The behaviour differs slightly between 27247273a2dbSMatthew BoothWindows hosts and other hosts: 27257273a2dbSMatthew Booth 27267273a2dbSMatthew BoothOn Windows, a single duplex pipe will be created at 27277273a2dbSMatthew Booth@file{\\.pipe\@option{path}}. 27287273a2dbSMatthew Booth 27297273a2dbSMatthew BoothOn other hosts, 2 pipes will be created called @file{@option{path}.in} and 27307273a2dbSMatthew Booth@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 27317273a2dbSMatthew Boothreceived by the guest. Data written by the guest can be read from 27327273a2dbSMatthew Booth@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 27337273a2dbSMatthew Boothbe present. 27347273a2dbSMatthew Booth 27357273a2dbSMatthew Booth@option{path} forms part of the pipe path as described above. @option{path} is 27367273a2dbSMatthew Boothrequired. 27377273a2dbSMatthew Booth 27387273a2dbSMatthew Booth@item -chardev console ,id=@var{id} 27397273a2dbSMatthew Booth 27407273a2dbSMatthew BoothSend traffic from the guest to QEMU's standard output. @option{console} does not 27417273a2dbSMatthew Boothtake any options. 27427273a2dbSMatthew Booth 27437273a2dbSMatthew Booth@option{console} is only available on Windows hosts. 27447273a2dbSMatthew Booth 27457273a2dbSMatthew Booth@item -chardev serial ,id=@var{id} ,path=@option{path} 27467273a2dbSMatthew Booth 27477273a2dbSMatthew BoothSend traffic from the guest to a serial device on the host. 27487273a2dbSMatthew Booth 2749d59044efSGerd HoffmannOn Unix hosts serial will actually accept any tty device, 2750d59044efSGerd Hoffmannnot only serial lines. 27517273a2dbSMatthew Booth 27527273a2dbSMatthew Booth@option{path} specifies the name of the serial device to open. 27537273a2dbSMatthew Booth 27547273a2dbSMatthew Booth@item -chardev pty ,id=@var{id} 27557273a2dbSMatthew Booth 27567273a2dbSMatthew BoothCreate a new pseudo-terminal on the host and connect to it. @option{pty} does 27577273a2dbSMatthew Boothnot take any options. 27587273a2dbSMatthew Booth 27597273a2dbSMatthew Booth@option{pty} is not available on Windows hosts. 27607273a2dbSMatthew Booth 2761b7fdb3abSAurelien Jarno@item -chardev stdio ,id=@var{id} [,signal=on|off] 2762b65ee4faSStefan WeilConnect to standard input and standard output of the QEMU process. 2763b7fdb3abSAurelien Jarno 2764b7fdb3abSAurelien Jarno@option{signal} controls if signals are enabled on the terminal, that includes 2765b7fdb3abSAurelien Jarnoexiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2766b7fdb3abSAurelien Jarnodefault, use @option{signal=off} to disable it. 2767b7fdb3abSAurelien Jarno 27687273a2dbSMatthew Booth@item -chardev braille ,id=@var{id} 27697273a2dbSMatthew Booth 27707273a2dbSMatthew BoothConnect to a local BrlAPI server. @option{braille} does not take any options. 27717273a2dbSMatthew Booth 27727273a2dbSMatthew Booth@item -chardev tty ,id=@var{id} ,path=@var{path} 27737273a2dbSMatthew Booth 27747273a2dbSMatthew Booth@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2775d037d6bbSMarkus ArmbrusterDragonFlyBSD hosts. It is an alias for @option{serial}. 27767273a2dbSMatthew Booth 27777273a2dbSMatthew Booth@option{path} specifies the path to the tty. @option{path} is required. 27787273a2dbSMatthew Booth 277988a946d3SGerd Hoffmann@item -chardev parallel ,id=@var{id} ,path=@var{path} 2780f9cfd655SMarkus Armbruster@itemx -chardev parport ,id=@var{id} ,path=@var{path} 27817273a2dbSMatthew Booth 278288a946d3SGerd Hoffmann@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 27837273a2dbSMatthew Booth 27847273a2dbSMatthew BoothConnect to a local parallel port. 27857273a2dbSMatthew Booth 27867273a2dbSMatthew Booth@option{path} specifies the path to the parallel port device. @option{path} is 27877273a2dbSMatthew Boothrequired. 27887273a2dbSMatthew Booth 2789cbcc6336SAlon Levy@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2790cbcc6336SAlon Levy 27913a846906SStefan Hajnoczi@option{spicevmc} is only available when spice support is built in. 27923a846906SStefan Hajnoczi 2793cbcc6336SAlon Levy@option{debug} debug level for spicevmc 2794cbcc6336SAlon Levy 2795cbcc6336SAlon Levy@option{name} name of spice channel to connect to 2796cbcc6336SAlon Levy 2797cbcc6336SAlon LevyConnect to a spice virtual machine channel, such as vdiport. 2798cbcc6336SAlon Levy 27995a49d3e9SMarc-André Lureau@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 28005a49d3e9SMarc-André Lureau 28015a49d3e9SMarc-André Lureau@option{spiceport} is only available when spice support is built in. 28025a49d3e9SMarc-André Lureau 28035a49d3e9SMarc-André Lureau@option{debug} debug level for spicevmc 28045a49d3e9SMarc-André Lureau 28055a49d3e9SMarc-André Lureau@option{name} name of spice port to connect to 28065a49d3e9SMarc-André Lureau 28075a49d3e9SMarc-André LureauConnect to a spice port, allowing a Spice client to handle the traffic 28085a49d3e9SMarc-André Lureauidentified by a name (preferably a fqdn). 28097273a2dbSMatthew BoothETEXI 28107273a2dbSMatthew Booth 2811c70a01e4SMarkus ArmbrusterSTEXI 2812c70a01e4SMarkus Armbruster@end table 2813c70a01e4SMarkus ArmbrusterETEXI 28147273a2dbSMatthew BoothDEFHEADING() 28157273a2dbSMatthew Booth 281643f187a5SPaolo BonziniDEFHEADING(Device URL Syntax) 2817c70a01e4SMarkus ArmbrusterSTEXI 28180f5314a2SRonnie Sahlberg 28190f5314a2SRonnie SahlbergIn addition to using normal file images for the emulated storage devices, 28200f5314a2SRonnie SahlbergQEMU can also use networked resources such as iSCSI devices. These are 28210f5314a2SRonnie Sahlbergspecified using a special URL syntax. 28220f5314a2SRonnie Sahlberg 28230f5314a2SRonnie Sahlberg@table @option 28240f5314a2SRonnie Sahlberg@item iSCSI 28250f5314a2SRonnie SahlbergiSCSI support allows QEMU to access iSCSI resources directly and use as 28260f5314a2SRonnie Sahlbergimages for the guest storage. Both disk and cdrom images are supported. 28270f5314a2SRonnie Sahlberg 28280f5314a2SRonnie SahlbergSyntax for specifying iSCSI LUNs is 28290f5314a2SRonnie Sahlberg``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 28300f5314a2SRonnie Sahlberg 283131459f46SRonnie SahlbergBy default qemu will use the iSCSI initiator-name 283231459f46SRonnie Sahlberg'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 283331459f46SRonnie Sahlbergline or a configuration file. 283431459f46SRonnie Sahlberg 28355dd7a535SPeter LievenSince version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect 28365dd7a535SPeter Lievenstalled requests and force a reestablishment of the session. The timeout 28379049736eSPeter Lievenis specified in seconds. The default is 0 which means no timeout. Libiscsi 28389049736eSPeter Lieven1.15.0 or greater is required for this feature. 283931459f46SRonnie Sahlberg 28400f5314a2SRonnie SahlbergExample (without authentication): 28410f5314a2SRonnie Sahlberg@example 28423804da9dSStefan Weilqemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2843f9dadc98SRonnie Sahlberg -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2844f9dadc98SRonnie Sahlberg -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 28450f5314a2SRonnie Sahlberg@end example 28460f5314a2SRonnie Sahlberg 28470f5314a2SRonnie SahlbergExample (CHAP username/password via URL): 28480f5314a2SRonnie Sahlberg@example 28493804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 28500f5314a2SRonnie Sahlberg@end example 28510f5314a2SRonnie Sahlberg 28520f5314a2SRonnie SahlbergExample (CHAP username/password via environment variables): 28530f5314a2SRonnie Sahlberg@example 28540f5314a2SRonnie SahlbergLIBISCSI_CHAP_USERNAME="user" \ 28550f5314a2SRonnie SahlbergLIBISCSI_CHAP_PASSWORD="password" \ 28563804da9dSStefan Weilqemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 28570f5314a2SRonnie Sahlberg@end example 28580f5314a2SRonnie Sahlberg 28590f5314a2SRonnie SahlbergiSCSI support is an optional feature of QEMU and only available when 28600f5314a2SRonnie Sahlbergcompiled and linked against libiscsi. 2861f9dadc98SRonnie SahlbergETEXI 2862f9dadc98SRonnie SahlbergDEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2863f9dadc98SRonnie Sahlberg "-iscsi [user=user][,password=password]\n" 2864f9dadc98SRonnie Sahlberg " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 28652fe3798cSPaolo Bonzini " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 28665dd7a535SPeter Lieven " [,timeout=timeout]\n" 2867f9dadc98SRonnie Sahlberg " iSCSI session parameters\n", QEMU_ARCH_ALL) 2868f9dadc98SRonnie SahlbergSTEXI 28690f5314a2SRonnie Sahlberg 287031459f46SRonnie SahlbergiSCSI parameters such as username and password can also be specified via 287131459f46SRonnie Sahlberga configuration file. See qemu-doc for more information and examples. 287231459f46SRonnie Sahlberg 287308ae330eSRonnie Sahlberg@item NBD 287408ae330eSRonnie SahlbergQEMU supports NBD (Network Block Devices) both using TCP protocol as well 287508ae330eSRonnie Sahlbergas Unix Domain Sockets. 287608ae330eSRonnie Sahlberg 287708ae330eSRonnie SahlbergSyntax for specifying a NBD device using TCP 287808ae330eSRonnie Sahlberg``nbd:<server-ip>:<port>[:exportname=<export>]'' 287908ae330eSRonnie Sahlberg 288008ae330eSRonnie SahlbergSyntax for specifying a NBD device using Unix Domain Sockets 288108ae330eSRonnie Sahlberg``nbd:unix:<domain-socket>[:exportname=<export>]'' 288208ae330eSRonnie Sahlberg 288308ae330eSRonnie Sahlberg 288408ae330eSRonnie SahlbergExample for TCP 288508ae330eSRonnie Sahlberg@example 28863804da9dSStefan Weilqemu-system-i386 --drive file=nbd:192.0.2.1:30000 288708ae330eSRonnie Sahlberg@end example 288808ae330eSRonnie Sahlberg 288908ae330eSRonnie SahlbergExample for Unix Domain Sockets 289008ae330eSRonnie Sahlberg@example 28913804da9dSStefan Weilqemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 289208ae330eSRonnie Sahlberg@end example 289308ae330eSRonnie Sahlberg 28940a12ec87SRichard W.M. Jones@item SSH 28950a12ec87SRichard W.M. JonesQEMU supports SSH (Secure Shell) access to remote disks. 28960a12ec87SRichard W.M. Jones 28970a12ec87SRichard W.M. JonesExamples: 28980a12ec87SRichard W.M. Jones@example 28990a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 29000a12ec87SRichard W.M. Jonesqemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 29010a12ec87SRichard W.M. Jones@end example 29020a12ec87SRichard W.M. Jones 29030a12ec87SRichard W.M. JonesCurrently authentication must be done using ssh-agent. Other 29040a12ec87SRichard W.M. Jonesauthentication methods may be supported in future. 29050a12ec87SRichard W.M. Jones 2906d9990228SRonnie Sahlberg@item Sheepdog 2907d9990228SRonnie SahlbergSheepdog is a distributed storage system for QEMU. 2908d9990228SRonnie SahlbergQEMU supports using either local sheepdog devices or remote networked 2909d9990228SRonnie Sahlbergdevices. 2910d9990228SRonnie Sahlberg 2911d9990228SRonnie SahlbergSyntax for specifying a sheepdog device 29125d6768e3SMORITA Kazutaka@example 29131b8bbb46SMORITA Kazutakasheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 29145d6768e3SMORITA Kazutaka@end example 2915d9990228SRonnie Sahlberg 2916d9990228SRonnie SahlbergExample 2917d9990228SRonnie Sahlberg@example 29185d6768e3SMORITA Kazutakaqemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2919d9990228SRonnie Sahlberg@end example 2920d9990228SRonnie Sahlberg 29216135c5e1SThomas HuthSee also @url{https://sheepdog.github.io/sheepdog/}. 2922d9990228SRonnie Sahlberg 29238809e289SBharata B Rao@item GlusterFS 2924736a83faSStefan WeilGlusterFS is a user space distributed file system. 29258809e289SBharata B RaoQEMU supports the use of GlusterFS volumes for hosting VM disk images using 29268809e289SBharata B RaoTCP, Unix Domain Sockets and RDMA transport protocols. 29278809e289SBharata B Rao 29288809e289SBharata B RaoSyntax for specifying a VM disk image on GlusterFS volume is 29298809e289SBharata B Rao@example 293076b5550fSPrasanna Kumar Kalever 293176b5550fSPrasanna Kumar KaleverURI: 293276b5550fSPrasanna Kumar Kalevergluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...] 293376b5550fSPrasanna Kumar Kalever 293476b5550fSPrasanna Kumar KaleverJSON: 293576b5550fSPrasanna Kumar Kalever'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...", 293676b5550fSPrasanna Kumar Kalever@ "server":[@{"type":"tcp","host":"...","port":"..."@}, 293776b5550fSPrasanna Kumar Kalever@ @{"type":"unix","socket":"..."@}]@}@}' 29388809e289SBharata B Rao@end example 29398809e289SBharata B Rao 29408809e289SBharata B Rao 29418809e289SBharata B RaoExample 29428809e289SBharata B Rao@example 294376b5550fSPrasanna Kumar KaleverURI: 294476b5550fSPrasanna Kumar Kaleverqemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img, 294576b5550fSPrasanna Kumar Kalever@ file.debug=9,file.logfile=/var/log/qemu-gluster.log 294676b5550fSPrasanna Kumar Kalever 294776b5550fSPrasanna Kumar KaleverJSON: 294876b5550fSPrasanna Kumar Kaleverqemu-system-x86_64 'json:@{"driver":"qcow2", 294976b5550fSPrasanna Kumar Kalever@ "file":@{"driver":"gluster", 295076b5550fSPrasanna Kumar Kalever@ "volume":"testvol","path":"a.img", 295176b5550fSPrasanna Kumar Kalever@ "debug":9,"logfile":"/var/log/qemu-gluster.log", 295276b5550fSPrasanna Kumar Kalever@ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@}, 295376b5550fSPrasanna Kumar Kalever@ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}' 295476b5550fSPrasanna Kumar Kaleverqemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, 295576b5550fSPrasanna Kumar Kalever@ file.debug=9,file.logfile=/var/log/qemu-gluster.log, 295676b5550fSPrasanna Kumar Kalever@ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, 295776b5550fSPrasanna Kumar Kalever@ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket 29588809e289SBharata B Rao@end example 29598809e289SBharata B Rao 29608809e289SBharata B RaoSee also @url{http://www.gluster.org}. 29610a86cb73SMatthew Booth 296223dce387SMax Reitz@item HTTP/HTTPS/FTP/FTPS 296323dce387SMax ReitzQEMU supports read-only access to files accessed over http(s) and ftp(s). 29640a86cb73SMatthew Booth 29650a86cb73SMatthew BoothSyntax using a single filename: 29660a86cb73SMatthew Booth@example 29670a86cb73SMatthew Booth<protocol>://[<username>[:<password>]@@]<host>/<path> 29680a86cb73SMatthew Booth@end example 29690a86cb73SMatthew Booth 29700a86cb73SMatthew Boothwhere: 29710a86cb73SMatthew Booth@table @option 29720a86cb73SMatthew Booth@item protocol 297323dce387SMax Reitz'http', 'https', 'ftp', or 'ftps'. 29740a86cb73SMatthew Booth 29750a86cb73SMatthew Booth@item username 29760a86cb73SMatthew BoothOptional username for authentication to the remote server. 29770a86cb73SMatthew Booth 29780a86cb73SMatthew Booth@item password 29790a86cb73SMatthew BoothOptional password for authentication to the remote server. 29800a86cb73SMatthew Booth 29810a86cb73SMatthew Booth@item host 29820a86cb73SMatthew BoothAddress of the remote server. 29830a86cb73SMatthew Booth 29840a86cb73SMatthew Booth@item path 29850a86cb73SMatthew BoothPath on the remote server, including any query string. 29860a86cb73SMatthew Booth@end table 29870a86cb73SMatthew Booth 29880a86cb73SMatthew BoothThe following options are also supported: 29890a86cb73SMatthew Booth@table @option 29900a86cb73SMatthew Booth@item url 29910a86cb73SMatthew BoothThe full URL when passing options to the driver explicitly. 29920a86cb73SMatthew Booth 29930a86cb73SMatthew Booth@item readahead 29940a86cb73SMatthew BoothThe amount of data to read ahead with each range request to the remote server. 29950a86cb73SMatthew BoothThis value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it 29960a86cb73SMatthew Boothdoes not have a suffix, it will be assumed to be in bytes. The value must be a 29970a86cb73SMatthew Boothmultiple of 512 bytes. It defaults to 256k. 29980a86cb73SMatthew Booth 29990a86cb73SMatthew Booth@item sslverify 30000a86cb73SMatthew BoothWhether to verify the remote server's certificate when connecting over SSL. It 30010a86cb73SMatthew Boothcan have the value 'on' or 'off'. It defaults to 'on'. 3002212aefaaSDaniel Henrique Barboza 3003a94f83d9SRichard W.M. Jones@item cookie 3004a94f83d9SRichard W.M. JonesSend this cookie (it can also be a list of cookies separated by ';') with 3005a94f83d9SRichard W.M. Joneseach outgoing request. Only supported when using protocols such as HTTP 3006a94f83d9SRichard W.M. Joneswhich support cookies, otherwise ignored. 3007a94f83d9SRichard W.M. Jones 3008212aefaaSDaniel Henrique Barboza@item timeout 3009212aefaaSDaniel Henrique BarbozaSet the timeout in seconds of the CURL connection. This timeout is the time 3010212aefaaSDaniel Henrique Barbozathat CURL waits for a response from the remote server to get the size of the 3011212aefaaSDaniel Henrique Barbozaimage to be downloaded. If not set, the default timeout of 5 seconds is used. 30120a86cb73SMatthew Booth@end table 30130a86cb73SMatthew Booth 30140a86cb73SMatthew BoothNote that when passing options to qemu explicitly, @option{driver} is the value 30150a86cb73SMatthew Boothof <protocol>. 30160a86cb73SMatthew Booth 30170a86cb73SMatthew BoothExample: boot from a remote Fedora 20 live ISO image 30180a86cb73SMatthew Booth@example 30190a86cb73SMatthew Boothqemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly 30200a86cb73SMatthew Booth 30210a86cb73SMatthew Boothqemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly 30220a86cb73SMatthew Booth@end example 30230a86cb73SMatthew Booth 30240a86cb73SMatthew BoothExample: boot from a remote Fedora 20 cloud image using a local overlay for 30250a86cb73SMatthew Boothwrites, copy-on-read, and a readahead of 64k 30260a86cb73SMatthew Booth@example 30270a86cb73SMatthew Boothqemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 30280a86cb73SMatthew Booth 30290a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on 30300a86cb73SMatthew Booth@end example 30310a86cb73SMatthew Booth 30320a86cb73SMatthew BoothExample: boot from an image stored on a VMware vSphere server with a self-signed 3033212aefaaSDaniel Henrique Barbozacertificate using a local overlay for writes, a readahead of 64k and a timeout 3034212aefaaSDaniel Henrique Barbozaof 10 seconds. 30350a86cb73SMatthew Booth@example 3036212aefaaSDaniel Henrique Barbozaqemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2 30370a86cb73SMatthew Booth 30380a86cb73SMatthew Boothqemu-system-x86_64 -drive file=/tmp/test.qcow2 30390a86cb73SMatthew Booth@end example 3040c70a01e4SMarkus ArmbrusterETEXI 3041c70a01e4SMarkus Armbruster 3042c70a01e4SMarkus ArmbrusterSTEXI 30430f5314a2SRonnie Sahlberg@end table 30440f5314a2SRonnie SahlbergETEXI 30450f5314a2SRonnie Sahlberg 304643f187a5SPaolo BonziniDEFHEADING(Bluetooth(R) options) 3047c70a01e4SMarkus ArmbrusterSTEXI 3048c70a01e4SMarkus Armbruster@table @option 3049c70a01e4SMarkus ArmbrusterETEXI 30507273a2dbSMatthew Booth 30515824d651Sblueswir1DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 30525824d651Sblueswir1 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 30535824d651Sblueswir1 "-bt hci,host[:id]\n" \ 30545824d651Sblueswir1 " use host's HCI with the given name\n" \ 30555824d651Sblueswir1 "-bt hci[,vlan=n]\n" \ 30565824d651Sblueswir1 " emulate a standard HCI in virtual scatternet 'n'\n" \ 30575824d651Sblueswir1 "-bt vhci[,vlan=n]\n" \ 30585824d651Sblueswir1 " add host computer to virtual scatternet 'n' using VHCI\n" \ 30595824d651Sblueswir1 "-bt device:dev[,vlan=n]\n" \ 3060ad96090aSBlue Swirl " emulate a bluetooth device 'dev' in scatternet 'n'\n", 3061ad96090aSBlue Swirl QEMU_ARCH_ALL) 30625824d651Sblueswir1STEXI 30635824d651Sblueswir1@item -bt hci[...] 30646616b2adSStefan Weil@findex -bt 30655824d651Sblueswir1Defines the function of the corresponding Bluetooth HCI. -bt options 30665824d651Sblueswir1are matched with the HCIs present in the chosen machine type. For 30675824d651Sblueswir1example when emulating a machine with only one HCI built into it, only 30685824d651Sblueswir1the first @code{-bt hci[...]} option is valid and defines the HCI's 30695824d651Sblueswir1logic. The Transport Layer is decided by the machine type. Currently 30705824d651Sblueswir1the machines @code{n800} and @code{n810} have one HCI and all other 30715824d651Sblueswir1machines have none. 30725824d651Sblueswir1 30735824d651Sblueswir1@anchor{bt-hcis} 30745824d651Sblueswir1The following three types are recognized: 30755824d651Sblueswir1 3076b3f046c2SKevin Wolf@table @option 30775824d651Sblueswir1@item -bt hci,null 30785824d651Sblueswir1(default) The corresponding Bluetooth HCI assumes no internal logic 30795824d651Sblueswir1and will not respond to any HCI commands or emit events. 30805824d651Sblueswir1 30815824d651Sblueswir1@item -bt hci,host[:@var{id}] 30825824d651Sblueswir1(@code{bluez} only) The corresponding HCI passes commands / events 30835824d651Sblueswir1to / from the physical HCI identified by the name @var{id} (default: 30845824d651Sblueswir1@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 30855824d651Sblueswir1capable systems like Linux. 30865824d651Sblueswir1 30875824d651Sblueswir1@item -bt hci[,vlan=@var{n}] 30885824d651Sblueswir1Add a virtual, standard HCI that will participate in the Bluetooth 30895824d651Sblueswir1scatternet @var{n} (default @code{0}). Similarly to @option{-net} 30905824d651Sblueswir1VLANs, devices inside a bluetooth network @var{n} can only communicate 30915824d651Sblueswir1with other devices in the same network (scatternet). 30925824d651Sblueswir1@end table 30935824d651Sblueswir1 30945824d651Sblueswir1@item -bt vhci[,vlan=@var{n}] 30955824d651Sblueswir1(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 30965824d651Sblueswir1to the host bluetooth stack instead of to the emulated target. This 30975824d651Sblueswir1allows the host and target machines to participate in a common scatternet 30985824d651Sblueswir1and communicate. Requires the Linux @code{vhci} driver installed. Can 30995824d651Sblueswir1be used as following: 31005824d651Sblueswir1 31015824d651Sblueswir1@example 31023804da9dSStefan Weilqemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 31035824d651Sblueswir1@end example 31045824d651Sblueswir1 31055824d651Sblueswir1@item -bt device:@var{dev}[,vlan=@var{n}] 31065824d651Sblueswir1Emulate a bluetooth device @var{dev} and place it in network @var{n} 31075824d651Sblueswir1(default @code{0}). QEMU can only emulate one type of bluetooth devices 31085824d651Sblueswir1currently: 31095824d651Sblueswir1 3110b3f046c2SKevin Wolf@table @option 31115824d651Sblueswir1@item keyboard 31125824d651Sblueswir1Virtual wireless keyboard implementing the HIDP bluetooth profile. 31135824d651Sblueswir1@end table 31145824d651Sblueswir1ETEXI 31155824d651Sblueswir1 3116c70a01e4SMarkus ArmbrusterSTEXI 3117c70a01e4SMarkus Armbruster@end table 3118c70a01e4SMarkus ArmbrusterETEXI 31195824d651Sblueswir1DEFHEADING() 31205824d651Sblueswir1 3121d1a0cf73SStefan Berger#ifdef CONFIG_TPM 312243f187a5SPaolo BonziniDEFHEADING(TPM device options) 3123d1a0cf73SStefan Berger 3124d1a0cf73SStefan BergerDEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 312592dcc234SStefan Berger "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 312692dcc234SStefan Berger " use path to provide path to a character device; default is /dev/tpm0\n" 312792dcc234SStefan Berger " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 3128f4ede81eSAmarnath Valluri " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 3129f4ede81eSAmarnath Valluri "-tpmdev emulator,id=id,chardev=dev\n" 3130f4ede81eSAmarnath Valluri " configure the TPM device using chardev backend\n", 3131d1a0cf73SStefan Berger QEMU_ARCH_ALL) 3132d1a0cf73SStefan BergerSTEXI 3133d1a0cf73SStefan Berger 3134d1a0cf73SStefan BergerThe general form of a TPM device option is: 3135d1a0cf73SStefan Berger@table @option 3136d1a0cf73SStefan Berger 3137d1a0cf73SStefan Berger@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 3138d1a0cf73SStefan Berger@findex -tpmdev 3139f4ede81eSAmarnath ValluriBackend type must be either one of the following: 3140f4ede81eSAmarnath Valluri@option{passthrough}, @option{emulator}. 3141d1a0cf73SStefan Berger 3142d1a0cf73SStefan BergerThe specific backend type will determine the applicable options. 314328c4fa32SCorey BryantThe @code{-tpmdev} option creates the TPM backend and requires a 314428c4fa32SCorey Bryant@code{-device} option that specifies the TPM frontend interface model. 3145d1a0cf73SStefan Berger 3146d1a0cf73SStefan BergerOptions to each backend are described below. 3147d1a0cf73SStefan Berger 3148d1a0cf73SStefan BergerUse 'help' to print all available TPM backend types. 3149d1a0cf73SStefan Berger@example 3150d1a0cf73SStefan Bergerqemu -tpmdev help 3151d1a0cf73SStefan Berger@end example 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 Berger@end table 3205d1a0cf73SStefan Berger 3206d1a0cf73SStefan BergerETEXI 3207d1a0cf73SStefan Berger 3208d1a0cf73SStefan BergerDEFHEADING() 3209d1a0cf73SStefan Berger 3210d1a0cf73SStefan Berger#endif 3211d1a0cf73SStefan Berger 321243f187a5SPaolo BonziniDEFHEADING(Linux/Multiboot boot specific) 32135824d651Sblueswir1STEXI 32147677f05dSAlexander Graf 32157677f05dSAlexander GrafWhen using these options, you can use a given Linux or Multiboot 32167677f05dSAlexander Grafkernel without installing it in the disk image. It can be useful 32175824d651Sblueswir1for easier testing of various kernels. 32185824d651Sblueswir1 32195824d651Sblueswir1@table @option 32205824d651Sblueswir1ETEXI 32215824d651Sblueswir1 32225824d651Sblueswir1DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 3223ad96090aSBlue Swirl "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 32245824d651Sblueswir1STEXI 32255824d651Sblueswir1@item -kernel @var{bzImage} 32266616b2adSStefan Weil@findex -kernel 32277677f05dSAlexander GrafUse @var{bzImage} as kernel image. The kernel can be either a Linux kernel 32287677f05dSAlexander Grafor in multiboot format. 32295824d651Sblueswir1ETEXI 32305824d651Sblueswir1 32315824d651Sblueswir1DEF("append", HAS_ARG, QEMU_OPTION_append, \ 3232ad96090aSBlue Swirl "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 32335824d651Sblueswir1STEXI 32345824d651Sblueswir1@item -append @var{cmdline} 32356616b2adSStefan Weil@findex -append 32365824d651Sblueswir1Use @var{cmdline} as kernel command line 32375824d651Sblueswir1ETEXI 32385824d651Sblueswir1 32395824d651Sblueswir1DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 3240ad96090aSBlue Swirl "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 32415824d651Sblueswir1STEXI 32425824d651Sblueswir1@item -initrd @var{file} 32436616b2adSStefan Weil@findex -initrd 32445824d651Sblueswir1Use @var{file} as initial ram disk. 32457677f05dSAlexander Graf 32467677f05dSAlexander Graf@item -initrd "@var{file1} arg=foo,@var{file2}" 32477677f05dSAlexander Graf 32487677f05dSAlexander GrafThis syntax is only available with multiboot. 32497677f05dSAlexander Graf 32507677f05dSAlexander GrafUse @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 32517677f05dSAlexander Graffirst module. 32525824d651Sblueswir1ETEXI 32535824d651Sblueswir1 3254412beee6SGrant LikelyDEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 3255379b5c7cSPeter A. G. Crosthwaite "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 3256412beee6SGrant LikelySTEXI 3257412beee6SGrant Likely@item -dtb @var{file} 3258412beee6SGrant Likely@findex -dtb 3259412beee6SGrant LikelyUse @var{file} as a device tree binary (dtb) image and pass it to the kernel 3260412beee6SGrant Likelyon boot. 3261412beee6SGrant LikelyETEXI 3262412beee6SGrant Likely 32635824d651Sblueswir1STEXI 32645824d651Sblueswir1@end table 32655824d651Sblueswir1ETEXI 32665824d651Sblueswir1DEFHEADING() 32675824d651Sblueswir1 326843f187a5SPaolo BonziniDEFHEADING(Debug/Expert options) 32695824d651Sblueswir1STEXI 32705824d651Sblueswir1@table @option 32715824d651Sblueswir1ETEXI 32725824d651Sblueswir1 327381b2b810SGabriel L. SomloDEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 327481b2b810SGabriel L. Somlo "-fw_cfg [name=]<name>,file=<file>\n" 327563d3145aSMarkus Armbruster " add named fw_cfg entry with contents from file\n" 32766407d76eSGabriel L. Somlo "-fw_cfg [name=]<name>,string=<str>\n" 327763d3145aSMarkus Armbruster " add named fw_cfg entry with contents from string\n", 327881b2b810SGabriel L. Somlo QEMU_ARCH_ALL) 327981b2b810SGabriel L. SomloSTEXI 328063d3145aSMarkus Armbruster 328181b2b810SGabriel L. Somlo@item -fw_cfg [name=]@var{name},file=@var{file} 328281b2b810SGabriel L. Somlo@findex -fw_cfg 328363d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from file @var{file}. 32846407d76eSGabriel L. Somlo 32856407d76eSGabriel L. Somlo@item -fw_cfg [name=]@var{name},string=@var{str} 328663d3145aSMarkus ArmbrusterAdd named fw_cfg entry with contents from string @var{str}. 328763d3145aSMarkus Armbruster 328863d3145aSMarkus ArmbrusterThe terminating NUL character of the contents of @var{str} will not be 328963d3145aSMarkus Armbrusterincluded as part of the fw_cfg item data. To insert contents with 329063d3145aSMarkus Armbrusterembedded NUL characters, you have to use the @var{file} parameter. 329163d3145aSMarkus Armbruster 329263d3145aSMarkus ArmbrusterThe fw_cfg entries are passed by QEMU through to the guest. 329363d3145aSMarkus Armbruster 329463d3145aSMarkus ArmbrusterExample: 329563d3145aSMarkus Armbruster@example 329663d3145aSMarkus Armbruster -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 329763d3145aSMarkus Armbruster@end example 329863d3145aSMarkus Armbrustercreates an fw_cfg entry named opt/com.mycompany/blob with contents 329963d3145aSMarkus Armbrusterfrom ./my_blob.bin. 330063d3145aSMarkus Armbruster 330181b2b810SGabriel L. SomloETEXI 330281b2b810SGabriel L. Somlo 33035824d651Sblueswir1DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3304ad96090aSBlue Swirl "-serial dev redirect the serial port to char device 'dev'\n", 3305ad96090aSBlue Swirl QEMU_ARCH_ALL) 33065824d651Sblueswir1STEXI 33075824d651Sblueswir1@item -serial @var{dev} 33086616b2adSStefan Weil@findex -serial 33095824d651Sblueswir1Redirect the virtual serial port to host character device 33105824d651Sblueswir1@var{dev}. The default device is @code{vc} in graphical mode and 33115824d651Sblueswir1@code{stdio} in non graphical mode. 33125824d651Sblueswir1 33135824d651Sblueswir1This option can be used several times to simulate up to 4 serial 33145824d651Sblueswir1ports. 33155824d651Sblueswir1 33165824d651Sblueswir1Use @code{-serial none} to disable all serial ports. 33175824d651Sblueswir1 33185824d651Sblueswir1Available character devices are: 3319b3f046c2SKevin Wolf@table @option 33204e257e5eSKevin Wolf@item vc[:@var{W}x@var{H}] 33215824d651Sblueswir1Virtual console. Optionally, a width and height can be given in pixel with 33225824d651Sblueswir1@example 33235824d651Sblueswir1vc:800x600 33245824d651Sblueswir1@end example 33255824d651Sblueswir1It is also possible to specify width or height in characters: 33265824d651Sblueswir1@example 33275824d651Sblueswir1vc:80Cx24C 33285824d651Sblueswir1@end example 33295824d651Sblueswir1@item pty 33305824d651Sblueswir1[Linux only] Pseudo TTY (a new PTY is automatically allocated) 33315824d651Sblueswir1@item none 33325824d651Sblueswir1No device is allocated. 33335824d651Sblueswir1@item null 33345824d651Sblueswir1void device 333588e020e5SIngo van Lil@item chardev:@var{id} 333688e020e5SIngo van LilUse a named character device defined with the @code{-chardev} option. 33375824d651Sblueswir1@item /dev/XXX 33385824d651Sblueswir1[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 33395824d651Sblueswir1parameters are set according to the emulated ones. 33405824d651Sblueswir1@item /dev/parport@var{N} 33415824d651Sblueswir1[Linux only, parallel port only] Use host parallel port 33425824d651Sblueswir1@var{N}. Currently SPP and EPP parallel port features can be used. 33435824d651Sblueswir1@item file:@var{filename} 33445824d651Sblueswir1Write output to @var{filename}. No character can be read. 33455824d651Sblueswir1@item stdio 33465824d651Sblueswir1[Unix only] standard input/output 33475824d651Sblueswir1@item pipe:@var{filename} 33485824d651Sblueswir1name pipe @var{filename} 33495824d651Sblueswir1@item COM@var{n} 33505824d651Sblueswir1[Windows only] Use host serial port @var{n} 33515824d651Sblueswir1@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 33525824d651Sblueswir1This implements UDP Net Console. 33535824d651Sblueswir1When @var{remote_host} or @var{src_ip} are not specified 33545824d651Sblueswir1they default to @code{0.0.0.0}. 33555824d651Sblueswir1When not using a specified @var{src_port} a random port is automatically chosen. 33565824d651Sblueswir1 33575824d651Sblueswir1If you just want a simple readonly console you can use @code{netcat} or 3358b65ee4faSStefan Weil@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3359b65ee4faSStefan Weil@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 33605824d651Sblueswir1will appear in the netconsole session. 33615824d651Sblueswir1 33625824d651Sblueswir1If you plan to send characters back via netconsole or you want to stop 3363b65ee4faSStefan Weiland start QEMU a lot of times, you should have QEMU use the same 33645824d651Sblueswir1source port each time by using something like @code{-serial 3365b65ee4faSStefan Weiludp::4555@@:4556} to QEMU. Another approach is to use a patched 33665824d651Sblueswir1version of netcat which can listen to a TCP port and send and receive 33675824d651Sblueswir1characters via udp. If you have a patched version of netcat which 33685824d651Sblueswir1activates telnet remote echo and single char transfer, then you can 3369bd1caa3fSMarc-André Lureauuse the following options to set up a netcat redirector to allow 3370b65ee4faSStefan Weiltelnet on port 5555 to access the QEMU port. 33715824d651Sblueswir1@table @code 3372071c9394SStefan Weil@item QEMU Options: 33735824d651Sblueswir1-serial udp::4555@@:4556 33745824d651Sblueswir1@item netcat options: 33755824d651Sblueswir1-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 33765824d651Sblueswir1@item telnet options: 33775824d651Sblueswir1localhost 5555 33785824d651Sblueswir1@end table 33795824d651Sblueswir1 33805dd1f02bSCorey Minyard@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 33815824d651Sblueswir1The TCP Net Console has two modes of operation. It can send the serial 33825824d651Sblueswir1I/O to a location or wait for a connection from a location. By default 33835824d651Sblueswir1the TCP Net Console is sent to @var{host} at the @var{port}. If you use 33845824d651Sblueswir1the @var{server} option QEMU will wait for a client socket application 33855824d651Sblueswir1to connect to the port before continuing, unless the @code{nowait} 33865824d651Sblueswir1option was specified. The @code{nodelay} option disables the Nagle buffering 33875dd1f02bSCorey Minyardalgorithm. The @code{reconnect} option only applies if @var{noserver} is 33885dd1f02bSCorey Minyardset, if the connection goes down it will attempt to reconnect at the 33895dd1f02bSCorey Minyardgiven interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 33905824d651Sblueswir1one TCP connection at a time is accepted. You can use @code{telnet} to 33915824d651Sblueswir1connect to the corresponding character device. 33925824d651Sblueswir1@table @code 33935824d651Sblueswir1@item Example to send tcp console to 192.168.0.2 port 4444 33945824d651Sblueswir1-serial tcp:192.168.0.2:4444 33955824d651Sblueswir1@item Example to listen and wait on port 4444 for connection 33965824d651Sblueswir1-serial tcp::4444,server 33975824d651Sblueswir1@item Example to not wait and listen on ip 192.168.0.100 port 4444 33985824d651Sblueswir1-serial tcp:192.168.0.100:4444,server,nowait 33995824d651Sblueswir1@end table 34005824d651Sblueswir1 34015824d651Sblueswir1@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 34025824d651Sblueswir1The telnet protocol is used instead of raw tcp sockets. The options 34035824d651Sblueswir1work the same as if you had specified @code{-serial tcp}. The 34045824d651Sblueswir1difference is that the port acts like a telnet server or client using 34055824d651Sblueswir1telnet option negotiation. This will also allow you to send the 34065824d651Sblueswir1MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 34075824d651Sblueswir1sequence. Typically in unix telnet you do it with Control-] and then 34085824d651Sblueswir1type "send break" followed by pressing the enter key. 34095824d651Sblueswir1 34105dd1f02bSCorey Minyard@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 34115824d651Sblueswir1A unix domain socket is used instead of a tcp socket. The option works the 34125824d651Sblueswir1same as if you had specified @code{-serial tcp} except the unix domain socket 34135824d651Sblueswir1@var{path} is used for connections. 34145824d651Sblueswir1 34155824d651Sblueswir1@item mon:@var{dev_string} 34165824d651Sblueswir1This is a special option to allow the monitor to be multiplexed onto 34175824d651Sblueswir1another serial port. The monitor is accessed with key sequence of 341802c4bdf1SPaolo Bonzini@key{Control-a} and then pressing @key{c}. 34195824d651Sblueswir1@var{dev_string} should be any one of the serial devices specified 34205824d651Sblueswir1above. An example to multiplex the monitor onto a telnet server 34215824d651Sblueswir1listening on port 4444 would be: 34225824d651Sblueswir1@table @code 34235824d651Sblueswir1@item -serial mon:telnet::4444,server,nowait 34245824d651Sblueswir1@end table 3425be022d61SMichael TokarevWhen the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 342602c4bdf1SPaolo BonziniQEMU any more but will be passed to the guest instead. 34275824d651Sblueswir1 34285824d651Sblueswir1@item braille 34295824d651Sblueswir1Braille device. This will use BrlAPI to display the braille output on a real 34305824d651Sblueswir1or fake device. 34315824d651Sblueswir1 3432be8b28a9SKevin Wolf@item msmouse 3433be8b28a9SKevin WolfThree button serial mouse. Configure the guest to use Microsoft protocol. 34345824d651Sblueswir1@end table 34355824d651Sblueswir1ETEXI 34365824d651Sblueswir1 34375824d651Sblueswir1DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3438ad96090aSBlue Swirl "-parallel dev redirect the parallel port to char device 'dev'\n", 3439ad96090aSBlue Swirl QEMU_ARCH_ALL) 34405824d651Sblueswir1STEXI 34415824d651Sblueswir1@item -parallel @var{dev} 34426616b2adSStefan Weil@findex -parallel 34435824d651Sblueswir1Redirect the virtual parallel port to host device @var{dev} (same 34445824d651Sblueswir1devices as the serial port). On Linux hosts, @file{/dev/parportN} can 34455824d651Sblueswir1be used to use hardware devices connected on the corresponding host 34465824d651Sblueswir1parallel port. 34475824d651Sblueswir1 34485824d651Sblueswir1This option can be used several times to simulate up to 3 parallel 34495824d651Sblueswir1ports. 34505824d651Sblueswir1 34515824d651Sblueswir1Use @code{-parallel none} to disable all parallel ports. 34525824d651Sblueswir1ETEXI 34535824d651Sblueswir1 34545824d651Sblueswir1DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3455ad96090aSBlue Swirl "-monitor dev redirect the monitor to char device 'dev'\n", 3456ad96090aSBlue Swirl QEMU_ARCH_ALL) 34575824d651Sblueswir1STEXI 34584e307fc8SGerd Hoffmann@item -monitor @var{dev} 34596616b2adSStefan Weil@findex -monitor 34605824d651Sblueswir1Redirect the monitor to host device @var{dev} (same devices as the 34615824d651Sblueswir1serial port). 34625824d651Sblueswir1The default device is @code{vc} in graphical mode and @code{stdio} in 34635824d651Sblueswir1non graphical mode. 346470e098afSLuiz CapitulinoUse @code{-monitor none} to disable the default monitor. 34655824d651Sblueswir1ETEXI 34666ca5582dSGerd HoffmannDEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3467ad96090aSBlue Swirl "-qmp dev like -monitor but opens in 'control' mode\n", 3468ad96090aSBlue Swirl QEMU_ARCH_ALL) 346995d5f08bSStefan WeilSTEXI 347095d5f08bSStefan Weil@item -qmp @var{dev} 34716616b2adSStefan Weil@findex -qmp 347295d5f08bSStefan WeilLike -monitor but opens in 'control' mode. 347395d5f08bSStefan WeilETEXI 34744821cd4cSMax ReitzDEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 34754821cd4cSMax Reitz "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 34764821cd4cSMax Reitz QEMU_ARCH_ALL) 34774821cd4cSMax ReitzSTEXI 34784821cd4cSMax Reitz@item -qmp-pretty @var{dev} 34794821cd4cSMax Reitz@findex -qmp-pretty 34804821cd4cSMax ReitzLike -qmp but uses pretty JSON formatting. 34814821cd4cSMax ReitzETEXI 34825824d651Sblueswir1 348322a0e04bSGerd HoffmannDEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3484bdbcb547SMarc-André Lureau "-mon [chardev=]name[,mode=readline|control]\n", QEMU_ARCH_ALL) 348522a0e04bSGerd HoffmannSTEXI 3486bdbcb547SMarc-André Lureau@item -mon [chardev=]name[,mode=readline|control] 34876616b2adSStefan Weil@findex -mon 348822a0e04bSGerd HoffmannSetup monitor on chardev @var{name}. 348922a0e04bSGerd HoffmannETEXI 349022a0e04bSGerd Hoffmann 3491c9f398e5SH. Peter AnvinDEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3492ad96090aSBlue Swirl "-debugcon dev redirect the debug console to char device 'dev'\n", 3493ad96090aSBlue Swirl QEMU_ARCH_ALL) 3494c9f398e5SH. Peter AnvinSTEXI 3495c9f398e5SH. Peter Anvin@item -debugcon @var{dev} 34966616b2adSStefan Weil@findex -debugcon 3497c9f398e5SH. Peter AnvinRedirect the debug console to host device @var{dev} (same devices as the 3498c9f398e5SH. Peter Anvinserial port). The debug console is an I/O port which is typically port 3499c9f398e5SH. Peter Anvin0xe9; writing to that I/O port sends output to this device. 3500c9f398e5SH. Peter AnvinThe default device is @code{vc} in graphical mode and @code{stdio} in 3501c9f398e5SH. Peter Anvinnon graphical mode. 3502c9f398e5SH. Peter AnvinETEXI 3503c9f398e5SH. Peter Anvin 35045824d651Sblueswir1DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3505ad96090aSBlue Swirl "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 35065824d651Sblueswir1STEXI 35075824d651Sblueswir1@item -pidfile @var{file} 35086616b2adSStefan Weil@findex -pidfile 35095824d651Sblueswir1Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 35105824d651Sblueswir1from a script. 35115824d651Sblueswir1ETEXI 35125824d651Sblueswir1 35131b530a6dSaurel32DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3514ad96090aSBlue Swirl "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 35151b530a6dSaurel32STEXI 35161b530a6dSaurel32@item -singlestep 35176616b2adSStefan Weil@findex -singlestep 35181b530a6dSaurel32Run the emulation in single step mode. 35191b530a6dSaurel32ETEXI 35201b530a6dSaurel32 35215824d651Sblueswir1DEF("S", 0, QEMU_OPTION_S, \ 3522ad96090aSBlue Swirl "-S freeze CPU at startup (use 'c' to start execution)\n", 3523ad96090aSBlue Swirl QEMU_ARCH_ALL) 35245824d651Sblueswir1STEXI 35255824d651Sblueswir1@item -S 35266616b2adSStefan Weil@findex -S 35275824d651Sblueswir1Do not start CPU at startup (you must type 'c' in the monitor). 35285824d651Sblueswir1ETEXI 35295824d651Sblueswir1 3530888a6bc6SSatoru MoriyaDEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3531888a6bc6SSatoru Moriya "-realtime [mlock=on|off]\n" 3532888a6bc6SSatoru Moriya " run qemu with realtime features\n" 3533888a6bc6SSatoru Moriya " mlock=on|off controls mlock support (default: on)\n", 3534888a6bc6SSatoru Moriya QEMU_ARCH_ALL) 3535888a6bc6SSatoru MoriyaSTEXI 3536888a6bc6SSatoru Moriya@item -realtime mlock=on|off 3537888a6bc6SSatoru Moriya@findex -realtime 3538888a6bc6SSatoru MoriyaRun qemu with realtime features. 3539888a6bc6SSatoru Moriyamlocking qemu and guest memory can be enabled via @option{mlock=on} 3540888a6bc6SSatoru Moriya(enabled by default). 3541888a6bc6SSatoru MoriyaETEXI 3542888a6bc6SSatoru Moriya 354359030a8cSaliguoriDEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3544ad96090aSBlue Swirl "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 35455824d651Sblueswir1STEXI 354659030a8cSaliguori@item -gdb @var{dev} 35476616b2adSStefan Weil@findex -gdb 354859030a8cSaliguoriWait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 354959030a8cSaliguoriconnections will likely be TCP-based, but also UDP, pseudo TTY, or even 3550b65ee4faSStefan Weilstdio are reasonable use case. The latter is allowing to start QEMU from 355159030a8cSaliguoriwithin gdb and establish the connection via a pipe: 355259030a8cSaliguori@example 35533804da9dSStefan Weil(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 355459030a8cSaliguori@end example 35555824d651Sblueswir1ETEXI 35565824d651Sblueswir1 355759030a8cSaliguoriDEF("s", 0, QEMU_OPTION_s, \ 3558ad96090aSBlue Swirl "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3559ad96090aSBlue Swirl QEMU_ARCH_ALL) 35605824d651Sblueswir1STEXI 356159030a8cSaliguori@item -s 35626616b2adSStefan Weil@findex -s 356359030a8cSaliguoriShorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 356459030a8cSaliguori(@pxref{gdb_usage}). 35655824d651Sblueswir1ETEXI 35665824d651Sblueswir1 35675824d651Sblueswir1DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3568989b697dSPeter Maydell "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3569ad96090aSBlue Swirl QEMU_ARCH_ALL) 35705824d651Sblueswir1STEXI 3571989b697dSPeter Maydell@item -d @var{item1}[,...] 35726616b2adSStefan Weil@findex -d 3573989b697dSPeter MaydellEnable logging of specified items. Use '-d help' for a list of log items. 35745824d651Sblueswir1ETEXI 35755824d651Sblueswir1 3576c235d738SMatthew FernandezDEF("D", HAS_ARG, QEMU_OPTION_D, \ 3577989b697dSPeter Maydell "-D logfile output log to logfile (default stderr)\n", 3578c235d738SMatthew Fernandez QEMU_ARCH_ALL) 3579c235d738SMatthew FernandezSTEXI 35808bd383b4SStefan Weil@item -D @var{logfile} 3581c235d738SMatthew Fernandez@findex -D 3582989b697dSPeter MaydellOutput log in @var{logfile} instead of to stderr 3583c235d738SMatthew FernandezETEXI 3584c235d738SMatthew Fernandez 35853514552eSAlex BennéeDEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 35863514552eSAlex Bennée "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 35873514552eSAlex Bennée QEMU_ARCH_ALL) 35883514552eSAlex BennéeSTEXI 35893514552eSAlex Bennée@item -dfilter @var{range1}[,...] 35903514552eSAlex Bennée@findex -dfilter 35913514552eSAlex BennéeFilter debug output to that relevant to a range of target addresses. The filter 35923514552eSAlex Bennéespec can be either @var{start}+@var{size}, @var{start}-@var{size} or 35933514552eSAlex Bennée@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 35943514552eSAlex Bennéeaddresses and sizes required. For example: 35953514552eSAlex Bennée@example 35963514552eSAlex Bennée -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 35973514552eSAlex Bennée@end example 35983514552eSAlex BennéeWill dump output for any code in the 0x1000 sized block starting at 0x8000 and 35993514552eSAlex Bennéethe 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 36003514552eSAlex Bennéeblock starting at 0xffffffc00005f000. 36013514552eSAlex BennéeETEXI 36023514552eSAlex Bennée 36035824d651Sblueswir1DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3604ad96090aSBlue Swirl "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3605ad96090aSBlue Swirl QEMU_ARCH_ALL) 36065824d651Sblueswir1STEXI 36075824d651Sblueswir1@item -L @var{path} 36086616b2adSStefan Weil@findex -L 36095824d651Sblueswir1Set the directory for the BIOS, VGA BIOS and keymaps. 361037146e7eSRichard W.M. Jones 361137146e7eSRichard W.M. JonesTo list all the data directories, use @code{-L help}. 36125824d651Sblueswir1ETEXI 36135824d651Sblueswir1 36145824d651Sblueswir1DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3615ad96090aSBlue Swirl "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 36165824d651Sblueswir1STEXI 36175824d651Sblueswir1@item -bios @var{file} 36186616b2adSStefan Weil@findex -bios 36195824d651Sblueswir1Set the filename for the BIOS. 36205824d651Sblueswir1ETEXI 36215824d651Sblueswir1 36225824d651Sblueswir1DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3623ad96090aSBlue Swirl "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 36245824d651Sblueswir1STEXI 36255824d651Sblueswir1@item -enable-kvm 36266616b2adSStefan Weil@findex -enable-kvm 36275824d651Sblueswir1Enable KVM full virtualization support. This option is only available 36285824d651Sblueswir1if KVM support is enabled when compiling. 36295824d651Sblueswir1ETEXI 36305824d651Sblueswir1 3631b0cb0a66SVincent PalatinDEF("enable-hax", 0, QEMU_OPTION_enable_hax, \ 3632b0cb0a66SVincent Palatin "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386) 3633b0cb0a66SVincent PalatinSTEXI 3634b0cb0a66SVincent Palatin@item -enable-hax 3635b0cb0a66SVincent Palatin@findex -enable-hax 3636b0cb0a66SVincent PalatinEnable HAX (Hardware-based Acceleration eXecution) support. This option 3637b0cb0a66SVincent Palatinis only available if HAX support is enabled when compiling. HAX is only 3638b0cb0a66SVincent Palatinapplicable to MAC and Windows platform, and thus does not conflict with 3639b0cb0a66SVincent PalatinKVM. 3640b0cb0a66SVincent PalatinETEXI 3641b0cb0a66SVincent Palatin 3642e37630caSaliguoriDEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3643ad96090aSBlue Swirl "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3644e37630caSaliguoriDEF("xen-create", 0, QEMU_OPTION_xen_create, 3645e37630caSaliguori "-xen-create create domain using xen hypercalls, bypassing xend\n" 3646ad96090aSBlue Swirl " warning: should not be used when xend is in use\n", 3647ad96090aSBlue Swirl QEMU_ARCH_ALL) 3648e37630caSaliguoriDEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3649e37630caSaliguori "-xen-attach attach to existing xen domain\n" 3650b65ee4faSStefan Weil " xend will use this when starting QEMU\n", 3651ad96090aSBlue Swirl QEMU_ARCH_ALL) 36521c599472SPaul DurrantDEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 36531c599472SPaul Durrant "-xen-domid-restrict restrict set of available xen operations\n" 36541c599472SPaul Durrant " to specified domain id. (Does not affect\n" 36551c599472SPaul Durrant " xenpv machine type).\n", 36561c599472SPaul Durrant QEMU_ARCH_ALL) 365795d5f08bSStefan WeilSTEXI 365895d5f08bSStefan Weil@item -xen-domid @var{id} 36596616b2adSStefan Weil@findex -xen-domid 366095d5f08bSStefan WeilSpecify xen guest domain @var{id} (XEN only). 366195d5f08bSStefan Weil@item -xen-create 36626616b2adSStefan Weil@findex -xen-create 366395d5f08bSStefan WeilCreate domain using xen hypercalls, bypassing xend. 366495d5f08bSStefan WeilWarning: should not be used when xend is in use (XEN only). 366595d5f08bSStefan Weil@item -xen-attach 36666616b2adSStefan Weil@findex -xen-attach 366795d5f08bSStefan WeilAttach to existing xen domain. 3668b65ee4faSStefan Weilxend will use this when starting QEMU (XEN only). 36691c599472SPaul Durrant@findex -xen-domid-restrict 36701c599472SPaul DurrantRestrict set of available xen operations to specified domain id (XEN only). 367195d5f08bSStefan WeilETEXI 3672e37630caSaliguori 36735824d651Sblueswir1DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3674ad96090aSBlue Swirl "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 36755824d651Sblueswir1STEXI 36765824d651Sblueswir1@item -no-reboot 36776616b2adSStefan Weil@findex -no-reboot 36785824d651Sblueswir1Exit instead of rebooting. 36795824d651Sblueswir1ETEXI 36805824d651Sblueswir1 36815824d651Sblueswir1DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3682ad96090aSBlue Swirl "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 36835824d651Sblueswir1STEXI 36845824d651Sblueswir1@item -no-shutdown 36856616b2adSStefan Weil@findex -no-shutdown 36865824d651Sblueswir1Don't exit QEMU on guest shutdown, but instead only stop the emulation. 36875824d651Sblueswir1This allows for instance switching to monitor to commit changes to the 36885824d651Sblueswir1disk image. 36895824d651Sblueswir1ETEXI 36905824d651Sblueswir1 36915824d651Sblueswir1DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 36925824d651Sblueswir1 "-loadvm [tag|id]\n" \ 3693ad96090aSBlue Swirl " start right away with a saved state (loadvm in monitor)\n", 3694ad96090aSBlue Swirl QEMU_ARCH_ALL) 36955824d651Sblueswir1STEXI 36965824d651Sblueswir1@item -loadvm @var{file} 36976616b2adSStefan Weil@findex -loadvm 36985824d651Sblueswir1Start right away with a saved state (@code{loadvm} in monitor) 36995824d651Sblueswir1ETEXI 37005824d651Sblueswir1 37015824d651Sblueswir1#ifndef _WIN32 37025824d651Sblueswir1DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3703ad96090aSBlue Swirl "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 37045824d651Sblueswir1#endif 37055824d651Sblueswir1STEXI 37065824d651Sblueswir1@item -daemonize 37076616b2adSStefan Weil@findex -daemonize 37085824d651Sblueswir1Daemonize the QEMU process after initialization. QEMU will not detach from 37095824d651Sblueswir1standard IO until it is ready to receive connections on any of its devices. 37105824d651Sblueswir1This option is a useful way for external programs to launch QEMU without having 37115824d651Sblueswir1to cope with initialization race conditions. 37125824d651Sblueswir1ETEXI 37135824d651Sblueswir1 37145824d651Sblueswir1DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3715ad96090aSBlue Swirl "-option-rom rom load a file, rom, into the option ROM space\n", 3716ad96090aSBlue Swirl QEMU_ARCH_ALL) 37175824d651Sblueswir1STEXI 37185824d651Sblueswir1@item -option-rom @var{file} 37196616b2adSStefan Weil@findex -option-rom 37205824d651Sblueswir1Load the contents of @var{file} as an option ROM. 37215824d651Sblueswir1This option is useful to load things like EtherBoot. 37225824d651Sblueswir1ETEXI 37235824d651Sblueswir1 3724e218052fSMarkus ArmbrusterHXCOMM Silently ignored for compatibility 3725e218052fSMarkus ArmbrusterDEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 37265824d651Sblueswir1 37271ed2fc1fSJan KiszkaHXCOMM Options deprecated by -rtc 3728ad96090aSBlue SwirlDEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 3729ad96090aSBlue SwirlDEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 37305824d651Sblueswir1 37311ed2fc1fSJan KiszkaDEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 373278808141SPaolo Bonzini "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3733ad96090aSBlue Swirl " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3734ad96090aSBlue Swirl QEMU_ARCH_ALL) 37351ed2fc1fSJan Kiszka 37365824d651Sblueswir1STEXI 37375824d651Sblueswir1 37386875204cSJan Kiszka@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 37396616b2adSStefan Weil@findex -rtc 37401ed2fc1fSJan KiszkaSpecify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 37411ed2fc1fSJan KiszkaUTC or local time, respectively. @code{localtime} is required for correct date in 37421ed2fc1fSJan KiszkaMS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 37431ed2fc1fSJan Kiszkaformat @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 37441ed2fc1fSJan Kiszka 37459d85d557SMichael TokarevBy default the RTC is driven by the host system time. This allows using of the 37466875204cSJan KiszkaRTC as accurate reference clock inside the guest, specifically if the host 37476875204cSJan Kiszkatime is smoothly following an accurate external reference clock, e.g. via NTP. 374878808141SPaolo BonziniIf you want to isolate the guest time from the host, you can set @option{clock} 374978808141SPaolo Bonzinito @code{rt} instead. To even prevent it from progressing during suspension, 375078808141SPaolo Bonziniyou can set it to @code{vm}. 37516875204cSJan Kiszka 37521ed2fc1fSJan KiszkaEnable @option{driftfix} (i386 targets only) if you experience time drift problems, 37531ed2fc1fSJan Kiszkaspecifically with Windows' ACPI HAL. This option will try to figure out how 37541ed2fc1fSJan Kiszkamany timer interrupts were not processed by the Windows guest and will 37551ed2fc1fSJan Kiszkare-inject them. 37565824d651Sblueswir1ETEXI 37575824d651Sblueswir1 37585824d651Sblueswir1DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 37599c2037d0SPavel Dovgalyuk "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3760bc14ca24Saliguori " enable virtual instruction counter with 2^N clock ticks per\n" \ 3761f1f4b57eSVictor CLEMENT " instruction, enable aligning the host and virtual clocks\n" \ 3762f1f4b57eSVictor CLEMENT " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 37635824d651Sblueswir1STEXI 37649c2037d0SPavel Dovgalyuk@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 37656616b2adSStefan Weil@findex -icount 37665824d651Sblueswir1Enable virtual instruction counter. The virtual cpu will execute one 37674e257e5eSKevin Wolfinstruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 37685824d651Sblueswir1then the virtual cpu speed will be automatically adjusted to keep virtual 37695824d651Sblueswir1time within a few seconds of real time. 37705824d651Sblueswir1 3771f1f4b57eSVictor CLEMENTWhen the virtual cpu is sleeping, the virtual time will advance at default 3772778d9f9bSPranith Kumarspeed unless @option{sleep=on|off} is specified. 3773778d9f9bSPranith KumarWith @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3774f1f4b57eSVictor CLEMENTinstantly whenever the virtual cpu goes to sleep mode and will not advance 3775f1f4b57eSVictor CLEMENTif no timer is enabled. This behavior give deterministic execution times from 3776f1f4b57eSVictor CLEMENTthe guest point of view. 3777f1f4b57eSVictor CLEMENT 37785824d651Sblueswir1Note that while this option can give deterministic behavior, it does not 37795824d651Sblueswir1provide cycle accurate emulation. Modern CPUs contain superscalar out of 37805824d651Sblueswir1order cores with complex cache hierarchies. The number of instructions 37815824d651Sblueswir1executed often has little or no correlation with actual performance. 3782a8bfac37SSebastian Tanase 3783b6af0975SDaniel P. Berrange@option{align=on} will activate the delay algorithm which will try 3784a8bfac37SSebastian Tanaseto synchronise the host clock and the virtual clock. The goal is to 3785a8bfac37SSebastian Tanasehave a guest running at the real frequency imposed by the shift option. 3786a8bfac37SSebastian TanaseWhenever the guest clock is behind the host clock and if 378782597615SMichael Tokarev@option{align=on} is specified then we print a message to the user 3788a8bfac37SSebastian Tanaseto inform about the delay. 3789a8bfac37SSebastian TanaseCurrently this option does not work when @option{shift} is @code{auto}. 3790a8bfac37SSebastian TanaseNote: The sync algorithm will work for those shift values for which 3791a8bfac37SSebastian Tanasethe guest clock runs ahead of the host clock. Typically this happens 3792a8bfac37SSebastian Tanasewhen the shift value is high (how high depends on the host machine). 37934c27b859SPavel Dovgalyuk 37944c27b859SPavel DovgalyukWhen @option{rr} option is specified deterministic record/replay is enabled. 37954c27b859SPavel DovgalyukReplay log is written into @var{filename} file in record mode and 37964c27b859SPavel Dovgalyukread from this file in replay mode. 37979c2037d0SPavel Dovgalyuk 37989c2037d0SPavel DovgalyukOption rrsnapshot is used to create new vm snapshot named @var{snapshot} 37999c2037d0SPavel Dovgalyukat the start of execution recording. In replay mode this option is used 38009c2037d0SPavel Dovgalyukto load the initial VM state. 38015824d651Sblueswir1ETEXI 38025824d651Sblueswir1 38039dd986ccSRichard W.M. JonesDEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3804d7933ef3SXu Wang "-watchdog model\n" \ 3805ad96090aSBlue Swirl " enable virtual hardware watchdog [default=none]\n", 3806ad96090aSBlue Swirl QEMU_ARCH_ALL) 38079dd986ccSRichard W.M. JonesSTEXI 38089dd986ccSRichard W.M. Jones@item -watchdog @var{model} 38096616b2adSStefan Weil@findex -watchdog 38109dd986ccSRichard W.M. JonesCreate a virtual hardware watchdog device. Once enabled (by a guest 38119dd986ccSRichard W.M. Jonesaction), the watchdog must be periodically polled by an agent inside 3812d7933ef3SXu Wangthe guest or else the guest will be restarted. Choose a model for 3813d7933ef3SXu Wangwhich your guest has drivers. 38149dd986ccSRichard W.M. Jones 3815d7933ef3SXu WangThe @var{model} is the model of hardware watchdog to emulate. Use 3816d7933ef3SXu Wang@code{-watchdog help} to list available hardware models. Only one 38179dd986ccSRichard W.M. Joneswatchdog can be enabled for a guest. 3818d7933ef3SXu Wang 3819d7933ef3SXu WangThe following models may be available: 3820d7933ef3SXu Wang@table @option 3821d7933ef3SXu Wang@item ib700 3822d7933ef3SXu WangiBASE 700 is a very simple ISA watchdog with a single timer. 3823d7933ef3SXu Wang@item i6300esb 3824d7933ef3SXu WangIntel 6300ESB I/O controller hub is a much more featureful PCI-based 3825d7933ef3SXu Wangdual-timer watchdog. 3826188f24c2SXu Wang@item diag288 3827188f24c2SXu WangA virtual watchdog for s390x backed by the diagnose 288 hypercall 3828188f24c2SXu Wang(currently KVM only). 3829d7933ef3SXu Wang@end table 38309dd986ccSRichard W.M. JonesETEXI 38319dd986ccSRichard W.M. Jones 38329dd986ccSRichard W.M. JonesDEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 38339dd986ccSRichard W.M. Jones "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 3834ad96090aSBlue Swirl " action when watchdog fires [default=reset]\n", 3835ad96090aSBlue Swirl QEMU_ARCH_ALL) 38369dd986ccSRichard W.M. JonesSTEXI 38379dd986ccSRichard W.M. Jones@item -watchdog-action @var{action} 3838b8f490ebSMarkus Armbruster@findex -watchdog-action 38399dd986ccSRichard W.M. Jones 38409dd986ccSRichard W.M. JonesThe @var{action} controls what QEMU will do when the watchdog timer 38419dd986ccSRichard W.M. Jonesexpires. 38429dd986ccSRichard W.M. JonesThe default is 38439dd986ccSRichard W.M. Jones@code{reset} (forcefully reset the guest). 38449dd986ccSRichard W.M. JonesOther possible actions are: 38459dd986ccSRichard W.M. Jones@code{shutdown} (attempt to gracefully shutdown the guest), 38469dd986ccSRichard W.M. Jones@code{poweroff} (forcefully poweroff the guest), 38479dd986ccSRichard W.M. Jones@code{pause} (pause the guest), 38489dd986ccSRichard W.M. Jones@code{debug} (print a debug message and continue), or 38499dd986ccSRichard W.M. Jones@code{none} (do nothing). 38509dd986ccSRichard W.M. Jones 38519dd986ccSRichard W.M. JonesNote that the @code{shutdown} action requires that the guest responds 38529dd986ccSRichard W.M. Jonesto ACPI signals, which it may not be able to do in the sort of 38539dd986ccSRichard W.M. Jonessituations where the watchdog would have expired, and thus 38549dd986ccSRichard W.M. Jones@code{-watchdog-action shutdown} is not recommended for production use. 38559dd986ccSRichard W.M. Jones 38569dd986ccSRichard W.M. JonesExamples: 38579dd986ccSRichard W.M. Jones 38589dd986ccSRichard W.M. Jones@table @code 38599dd986ccSRichard W.M. Jones@item -watchdog i6300esb -watchdog-action pause 3860f9cfd655SMarkus Armbruster@itemx -watchdog ib700 38619dd986ccSRichard W.M. Jones@end table 38629dd986ccSRichard W.M. JonesETEXI 38639dd986ccSRichard W.M. Jones 38645824d651Sblueswir1DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3865ad96090aSBlue Swirl "-echr chr set terminal escape character instead of ctrl-a\n", 3866ad96090aSBlue Swirl QEMU_ARCH_ALL) 38675824d651Sblueswir1STEXI 38685824d651Sblueswir1 38694e257e5eSKevin Wolf@item -echr @var{numeric_ascii_value} 38706616b2adSStefan Weil@findex -echr 38715824d651Sblueswir1Change the escape character used for switching to the monitor when using 38725824d651Sblueswir1monitor and serial sharing. The default is @code{0x01} when using the 38735824d651Sblueswir1@code{-nographic} option. @code{0x01} is equal to pressing 38745824d651Sblueswir1@code{Control-a}. You can select a different character from the ascii 38755824d651Sblueswir1control keys where 1 through 26 map to Control-a through Control-z. For 38765824d651Sblueswir1instance you could use the either of the following to change the escape 38775824d651Sblueswir1character to Control-t. 38785824d651Sblueswir1@table @code 38795824d651Sblueswir1@item -echr 0x14 3880f9cfd655SMarkus Armbruster@itemx -echr 20 38815824d651Sblueswir1@end table 38825824d651Sblueswir1ETEXI 38835824d651Sblueswir1 38845824d651Sblueswir1DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 38855824d651Sblueswir1 "-virtioconsole c\n" \ 3886ad96090aSBlue Swirl " set virtio console\n", QEMU_ARCH_ALL) 38875824d651Sblueswir1STEXI 38885824d651Sblueswir1@item -virtioconsole @var{c} 38896616b2adSStefan Weil@findex -virtioconsole 38905824d651Sblueswir1Set virtio console. 389198b19252SAmit Shah 389298b19252SAmit ShahThis option is maintained for backward compatibility. 389398b19252SAmit Shah 389498b19252SAmit ShahPlease use @code{-device virtconsole} for the new way of invocation. 38955824d651Sblueswir1ETEXI 38965824d651Sblueswir1 38975824d651Sblueswir1DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3898ad96090aSBlue Swirl "-show-cursor show cursor\n", QEMU_ARCH_ALL) 38995824d651Sblueswir1STEXI 390095d5f08bSStefan Weil@item -show-cursor 39016616b2adSStefan Weil@findex -show-cursor 390295d5f08bSStefan WeilShow cursor. 39035824d651Sblueswir1ETEXI 39045824d651Sblueswir1 39055824d651Sblueswir1DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3906ad96090aSBlue Swirl "-tb-size n set TB size\n", QEMU_ARCH_ALL) 39075824d651Sblueswir1STEXI 390895d5f08bSStefan Weil@item -tb-size @var{n} 39096616b2adSStefan Weil@findex -tb-size 391095d5f08bSStefan WeilSet TB size. 39115824d651Sblueswir1ETEXI 39125824d651Sblueswir1 39135824d651Sblueswir1DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 39147c601803SMichael Tokarev "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 39157c601803SMichael Tokarev "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 39167c601803SMichael Tokarev "-incoming unix:socketpath\n" \ 39177c601803SMichael Tokarev " prepare for incoming migration, listen on\n" \ 39187c601803SMichael Tokarev " specified protocol and socket address\n" \ 39197c601803SMichael Tokarev "-incoming fd:fd\n" \ 39207c601803SMichael Tokarev "-incoming exec:cmdline\n" \ 39217c601803SMichael Tokarev " accept incoming migration on given file descriptor\n" \ 39221597051bSDr. David Alan Gilbert " or from given external command\n" \ 39231597051bSDr. David Alan Gilbert "-incoming defer\n" \ 39241597051bSDr. David Alan Gilbert " wait for the URI to be specified via migrate_incoming\n", 3925ad96090aSBlue Swirl QEMU_ARCH_ALL) 39265824d651Sblueswir1STEXI 39277c601803SMichael Tokarev@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3928f9cfd655SMarkus Armbruster@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 39296616b2adSStefan Weil@findex -incoming 39307c601803SMichael TokarevPrepare for incoming migration, listen on a given tcp port. 39317c601803SMichael Tokarev 39327c601803SMichael Tokarev@item -incoming unix:@var{socketpath} 39337c601803SMichael TokarevPrepare for incoming migration, listen on a given unix socket. 39347c601803SMichael Tokarev 39357c601803SMichael Tokarev@item -incoming fd:@var{fd} 39367c601803SMichael TokarevAccept incoming migration from a given filedescriptor. 39377c601803SMichael Tokarev 39387c601803SMichael Tokarev@item -incoming exec:@var{cmdline} 39397c601803SMichael TokarevAccept incoming migration as an output from specified external command. 39401597051bSDr. David Alan Gilbert 39411597051bSDr. David Alan Gilbert@item -incoming defer 39421597051bSDr. David Alan GilbertWait for the URI to be specified via migrate_incoming. The monitor can 39431597051bSDr. David Alan Gilbertbe used to change settings (such as migration parameters) prior to issuing 39441597051bSDr. David Alan Gilbertthe migrate_incoming to allow the migration to begin. 39455824d651Sblueswir1ETEXI 39465824d651Sblueswir1 3947d15c05fcSAshijeet AcharyaDEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 3948d15c05fcSAshijeet Acharya "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 3949d15c05fcSAshijeet AcharyaSTEXI 3950d15c05fcSAshijeet Acharya@item -only-migratable 3951d15c05fcSAshijeet Acharya@findex -only-migratable 3952d15c05fcSAshijeet AcharyaOnly allow migratable devices. Devices will not be allowed to enter an 3953d15c05fcSAshijeet Acharyaunmigratable state. 3954d15c05fcSAshijeet AcharyaETEXI 3955d15c05fcSAshijeet Acharya 3956d8c208ddSGerd HoffmannDEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3957ad96090aSBlue Swirl "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3958d8c208ddSGerd HoffmannSTEXI 39593dbf2c7fSStefan Weil@item -nodefaults 39606616b2adSStefan Weil@findex -nodefaults 396166c19bf1SMichal NovotnyDon't create default devices. Normally, QEMU sets the default devices like serial 396266c19bf1SMichal Novotnyport, parallel port, virtual console, monitor device, VGA adapter, floppy and 396366c19bf1SMichal NovotnyCD-ROM drive and others. The @code{-nodefaults} option will disable all those 396466c19bf1SMichal Novotnydefault devices. 3965d8c208ddSGerd HoffmannETEXI 3966d8c208ddSGerd Hoffmann 39675824d651Sblueswir1#ifndef _WIN32 39685824d651Sblueswir1DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3969ad96090aSBlue Swirl "-chroot dir chroot to dir just before starting the VM\n", 3970ad96090aSBlue Swirl QEMU_ARCH_ALL) 39715824d651Sblueswir1#endif 39725824d651Sblueswir1STEXI 39734e257e5eSKevin Wolf@item -chroot @var{dir} 39746616b2adSStefan Weil@findex -chroot 39755824d651Sblueswir1Immediately before starting guest execution, chroot to the specified 39765824d651Sblueswir1directory. Especially useful in combination with -runas. 39775824d651Sblueswir1ETEXI 39785824d651Sblueswir1 39795824d651Sblueswir1#ifndef _WIN32 39805824d651Sblueswir1DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 3981ad96090aSBlue Swirl "-runas user change to user id user just before starting the VM\n", 3982ad96090aSBlue Swirl QEMU_ARCH_ALL) 39835824d651Sblueswir1#endif 39845824d651Sblueswir1STEXI 39854e257e5eSKevin Wolf@item -runas @var{user} 39866616b2adSStefan Weil@findex -runas 39875824d651Sblueswir1Immediately before starting guest execution, drop root privileges, switching 39885824d651Sblueswir1to the specified user. 39895824d651Sblueswir1ETEXI 39905824d651Sblueswir1 39915824d651Sblueswir1DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 39925824d651Sblueswir1 "-prom-env variable=value\n" 3993ad96090aSBlue Swirl " set OpenBIOS nvram variables\n", 3994ad96090aSBlue Swirl QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 399595d5f08bSStefan WeilSTEXI 399695d5f08bSStefan Weil@item -prom-env @var{variable}=@var{value} 39976616b2adSStefan Weil@findex -prom-env 399895d5f08bSStefan WeilSet OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 399995d5f08bSStefan WeilETEXI 40005824d651Sblueswir1DEF("semihosting", 0, QEMU_OPTION_semihosting, 4001f7bbcfb5SMichael Walle "-semihosting semihosting mode\n", 40023b3c1694SLeon Alrae QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 40033b3c1694SLeon Alrae QEMU_ARCH_MIPS) 400495d5f08bSStefan WeilSTEXI 400595d5f08bSStefan Weil@item -semihosting 40066616b2adSStefan Weil@findex -semihosting 40073b3c1694SLeon AlraeEnable semihosting mode (ARM, M68K, Xtensa, MIPS only). 4008a38bb079SLiviu IonescuETEXI 4009a38bb079SLiviu IonescuDEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 4010a59d31a1SLeon Alrae "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 4011a59d31a1SLeon Alrae " semihosting configuration\n", 40123b3c1694SLeon AlraeQEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 40133b3c1694SLeon AlraeQEMU_ARCH_MIPS) 4014a38bb079SLiviu IonescuSTEXI 4015a59d31a1SLeon Alrae@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 4016a38bb079SLiviu Ionescu@findex -semihosting-config 40173b3c1694SLeon AlraeEnable and configure semihosting (ARM, M68K, Xtensa, MIPS only). 4018a59d31a1SLeon Alrae@table @option 4019a59d31a1SLeon Alrae@item target=@code{native|gdb|auto} 4020a59d31a1SLeon AlraeDefines where the semihosting calls will be addressed, to QEMU (@code{native}) 4021a59d31a1SLeon Alraeor to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 4022a59d31a1SLeon Alraeduring debug sessions and @code{native} otherwise. 4023a59d31a1SLeon Alrae@item arg=@var{str1},arg=@var{str2},... 4024a59d31a1SLeon AlraeAllows the user to pass input arguments, and can be used multiple times to build 4025a59d31a1SLeon Alraeup a list. The old-style @code{-kernel}/@code{-append} method of passing a 4026a59d31a1SLeon Alraecommand line is still supported for backward compatibility. If both the 4027a59d31a1SLeon Alrae@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 4028a59d31a1SLeon Alraespecified, the former is passed to semihosting as it always takes precedence. 4029a59d31a1SLeon Alrae@end table 403095d5f08bSStefan WeilETEXI 40315824d651Sblueswir1DEF("old-param", 0, QEMU_OPTION_old_param, 4032ad96090aSBlue Swirl "-old-param old param mode\n", QEMU_ARCH_ARM) 403395d5f08bSStefan WeilSTEXI 403495d5f08bSStefan Weil@item -old-param 40356616b2adSStefan Weil@findex -old-param (ARM) 403695d5f08bSStefan WeilOld param mode (ARM only). 403795d5f08bSStefan WeilETEXI 403895d5f08bSStefan Weil 40397d76ad4fSEduardo OtuboDEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 404073a1e647SEduardo Otubo "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 404124f8cdc5SEduardo Otubo " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 40422b716fa6SEduardo Otubo " Enable seccomp mode 2 system call filter (default 'off').\n" \ 40432b716fa6SEduardo Otubo " use 'obsolete' to allow obsolete system calls that are provided\n" \ 40442b716fa6SEduardo Otubo " by the kernel, but typically no longer used by modern\n" \ 404573a1e647SEduardo Otubo " C library implementations.\n" \ 404673a1e647SEduardo Otubo " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 404773a1e647SEduardo Otubo " its privileges by blacklisting all set*uid|gid system calls.\n" \ 404873a1e647SEduardo Otubo " The value 'children' will deny set*uid|gid system calls for\n" \ 4049995a226fSEduardo Otubo " main QEMU process but will allow forks and execves to run unprivileged\n" \ 4050995a226fSEduardo Otubo " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 405124f8cdc5SEduardo Otubo " blacklisting *fork and execve\n" \ 405224f8cdc5SEduardo Otubo " use 'resourcecontrol' to disable process affinity and schedular priority\n", 40537d76ad4fSEduardo Otubo QEMU_ARCH_ALL) 40547d76ad4fSEduardo OtuboSTEXI 405524f8cdc5SEduardo Otubo@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 40567d76ad4fSEduardo Otubo@findex -sandbox 40577d76ad4fSEduardo OtuboEnable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 40587d76ad4fSEduardo Otubodisable it. The default is 'off'. 40592b716fa6SEduardo Otubo@table @option 40602b716fa6SEduardo Otubo@item obsolete=@var{string} 40612b716fa6SEduardo OtuboEnable Obsolete system calls 406273a1e647SEduardo Otubo@item elevateprivileges=@var{string} 406373a1e647SEduardo OtuboDisable set*uid|gid system calls 4064995a226fSEduardo Otubo@item spawn=@var{string} 4065995a226fSEduardo OtuboDisable *fork and execve 406624f8cdc5SEduardo Otubo@item resourcecontrol=@var{string} 406724f8cdc5SEduardo OtuboDisable process affinity and schedular priority 40682b716fa6SEduardo Otubo@end table 40697d76ad4fSEduardo OtuboETEXI 40707d76ad4fSEduardo Otubo 4071715a664aSGerd HoffmannDEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 4072ad96090aSBlue Swirl "-readconfig <file>\n", QEMU_ARCH_ALL) 40733dbf2c7fSStefan WeilSTEXI 40743dbf2c7fSStefan Weil@item -readconfig @var{file} 40756616b2adSStefan Weil@findex -readconfig 4076ed24cfacSMichal NovotnyRead device configuration from @var{file}. This approach is useful when you want to spawn 4077ed24cfacSMichal NovotnyQEMU process with many command line options but you don't want to exceed the command line 4078ed24cfacSMichal Novotnycharacter limit. 40793dbf2c7fSStefan WeilETEXI 4080715a664aSGerd HoffmannDEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 4081715a664aSGerd Hoffmann "-writeconfig <file>\n" 4082ad96090aSBlue Swirl " read/write config file\n", QEMU_ARCH_ALL) 40833dbf2c7fSStefan WeilSTEXI 40843dbf2c7fSStefan Weil@item -writeconfig @var{file} 40856616b2adSStefan Weil@findex -writeconfig 4086ed24cfacSMichal NovotnyWrite device configuration to @var{file}. The @var{file} can be either filename to save 4087ed24cfacSMichal Novotnycommand line and device configuration into file or dash @code{-}) character to print the 4088ed24cfacSMichal Novotnyoutput to stdout. This can be later used as input file for @code{-readconfig} option. 40893dbf2c7fSStefan WeilETEXI 40903478eae9SEduardo HabkostHXCOMM Deprecated, same as -no-user-config 40913478eae9SEduardo HabkostDEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, "", QEMU_ARCH_ALL) 4092f29a5614SEduardo HabkostDEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 4093f29a5614SEduardo Habkost "-no-user-config\n" 40943478eae9SEduardo Habkost " do not load default user-provided config files at startup\n", 4095f29a5614SEduardo Habkost QEMU_ARCH_ALL) 4096f29a5614SEduardo HabkostSTEXI 4097f29a5614SEduardo Habkost@item -no-user-config 4098f29a5614SEduardo Habkost@findex -no-user-config 4099f29a5614SEduardo HabkostThe @code{-no-user-config} option makes QEMU not load any of the user-provided 41003478eae9SEduardo Habkostconfig files on @var{sysconfdir}. 4101292444cbSAnthony LiguoriETEXI 4102ab6540d5SPrerna SaxenaDEF("trace", HAS_ARG, QEMU_OPTION_trace, 410310578a25SPaolo Bonzini "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 410423d15e86SLluís " specify tracing options\n", 4105ab6540d5SPrerna Saxena QEMU_ARCH_ALL) 4106ab6540d5SPrerna SaxenaSTEXI 410723d15e86SLluísHXCOMM This line is not accurate, as some sub-options are backend-specific but 410823d15e86SLluísHXCOMM HX does not support conditional compilation of text. 4109e370ad99SDenis V. Lunev@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 4110ab6540d5SPrerna Saxena@findex -trace 4111eeb2b8f7SDenis V. Lunev@include qemu-option-trace.texi 4112ab6540d5SPrerna SaxenaETEXI 41133dbf2c7fSStefan Weil 411431e70d6cSMarkus ArmbrusterHXCOMM Internal use 411531e70d6cSMarkus ArmbrusterDEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 411631e70d6cSMarkus ArmbrusterDEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 4117c7f0f3b1SAnthony Liguori 41180f66998fSPaul Moore#ifdef __linux__ 41190f66998fSPaul MooreDEF("enable-fips", 0, QEMU_OPTION_enablefips, 41200f66998fSPaul Moore "-enable-fips enable FIPS 140-2 compliance\n", 41210f66998fSPaul Moore QEMU_ARCH_ALL) 41220f66998fSPaul Moore#endif 41230f66998fSPaul MooreSTEXI 41240f66998fSPaul Moore@item -enable-fips 41250f66998fSPaul Moore@findex -enable-fips 41260f66998fSPaul MooreEnable FIPS 140-2 compliance mode. 41270f66998fSPaul MooreETEXI 41280f66998fSPaul Moore 4129a0dac021SJan KiszkaHXCOMM Deprecated by -machine accel=tcg property 4130c6e88b3bSBruce RogersDEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 4131a0dac021SJan Kiszka 4132c21fb4f8SJan KiszkaHXCOMM Deprecated by kvm-pit driver properties 4133c6e88b3bSBruce RogersDEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 4134c21fb4f8SJan Kiszka "", QEMU_ARCH_I386) 4135c21fb4f8SJan Kiszka 41364086bde8SJan KiszkaHXCOMM Deprecated (ignored) 4137c6e88b3bSBruce RogersDEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 41384086bde8SJan Kiszka 4139e43d594eSJan KiszkaHXCOMM Deprecated by -machine kernel_irqchip=on|off property 4140c6e88b3bSBruce RogersDEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 4141e43d594eSJan Kiszka 414288eed34aSJan KiszkaHXCOMM Deprecated (ignored) 414388eed34aSJan KiszkaDEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 414488eed34aSJan Kiszka 41455e2ac519SSeiji AguchiDEF("msg", HAS_ARG, QEMU_OPTION_msg, 41465e2ac519SSeiji Aguchi "-msg timestamp[=on|off]\n" 41475e2ac519SSeiji Aguchi " change the format of messages\n" 41485e2ac519SSeiji Aguchi " on|off controls leading timestamps (default:on)\n", 41495e2ac519SSeiji Aguchi QEMU_ARCH_ALL) 41505e2ac519SSeiji AguchiSTEXI 41515e2ac519SSeiji Aguchi@item -msg timestamp[=on|off] 41525e2ac519SSeiji Aguchi@findex -msg 41535e2ac519SSeiji Aguchiprepend a timestamp to each log message.(default:on) 41545e2ac519SSeiji AguchiETEXI 41555e2ac519SSeiji Aguchi 4156abfd9ce3SAmit ShahDEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 4157abfd9ce3SAmit Shah "-dump-vmstate <file>\n" 4158abfd9ce3SAmit Shah " Output vmstate information in JSON format to file.\n" 4159abfd9ce3SAmit Shah " Use the scripts/vmstate-static-checker.py file to\n" 4160abfd9ce3SAmit Shah " check for possible regressions in migration code\n" 41612382053fSLaurent Vivier " by comparing two such vmstate dumps.\n", 4162abfd9ce3SAmit Shah QEMU_ARCH_ALL) 4163abfd9ce3SAmit ShahSTEXI 4164abfd9ce3SAmit Shah@item -dump-vmstate @var{file} 4165abfd9ce3SAmit Shah@findex -dump-vmstate 4166abfd9ce3SAmit ShahDump json-encoded vmstate information for current machine type to file 4167abfd9ce3SAmit Shahin @var{file} 4168abfd9ce3SAmit ShahETEXI 4169abfd9ce3SAmit Shah 417043f187a5SPaolo BonziniSTEXI 417143f187a5SPaolo Bonzini@end table 417243f187a5SPaolo BonziniETEXI 417343f187a5SPaolo BonziniDEFHEADING() 4174b9174d4fSDaniel P. BerrangeDEFHEADING(Generic object creation) 417543f187a5SPaolo BonziniSTEXI 417643f187a5SPaolo Bonzini@table @option 417743f187a5SPaolo BonziniETEXI 4178b9174d4fSDaniel P. Berrange 4179b9174d4fSDaniel P. BerrangeDEF("object", HAS_ARG, QEMU_OPTION_object, 4180b9174d4fSDaniel P. Berrange "-object TYPENAME[,PROP1=VALUE1,...]\n" 4181b9174d4fSDaniel P. Berrange " create a new object of type TYPENAME setting properties\n" 4182b9174d4fSDaniel P. Berrange " in the order they are specified. Note that the 'id'\n" 4183b9174d4fSDaniel P. Berrange " property must be set. These objects are placed in the\n" 4184b9174d4fSDaniel P. Berrange " '/objects' path.\n", 4185b9174d4fSDaniel P. Berrange QEMU_ARCH_ALL) 4186b9174d4fSDaniel P. BerrangeSTEXI 4187b9174d4fSDaniel P. Berrange@item -object @var{typename}[,@var{prop1}=@var{value1},...] 4188b9174d4fSDaniel P. Berrange@findex -object 4189b9174d4fSDaniel P. BerrangeCreate a new object of type @var{typename} setting properties 4190b9174d4fSDaniel P. Berrangein the order they are specified. Note that the 'id' 4191b9174d4fSDaniel P. Berrangeproperty must be set. These objects are placed in the 4192b9174d4fSDaniel P. Berrange'/objects' path. 4193b9174d4fSDaniel P. Berrange 4194b9174d4fSDaniel P. Berrange@table @option 4195b9174d4fSDaniel P. Berrange 419611ae6ed8SEduardo Habkost@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off} 4197b9174d4fSDaniel P. Berrange 4198b9174d4fSDaniel P. BerrangeCreates a memory file backend object, which can be used to back 4199b9174d4fSDaniel P. Berrangethe guest RAM with huge pages. The @option{id} parameter is a 4200b9174d4fSDaniel P. Berrangeunique ID that will be used to reference this memory region 4201b9174d4fSDaniel P. Berrangewhen configuring the @option{-numa} argument. The @option{size} 4202b9174d4fSDaniel P. Berrangeoption provides the size of the memory region, and accepts 4203b9174d4fSDaniel P. Berrangecommon suffixes, eg @option{500M}. The @option{mem-path} provides 4204b9174d4fSDaniel P. Berrangethe path to either a shared memory or huge page filesystem mount. 4205b9174d4fSDaniel P. BerrangeThe @option{share} boolean option determines whether the memory 4206b9174d4fSDaniel P. Berrangeregion is marked as private to QEMU, or shared. The latter allows 4207b9174d4fSDaniel P. Berrangea co-operating external process to access the QEMU memory region. 420811ae6ed8SEduardo HabkostSetting the @option{discard-data} boolean option to @var{on} 420911ae6ed8SEduardo Habkostindicates that file contents can be destroyed when QEMU exits, 421011ae6ed8SEduardo Habkostto avoid unnecessarily flushing data to the backing file. Note 421111ae6ed8SEduardo Habkostthat @option{discard-data} is only an optimization, and QEMU 421211ae6ed8SEduardo Habkostmight not discard file contents if it aborts unexpectedly or is 421311ae6ed8SEduardo Habkostterminated using SIGKILL. 4214b9174d4fSDaniel P. Berrange 4215b9174d4fSDaniel P. Berrange@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4216b9174d4fSDaniel P. Berrange 4217b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4218b9174d4fSDaniel P. Berrangea device on the host. The @option{id} parameter is a unique ID that 4219b9174d4fSDaniel P. Berrangewill be used to reference this entropy backend from the @option{virtio-rng} 4220b9174d4fSDaniel P. Berrangedevice. The @option{filename} parameter specifies which file to obtain 4221b9174d4fSDaniel P. Berrangeentropy from and if omitted defaults to @option{/dev/random}. 4222b9174d4fSDaniel P. Berrange 4223b9174d4fSDaniel P. Berrange@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4224b9174d4fSDaniel P. Berrange 4225b9174d4fSDaniel P. BerrangeCreates a random number generator backend which obtains entropy from 4226b9174d4fSDaniel P. Berrangean external daemon running on the host. The @option{id} parameter is 4227b9174d4fSDaniel P. Berrangea unique ID that will be used to reference this entropy backend from 4228b9174d4fSDaniel P. Berrangethe @option{virtio-rng} device. The @option{chardev} parameter is 4229b9174d4fSDaniel P. Berrangethe unique ID of a character device backend that provides the connection 4230b9174d4fSDaniel P. Berrangeto the RNG daemon. 4231b9174d4fSDaniel P. Berrange 4232e00adf6cSDaniel P. Berrange@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4233e00adf6cSDaniel P. Berrange 4234e00adf6cSDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 4235e00adf6cSDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 4236e00adf6cSDaniel P. BerrangeID which network backends will use to access the credentials. The 4237e00adf6cSDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 4238e00adf6cSDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 4239e00adf6cSDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 4240e00adf6cSDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 4241e00adf6cSDaniel P. Berrangewill be verified, though this is a no-op for anonymous credentials. 4242e00adf6cSDaniel P. Berrange 4243e00adf6cSDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 4244e00adf6cSDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 4245e00adf6cSDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 4246e00adf6cSDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 4247e00adf6cSDaniel P. Berrangea set of DH parameters at startup. This is a computationally 4248e00adf6cSDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 4249e00adf6cSDaniel P. Berrangerecommended that a persistent set of parameters be generated 4250e00adf6cSDaniel P. Berrangeupfront and saved. 4251e00adf6cSDaniel P. Berrange 42521d7b5b4aSDaniel P. Berrange@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off},passwordid=@var{id} 425385bcbc78SDaniel P. Berrange 425485bcbc78SDaniel P. BerrangeCreates a TLS anonymous credentials object, which can be used to provide 425585bcbc78SDaniel P. BerrangeTLS support on network backends. The @option{id} parameter is a unique 425685bcbc78SDaniel P. BerrangeID which network backends will use to access the credentials. The 425785bcbc78SDaniel P. Berrange@option{endpoint} is either @option{server} or @option{client} depending 425885bcbc78SDaniel P. Berrangeon whether the QEMU network backend that uses the credentials will be 425985bcbc78SDaniel P. Berrangeacting as a client or as a server. If @option{verify-peer} is enabled 426085bcbc78SDaniel P. Berrange(the default) then once the handshake is completed, the peer credentials 426185bcbc78SDaniel P. Berrangewill be verified. With x509 certificates, this implies that the clients 426285bcbc78SDaniel P. Berrangemust be provided with valid client certificates too. 426385bcbc78SDaniel P. Berrange 426485bcbc78SDaniel P. BerrangeThe @var{dir} parameter tells QEMU where to find the credential 426585bcbc78SDaniel P. Berrangefiles. For server endpoints, this directory may contain a file 426685bcbc78SDaniel P. Berrange@var{dh-params.pem} providing diffie-hellman parameters to use 426785bcbc78SDaniel P. Berrangefor the TLS server. If the file is missing, QEMU will generate 426885bcbc78SDaniel P. Berrangea set of DH parameters at startup. This is a computationally 426985bcbc78SDaniel P. Berrangeexpensive operation that consumes random pool entropy, so it is 427085bcbc78SDaniel P. Berrangerecommended that a persistent set of parameters be generated 427185bcbc78SDaniel P. Berrangeupfront and saved. 427285bcbc78SDaniel P. Berrange 427385bcbc78SDaniel P. BerrangeFor x509 certificate credentials the directory will contain further files 427485bcbc78SDaniel P. Berrangeproviding the x509 certificates. The certificates must be stored 427585bcbc78SDaniel P. Berrangein PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 427685bcbc78SDaniel P. Berrange@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 427785bcbc78SDaniel P. Berrange@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 427885bcbc78SDaniel P. Berrange 42791d7b5b4aSDaniel P. BerrangeFor the @var{server-key.pem} and @var{client-key.pem} files which 42801d7b5b4aSDaniel P. Berrangecontain sensitive private keys, it is possible to use an encrypted 42811d7b5b4aSDaniel P. Berrangeversion by providing the @var{passwordid} parameter. This provides 42821d7b5b4aSDaniel P. Berrangethe ID of a previously created @code{secret} object containing the 42831d7b5b4aSDaniel P. Berrangepassword for decryption. 42841d7b5b4aSDaniel P. Berrange 4285338d3f41Szhanghailiang@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 42867dbb11c8SYang Hongyang 42877dbb11c8SYang HongyangInterval @var{t} can't be 0, this filter batches the packet delivery: all 42887dbb11c8SYang Hongyangpackets arriving in a given interval on netdev @var{netdevid} are delayed 42897dbb11c8SYang Hongyanguntil the end of the interval. Interval is in microseconds. 4290338d3f41Szhanghailiang@option{status} is optional that indicate whether the netfilter is 4291338d3f41Szhanghailiangon (enabled) or off (disabled), the default status for netfilter will be 'on'. 42927dbb11c8SYang Hongyang 42937dbb11c8SYang Hongyangqueue @var{all|rx|tx} is an option that can be applied to any netfilter. 42947dbb11c8SYang Hongyang 42957dbb11c8SYang Hongyang@option{all}: the filter is attached both to the receive and the transmit 42967dbb11c8SYang Hongyang queue of the netdev (default). 42977dbb11c8SYang Hongyang 42987dbb11c8SYang Hongyang@option{rx}: the filter is attached to the receive queue of the netdev, 42997dbb11c8SYang Hongyang where it will receive packets sent to the netdev. 43007dbb11c8SYang Hongyang 43017dbb11c8SYang Hongyang@option{tx}: the filter is attached to the transmit queue of the netdev, 43027dbb11c8SYang Hongyang where it will receive packets sent by the netdev. 43037dbb11c8SYang Hongyang 4304e2521f0eSZhang Chen@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4305f6d3afb5SZhang Chen 4306e2521f0eSZhang 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. 4307f6d3afb5SZhang Chen 430800d5c240SZhang 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] 4309d46f75b2SZhang Chen 4310d46f75b2SZhang Chenfilter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 431100d5c240SZhang Chen@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 431200d5c240SZhang Chenfilter-redirector will redirect packet with vnet_hdr_len. 4313d46f75b2SZhang ChenCreate a filter-redirector we need to differ outdev id from indev id, id can not 4314d46f75b2SZhang Chenbe the same. we can just use indev or outdev, but at least one of indev or outdev 4315d46f75b2SZhang Chenneed to be specified. 4316d46f75b2SZhang Chen 43174b39bdceSZhang Chen@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4318e6eee8abSZhang Chen 4319e6eee8abSZhang ChenFilter-rewriter is a part of COLO project.It will rewrite tcp packet to 4320e6eee8abSZhang Chensecondary from primary to keep secondary tcp connection,and rewrite 4321e6eee8abSZhang Chentcp packet to primary from secondary make tcp packet can be handled by 43224b39bdceSZhang Chenclient.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4323e6eee8abSZhang Chen 4324e6eee8abSZhang Chenusage: 4325e6eee8abSZhang Chencolo secondary: 4326e6eee8abSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4327e6eee8abSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4328e6eee8abSZhang Chen-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4329e6eee8abSZhang Chen 4330c551cd52SChanglong Xie@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4331d3e0c032SThomas Huth 4332d3e0c032SThomas HuthDump the network traffic on netdev @var{dev} to the file specified by 4333d3e0c032SThomas Huth@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4334d3e0c032SThomas HuthThe file format is libpcap, so it can be analyzed with tools such as tcpdump 4335d3e0c032SThomas Huthor Wireshark. 4336d3e0c032SThomas Huth 4337aa3a7032SZhang Chen@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid}[,vnet_hdr_support] 43387dce4e6fSZhang Chen 43397dce4e6fSZhang ChenColo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 43407dce4e6fSZhang Chensecondary packet. If the packets are same, we will output primary 43417dce4e6fSZhang Chenpacket to outdev@var{chardevid}, else we will notify colo-frame 43427dce4e6fSZhang Chendo checkpoint and send primary packet to outdev@var{chardevid}. 4343aa3a7032SZhang Chenif it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len. 43447dce4e6fSZhang Chen 43457dce4e6fSZhang Chenwe must use it with the help of filter-mirror and filter-redirector. 43467dce4e6fSZhang Chen 43477dce4e6fSZhang Chen@example 43487dce4e6fSZhang Chen 43497dce4e6fSZhang Chenprimary: 43507dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 43517dce4e6fSZhang Chen-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 43527dce4e6fSZhang Chen-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 43537dce4e6fSZhang Chen-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 43547dce4e6fSZhang Chen-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 43557dce4e6fSZhang Chen-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 43567dce4e6fSZhang Chen-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 43577dce4e6fSZhang Chen-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 43587dce4e6fSZhang Chen-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 43597dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 43607dce4e6fSZhang Chen-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 43617dce4e6fSZhang Chen-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0 43627dce4e6fSZhang Chen 43637dce4e6fSZhang Chensecondary: 43647dce4e6fSZhang Chen-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 43657dce4e6fSZhang Chen-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 43667dce4e6fSZhang Chen-chardev socket,id=red0,host=3.3.3.3,port=9003 43677dce4e6fSZhang Chen-chardev socket,id=red1,host=3.3.3.3,port=9004 43687dce4e6fSZhang Chen-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 43697dce4e6fSZhang Chen-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 43707dce4e6fSZhang Chen 43717dce4e6fSZhang Chen@end example 43727dce4e6fSZhang Chen 43737dce4e6fSZhang ChenIf you want to know the detail of above command line, you can read 43747dce4e6fSZhang Chenthe colo-compare git log. 43757dce4e6fSZhang Chen 43761653a5f3SGonglei@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 43771653a5f3SGonglei 43781653a5f3SGongleiCreates a cryptodev backend which executes crypto opreation from 43791653a5f3SGongleithe QEMU cipher APIS. The @var{id} parameter is 43801653a5f3SGongleia unique ID that will be used to reference this cryptodev backend from 43811653a5f3SGongleithe @option{virtio-crypto} device. The @var{queues} parameter is optional, 43821653a5f3SGongleiwhich specify the queue number of cryptodev backend, the default of 43831653a5f3SGonglei@var{queues} is 1. 43841653a5f3SGonglei 43851653a5f3SGonglei@example 43861653a5f3SGonglei 43871653a5f3SGonglei # qemu-system-x86_64 \ 43881653a5f3SGonglei [...] \ 43891653a5f3SGonglei -object cryptodev-backend-builtin,id=cryptodev0 \ 43901653a5f3SGonglei -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 43911653a5f3SGonglei [...] 43921653a5f3SGonglei@end example 43931653a5f3SGonglei 4394ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4395ac1d8878SDaniel P. Berrange@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4396ac1d8878SDaniel P. Berrange 4397ac1d8878SDaniel P. BerrangeDefines a secret to store a password, encryption key, or some other sensitive 4398ac1d8878SDaniel P. Berrangedata. The sensitive data can either be passed directly via the @var{data} 4399ac1d8878SDaniel P. Berrangeparameter, or indirectly via the @var{file} parameter. Using the @var{data} 4400ac1d8878SDaniel P. Berrangeparameter is insecure unless the sensitive data is encrypted. 4401ac1d8878SDaniel P. Berrange 4402ac1d8878SDaniel P. BerrangeThe sensitive data can be provided in raw format (the default), or base64. 4403ac1d8878SDaniel P. BerrangeWhen encoded as JSON, the raw format only supports valid UTF-8 characters, 4404ac1d8878SDaniel P. Berrangeso base64 is recommended for sending binary data. QEMU will convert from 4405ac1d8878SDaniel P. Berrangewhich ever format is provided to the format it needs internally. eg, an 4406ac1d8878SDaniel P. BerrangeRBD password can be provided in raw format, even though it will be base64 4407ac1d8878SDaniel P. Berrangeencoded when passed onto the RBD sever. 4408ac1d8878SDaniel P. Berrange 4409ac1d8878SDaniel P. BerrangeFor added protection, it is possible to encrypt the data associated with 4410ac1d8878SDaniel P. Berrangea secret using the AES-256-CBC cipher. Use of encryption is indicated 4411ac1d8878SDaniel P. Berrangeby providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4412ac1d8878SDaniel P. Berrangeparameter provides the ID of a previously defined secret that contains 4413ac1d8878SDaniel P. Berrangethe AES-256 decryption key. This key should be 32-bytes long and be 4414ac1d8878SDaniel P. Berrangebase64 encoded. The @var{iv} parameter provides the random initialization 4415ac1d8878SDaniel P. Berrangevector used for encryption of this particular secret and should be a 441669c0b278SDaniel P. Berrangebase64 encrypted string of the 16-byte IV. 4417ac1d8878SDaniel P. Berrange 4418ac1d8878SDaniel P. BerrangeThe simplest (insecure) usage is to provide the secret inline 4419ac1d8878SDaniel P. Berrange 4420ac1d8878SDaniel P. Berrange@example 4421ac1d8878SDaniel P. Berrange 4422ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,data=letmein,format=raw 4423ac1d8878SDaniel P. Berrange 4424ac1d8878SDaniel P. Berrange@end example 4425ac1d8878SDaniel P. Berrange 4426ac1d8878SDaniel P. BerrangeThe simplest secure usage is to provide the secret via a file 4427ac1d8878SDaniel P. Berrange 4428b43671f8SEric Blake # printf "letmein" > mypasswd.txt 4429ac1d8878SDaniel P. Berrange # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 4430ac1d8878SDaniel P. Berrange 4431ac1d8878SDaniel P. BerrangeFor greater security, AES-256-CBC should be used. To illustrate usage, 4432ac1d8878SDaniel P. Berrangeconsider the openssl command line tool which can encrypt the data. Note 4433ac1d8878SDaniel P. Berrangethat when encrypting, the plaintext must be padded to the cipher block 4434ac1d8878SDaniel P. Berrangesize (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4435ac1d8878SDaniel P. Berrange 4436ac1d8878SDaniel P. BerrangeFirst a master key needs to be created in base64 encoding: 4437ac1d8878SDaniel P. Berrange 4438ac1d8878SDaniel P. Berrange@example 4439ac1d8878SDaniel P. Berrange # openssl rand -base64 32 > key.b64 4440ac1d8878SDaniel P. Berrange # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4441ac1d8878SDaniel P. Berrange@end example 4442ac1d8878SDaniel P. Berrange 4443ac1d8878SDaniel P. BerrangeEach secret to be encrypted needs to have a random initialization vector 4444ac1d8878SDaniel P. Berrangegenerated. These do not need to be kept secret 4445ac1d8878SDaniel P. Berrange 4446ac1d8878SDaniel P. Berrange@example 4447ac1d8878SDaniel P. Berrange # openssl rand -base64 16 > iv.b64 4448ac1d8878SDaniel P. Berrange # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4449ac1d8878SDaniel P. Berrange@end example 4450ac1d8878SDaniel P. Berrange 4451ac1d8878SDaniel P. BerrangeThe secret to be defined can now be encrypted, in this case we're 4452ac1d8878SDaniel P. Berrangetelling openssl to base64 encode the result, but it could be left 4453ac1d8878SDaniel P. Berrangeas raw bytes if desired. 4454ac1d8878SDaniel P. Berrange 4455ac1d8878SDaniel P. Berrange@example 4456b43671f8SEric Blake # SECRET=$(printf "letmein" | 4457ac1d8878SDaniel P. Berrange openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4458ac1d8878SDaniel P. Berrange@end example 4459ac1d8878SDaniel P. Berrange 4460ac1d8878SDaniel P. BerrangeWhen launching QEMU, create a master secret pointing to @code{key.b64} 4461ac1d8878SDaniel P. Berrangeand specify that to be used to decrypt the user password. Pass the 4462ac1d8878SDaniel P. Berrangecontents of @code{iv.b64} to the second secret 4463ac1d8878SDaniel P. Berrange 4464ac1d8878SDaniel P. Berrange@example 4465ac1d8878SDaniel P. Berrange # $QEMU \ 4466ac1d8878SDaniel P. Berrange -object secret,id=secmaster0,format=base64,file=key.b64 \ 4467ac1d8878SDaniel P. Berrange -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4468ac1d8878SDaniel P. Berrange data=$SECRET,iv=$(<iv.b64) 4469ac1d8878SDaniel P. Berrange@end example 4470ac1d8878SDaniel P. Berrange 4471b9174d4fSDaniel P. Berrange@end table 4472b9174d4fSDaniel P. Berrange 4473b9174d4fSDaniel P. BerrangeETEXI 4474b9174d4fSDaniel P. Berrange 4475b9174d4fSDaniel P. Berrange 44763dbf2c7fSStefan WeilHXCOMM This is the last statement. Insert new options before this line! 44773dbf2c7fSStefan WeilSTEXI 44783dbf2c7fSStefan Weil@end table 44793dbf2c7fSStefan WeilETEXI 4480