1HXCOMM Use DEFHEADING() to define headings in both help text and texi 2HXCOMM Text between STEXI and ETEXI are copied to texi version and 3HXCOMM discarded from C version 4HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to 5HXCOMM construct option structures, enums and help message for specified 6HXCOMM architectures. 7HXCOMM HXCOMM can be used for comments, discarded from both texi and C 8 9DEFHEADING(Standard options:) 10STEXI 11@table @option 12ETEXI 13 14DEF("help", 0, QEMU_OPTION_h, 15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL) 16STEXI 17@item -h 18@findex -h 19Display help and exit 20ETEXI 21SRST 22``-h`` 23 Display help and exit 24ERST 25 26DEF("version", 0, QEMU_OPTION_version, 27 "-version display version information and exit\n", QEMU_ARCH_ALL) 28STEXI 29@item -version 30@findex -version 31Display version information and exit 32ETEXI 33SRST 34``-version`` 35 Display version information and exit 36ERST 37 38DEF("machine", HAS_ARG, QEMU_OPTION_machine, \ 39 "-machine [type=]name[,prop[=value][,...]]\n" 40 " selects emulated machine ('-machine help' for list)\n" 41 " property accel=accel1[:accel2[:...]] selects accelerator\n" 42 " supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n" 43 " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 44 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 45 " mem-merge=on|off controls memory merge support (default: on)\n" 46 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 47 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 48 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n" 49 " nvdimm=on|off controls NVDIMM support (default=off)\n" 50 " enforce-config-section=on|off enforce configuration section migration (default=off)\n" 51 " memory-encryption=@var{} memory encryption object to use (default=none)\n" 52 " hmat=on|off controls ACPI HMAT support (default=off)\n", 53 QEMU_ARCH_ALL) 54STEXI 55@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 56@findex -machine 57Select the emulated machine by @var{name}. Use @code{-machine help} to list 58available machines. 59 60For architectures which aim to support live migration compatibility 61across releases, each release will introduce a new versioned machine 62type. For example, the 2.8.0 release introduced machine types 63``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 64 65To allow live migration of guests from QEMU version 2.8.0, to QEMU 66version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 67and ``pc-q35-2.8'' machines too. To allow users live migrating VMs 68to skip multiple intermediate releases when upgrading, new releases 69of QEMU will support machine types from many previous versions. 70 71Supported machine properties are: 72@table @option 73@item accel=@var{accels1}[:@var{accels2}[:...]] 74This is used to enable an accelerator. Depending on the target architecture, 75kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 76more than one accelerator specified, the next one is used if the previous one 77fails to initialize. 78@item vmport=on|off|auto 79Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the 80value based on accel. For accel=xen the default is off otherwise the default 81is on. 82@item dump-guest-core=on|off 83Include guest memory in a core dump. The default is on. 84@item mem-merge=on|off 85Enables or disables memory merge support. This feature, when supported by 86the host, de-duplicates identical memory pages among VMs instances 87(enabled by default). 88@item aes-key-wrap=on|off 89Enables or disables AES key wrapping support on s390-ccw hosts. This feature 90controls whether AES wrapping keys will be created to allow 91execution of AES cryptographic functions. The default is on. 92@item dea-key-wrap=on|off 93Enables or disables DEA key wrapping support on s390-ccw hosts. This feature 94controls whether DEA wrapping keys will be created to allow 95execution of DEA cryptographic functions. The default is on. 96@item nvdimm=on|off 97Enables or disables NVDIMM support. The default is off. 98@item enforce-config-section=on|off 99If @option{enforce-config-section} is set to @var{on}, force migration 100code to send configuration section even if the machine-type sets the 101@option{migration.send-configuration} property to @var{off}. 102NOTE: this parameter is deprecated. Please use @option{-global} 103@option{migration.send-configuration}=@var{on|off} instead. 104@item memory-encryption=@var{} 105Memory encryption object to use. The default is none. 106@item hmat=on|off 107Enables or disables ACPI Heterogeneous Memory Attribute Table (HMAT) support. 108The default is off. 109@end table 110ETEXI 111SRST 112``-machine [type=]name[,prop=value[,...]]`` 113 Select the emulated machine by name. Use ``-machine help`` to list 114 available machines. 115 116 For architectures which aim to support live migration compatibility 117 across releases, each release will introduce a new versioned machine 118 type. For example, the 2.8.0 release introduced machine types 119 "pc-i440fx-2.8" and "pc-q35-2.8" for the x86\_64/i686 architectures. 120 121 To allow live migration of guests from QEMU version 2.8.0, to QEMU 122 version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8" 123 and "pc-q35-2.8" machines too. To allow users live migrating VMs to 124 skip multiple intermediate releases when upgrading, new releases of 125 QEMU will support machine types from many previous versions. 126 127 Supported machine properties are: 128 129 ``accel=accels1[:accels2[:...]]`` 130 This is used to enable an accelerator. Depending on the target 131 architecture, kvm, xen, hax, hvf, whpx or tcg can be available. 132 By default, tcg is used. If there is more than one accelerator 133 specified, the next one is used if the previous one fails to 134 initialize. 135 136 ``vmport=on|off|auto`` 137 Enables emulation of VMWare IO port, for vmmouse etc. auto says 138 to select the value based on accel. For accel=xen the default is 139 off otherwise the default is on. 140 141 ``dump-guest-core=on|off`` 142 Include guest memory in a core dump. The default is on. 143 144 ``mem-merge=on|off`` 145 Enables or disables memory merge support. This feature, when 146 supported by the host, de-duplicates identical memory pages 147 among VMs instances (enabled by default). 148 149 ``aes-key-wrap=on|off`` 150 Enables or disables AES key wrapping support on s390-ccw hosts. 151 This feature controls whether AES wrapping keys will be created 152 to allow execution of AES cryptographic functions. The default 153 is on. 154 155 ``dea-key-wrap=on|off`` 156 Enables or disables DEA key wrapping support on s390-ccw hosts. 157 This feature controls whether DEA wrapping keys will be created 158 to allow execution of DEA cryptographic functions. The default 159 is on. 160 161 ``nvdimm=on|off`` 162 Enables or disables NVDIMM support. The default is off. 163 164 ``enforce-config-section=on|off`` 165 If ``enforce-config-section`` is set to on, force migration code 166 to send configuration section even if the machine-type sets the 167 ``migration.send-configuration`` property to off. NOTE: this 168 parameter is deprecated. Please use ``-global`` 169 ``migration.send-configuration``\ =on\|off instead. 170 171 ``memory-encryption=`` 172 Memory encryption object to use. The default is none. 173 174 ``hmat=on|off`` 175 Enables or disables ACPI Heterogeneous Memory Attribute Table 176 (HMAT) support. The default is off. 177ERST 178 179HXCOMM Deprecated by -machine 180DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 181 182DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 183 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 184STEXI 185@item -cpu @var{model} 186@findex -cpu 187Select CPU model (@code{-cpu help} for list and additional feature selection) 188ETEXI 189SRST 190``-cpu model`` 191 Select CPU model (``-cpu help`` for list and additional feature 192 selection) 193ERST 194 195DEF("accel", HAS_ARG, QEMU_OPTION_accel, 196 "-accel [accel=]accelerator[,prop[=value][,...]]\n" 197 " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n" 198 " igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n" 199 " kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n" 200 " kvm-shadow-mem=size of KVM shadow MMU in bytes\n" 201 " tb-size=n (TCG translation block cache size)\n" 202 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL) 203STEXI 204@item -accel @var{name}[,prop=@var{value}[,...]] 205@findex -accel 206This is used to enable an accelerator. Depending on the target architecture, 207kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 208more than one accelerator specified, the next one is used if the previous one 209fails to initialize. 210@table @option 211@item igd-passthru=on|off 212When Xen is in use, this option controls whether Intel integrated graphics 213devices can be passed through to the guest (default=off) 214@item kernel-irqchip=on|off|split 215Controls KVM in-kernel irqchip support. The default is full acceleration of the 216interrupt controllers. On x86, split irqchip reduces the kernel attack 217surface, at a performance cost for non-MSI interrupts. Disabling the in-kernel 218irqchip completely is not recommended except for debugging purposes. 219@item kvm-shadow-mem=size 220Defines the size of the KVM shadow MMU. 221@item tb-size=@var{n} 222Controls the size (in MiB) of the TCG translation block cache. 223@item thread=single|multi 224Controls number of TCG threads. When the TCG is multi-threaded there will be one 225thread per vCPU therefor taking advantage of additional host cores. The default 226is to enable multi-threading where both the back-end and front-ends support it and 227no incompatible TCG features have been enabled (e.g. icount/replay). 228@end table 229ETEXI 230SRST 231``-accel name[,prop=value[,...]]`` 232 This is used to enable an accelerator. Depending on the target 233 architecture, kvm, xen, hax, hvf, whpx or tcg can be available. By 234 default, tcg is used. If there is more than one accelerator 235 specified, the next one is used if the previous one fails to 236 initialize. 237 238 ``igd-passthru=on|off`` 239 When Xen is in use, this option controls whether Intel 240 integrated graphics devices can be passed through to the guest 241 (default=off) 242 243 ``kernel-irqchip=on|off|split`` 244 Controls KVM in-kernel irqchip support. The default is full 245 acceleration of the interrupt controllers. On x86, split irqchip 246 reduces the kernel attack surface, at a performance cost for 247 non-MSI interrupts. Disabling the in-kernel irqchip completely 248 is not recommended except for debugging purposes. 249 250 ``kvm-shadow-mem=size`` 251 Defines the size of the KVM shadow MMU. 252 253 ``tb-size=n`` 254 Controls the size (in MiB) of the TCG translation block cache. 255 256 ``thread=single|multi`` 257 Controls number of TCG threads. When the TCG is multi-threaded 258 there will be one thread per vCPU therefor taking advantage of 259 additional host cores. The default is to enable multi-threading 260 where both the back-end and front-ends support it and no 261 incompatible TCG features have been enabled (e.g. 262 icount/replay). 263ERST 264 265DEF("smp", HAS_ARG, QEMU_OPTION_smp, 266 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n" 267 " set the number of CPUs to 'n' [default=1]\n" 268 " maxcpus= maximum number of total cpus, including\n" 269 " offline CPUs for hotplug, etc\n" 270 " cores= number of CPU cores on one socket (for PC, it's on one die)\n" 271 " threads= number of threads on one CPU core\n" 272 " dies= number of CPU dies on one socket (for PC only)\n" 273 " sockets= number of discrete sockets in the system\n", 274 QEMU_ARCH_ALL) 275STEXI 276@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 277@findex -smp 278Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 279CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 280to 4. 281For the PC target, the number of @var{cores} per die, the number of @var{threads} 282per cores, the number of @var{dies} per packages and the total number of 283@var{sockets} can be specified. Missing values will be computed. 284If any on the three values is given, the total number of CPUs @var{n} can be omitted. 285@var{maxcpus} specifies the maximum number of hotpluggable CPUs. 286ETEXI 287SRST 288``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]`` 289 Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs 290 are supported. On Sparc32 target, Linux limits the number of usable 291 CPUs to 4. For the PC target, the number of cores per die, the 292 number of threads per cores, the number of dies per packages and the 293 total number of sockets can be specified. Missing values will be 294 computed. If any on the three values is given, the total number of 295 CPUs n can be omitted. maxcpus specifies the maximum number of 296 hotpluggable CPUs. 297ERST 298 299DEF("numa", HAS_ARG, QEMU_OPTION_numa, 300 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n" 301 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n" 302 "-numa dist,src=source,dst=destination,val=distance\n" 303 "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n" 304 "-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n" 305 "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n", 306 QEMU_ARCH_ALL) 307STEXI 308@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}] 309@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}] 310@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 311@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 312@itemx -numa hmat-lb,initiator=@var{node},target=@var{node},hierarchy=@var{hierarchy},data-type=@var{tpye}[,latency=@var{lat}][,bandwidth=@var{bw}] 313@itemx -numa hmat-cache,node-id=@var{node},size=@var{size},level=@var{level}[,associativity=@var{str}][,policy=@var{str}][,line=@var{size}] 314@findex -numa 315Define a NUMA node and assign RAM and VCPUs to it. 316Set the NUMA distance from a source node to a destination node. 317Set the ACPI Heterogeneous Memory Attributes for the given nodes. 318 319Legacy VCPU assignment uses @samp{cpus} option where 320@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 321@samp{cpus} option represent a contiguous range of CPU indexes 322(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 323set of VCPUs can be represented by providing multiple @samp{cpus} 324options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 325split between them. 326 327For example, the following option assigns VCPUs 0, 1, 2 and 5 to 328a NUMA node: 329@example 330-numa node,cpus=0-2,cpus=5 331@end example 332 333@samp{cpu} option is a new alternative to @samp{cpus} option 334which uses @samp{socket-id|core-id|thread-id} properties to assign 335CPU objects to a @var{node} using topology layout properties of CPU. 336The set of properties is machine specific, and depends on used 337machine type/@samp{smp} options. It could be queried with 338@samp{hotpluggable-cpus} monitor command. 339@samp{node-id} property specifies @var{node} to which CPU object 340will be assigned, it's required for @var{node} to be declared 341with @samp{node} option before it's used with @samp{cpu} option. 342 343For example: 344@example 345-M pc \ 346-smp 1,sockets=2,maxcpus=2 \ 347-numa node,nodeid=0 -numa node,nodeid=1 \ 348-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 349@end example 350 351@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 352assigns RAM from a given memory backend device to a node. If 353@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 354split equally between them. 355 356@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 357if one node uses @samp{memdev}, all of them have to use it. 358 359@samp{initiator} is an additional option that points to an @var{initiator} 360NUMA node that has best performance (the lowest latency or largest bandwidth) 361to this NUMA @var{node}. Note that this option can be set only when 362the machine property 'hmat' is set to 'on'. 363 364Following example creates a machine with 2 NUMA nodes, node 0 has CPU. 365node 1 has only memory, and its initiator is node 0. Note that because 366node 0 has CPU, by default the initiator of node 0 is itself and must be 367itself. 368@example 369-machine hmat=on \ 370-m 2G,slots=2,maxmem=4G \ 371-object memory-backend-ram,size=1G,id=m0 \ 372-object memory-backend-ram,size=1G,id=m1 \ 373-numa node,nodeid=0,memdev=m0 \ 374-numa node,nodeid=1,memdev=m1,initiator=0 \ 375-smp 2,sockets=2,maxcpus=2 \ 376-numa cpu,node-id=0,socket-id=0 \ 377-numa cpu,node-id=0,socket-id=1 378@end example 379 380@var{source} and @var{destination} are NUMA node IDs. 381@var{distance} is the NUMA distance from @var{source} to @var{destination}. 382The distance from a node to itself is always 10. If any pair of nodes is 383given a distance, then all pairs must be given distances. Although, when 384distances are only given in one direction for each pair of nodes, then 385the distances in the opposite directions are assumed to be the same. If, 386however, an asymmetrical pair of distances is given for even one node 387pair, then all node pairs must be provided distance values for both 388directions, even when they are symmetrical. When a node is unreachable 389from another node, set the pair's distance to 255. 390 391Note that the -@option{numa} option doesn't allocate any of the 392specified resources, it just assigns existing resources to NUMA 393nodes. This means that one still has to use the @option{-m}, 394@option{-smp} options to allocate RAM and VCPUs respectively. 395 396Use @samp{hmat-lb} to set System Locality Latency and Bandwidth Information 397between initiator and target NUMA nodes in ACPI Heterogeneous Attribute Memory Table (HMAT). 398Initiator NUMA node can create memory requests, usually it has one or more processors. 399Target NUMA node contains addressable memory. 400 401In @samp{hmat-lb} option, @var{node} are NUMA node IDs. @var{hierarchy} is the memory 402hierarchy of the target NUMA node: if @var{hierarchy} is 'memory', the structure 403represents the memory performance; if @var{hierarchy} is 'first-level|second-level|third-level', 404this structure represents aggregated performance of memory side caches for each domain. 405@var{type} of 'data-type' is type of data represented by this structure instance: 406if 'hierarchy' is 'memory', 'data-type' is 'access|read|write' latency or 'access|read|write' 407bandwidth of the target memory; if 'hierarchy' is 'first-level|second-level|third-level', 408'data-type' is 'access|read|write' hit latency or 'access|read|write' hit bandwidth of the 409target memory side cache. 410 411@var{lat} is latency value in nanoseconds. @var{bw} is bandwidth value, 412the possible value and units are NUM[M|G|T], mean that the bandwidth value are 413NUM byte per second (or MB/s, GB/s or TB/s depending on used suffix). 414Note that if latency or bandwidth value is 0, means the corresponding latency or 415bandwidth information is not provided. 416 417In @samp{hmat-cache} option, @var{node-id} is the NUMA-id of the memory belongs. 418@var{size} is the size of memory side cache in bytes. @var{level} is the cache 419level described in this structure, note that the cache level 0 should not be used 420with @samp{hmat-cache} option. @var{associativity} is the cache associativity, 421the possible value is 'none/direct(direct-mapped)/complex(complex cache indexing)'. 422@var{policy} is the write policy. @var{line} is the cache Line size in bytes. 423 424For example, the following options describe 2 NUMA nodes. Node 0 has 2 cpus and 425a ram, node 1 has only a ram. The processors in node 0 access memory in node 4260 with access-latency 5 nanoseconds, access-bandwidth is 200 MB/s; 427The processors in NUMA node 0 access memory in NUMA node 1 with access-latency 10 428nanoseconds, access-bandwidth is 100 MB/s. 429And for memory side cache information, NUMA node 0 and 1 both have 1 level memory 430cache, size is 10KB, policy is write-back, the cache Line size is 8 bytes: 431@example 432-machine hmat=on \ 433-m 2G \ 434-object memory-backend-ram,size=1G,id=m0 \ 435-object memory-backend-ram,size=1G,id=m1 \ 436-smp 2 \ 437-numa node,nodeid=0,memdev=m0 \ 438-numa node,nodeid=1,memdev=m1,initiator=0 \ 439-numa cpu,node-id=0,socket-id=0 \ 440-numa cpu,node-id=0,socket-id=1 \ 441-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \ 442-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \ 443-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \ 444-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \ 445-numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \ 446-numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8 447@end example 448 449ETEXI 450SRST 451``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]`` 452 \ 453``-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]`` 454 \ 455``-numa dist,src=source,dst=destination,val=distance`` 456 \ 457``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]`` 458 \ 459``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]`` 460 \ 461``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]`` 462 Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA 463 distance from a source node to a destination node. Set the ACPI 464 Heterogeneous Memory Attributes for the given nodes. 465 466 Legacy VCPU assignment uses '\ ``cpus``\ ' option where firstcpu and 467 lastcpu are CPU indexes. Each '\ ``cpus``\ ' option represent a 468 contiguous range of CPU indexes (or a single VCPU if lastcpu is 469 omitted). A non-contiguous set of VCPUs can be represented by 470 providing multiple '\ ``cpus``\ ' options. If '\ ``cpus``\ ' is 471 omitted on all nodes, VCPUs are automatically split between them. 472 473 For example, the following option assigns VCPUs 0, 1, 2 and 5 to a 474 NUMA node: 475 476 :: 477 478 -numa node,cpus=0-2,cpus=5 479 480 '\ ``cpu``\ ' option is a new alternative to '\ ``cpus``\ ' option 481 which uses '\ ``socket-id|core-id|thread-id``\ ' properties to 482 assign CPU objects to a node using topology layout properties of 483 CPU. The set of properties is machine specific, and depends on used 484 machine type/'\ ``smp``\ ' options. It could be queried with 485 '\ ``hotpluggable-cpus``\ ' monitor command. '\ ``node-id``\ ' 486 property specifies node to which CPU object will be assigned, it's 487 required for node to be declared with '\ ``node``\ ' option before 488 it's used with '\ ``cpu``\ ' option. 489 490 For example: 491 492 :: 493 494 -M pc \ 495 -smp 1,sockets=2,maxcpus=2 \ 496 -numa node,nodeid=0 -numa node,nodeid=1 \ 497 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 498 499 '\ ``mem``\ ' assigns a given RAM amount to a node. '\ ``memdev``\ ' 500 assigns RAM from a given memory backend device to a node. If 501 '\ ``mem``\ ' and '\ ``memdev``\ ' are omitted in all nodes, RAM is 502 split equally between them. 503 504 '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive. 505 Furthermore, if one node uses '\ ``memdev``\ ', all of them have to 506 use it. 507 508 '\ ``initiator``\ ' is an additional option that points to an 509 initiator NUMA node that has best performance (the lowest latency or 510 largest bandwidth) to this NUMA node. Note that this option can be 511 set only when the machine property 'hmat' is set to 'on'. 512 513 Following example creates a machine with 2 NUMA nodes, node 0 has 514 CPU. node 1 has only memory, and its initiator is node 0. Note that 515 because node 0 has CPU, by default the initiator of node 0 is itself 516 and must be itself. 517 518 :: 519 520 -machine hmat=on \ 521 -m 2G,slots=2,maxmem=4G \ 522 -object memory-backend-ram,size=1G,id=m0 \ 523 -object memory-backend-ram,size=1G,id=m1 \ 524 -numa node,nodeid=0,memdev=m0 \ 525 -numa node,nodeid=1,memdev=m1,initiator=0 \ 526 -smp 2,sockets=2,maxcpus=2 \ 527 -numa cpu,node-id=0,socket-id=0 \ 528 -numa cpu,node-id=0,socket-id=1 529 530 source and destination are NUMA node IDs. distance is the NUMA 531 distance from source to destination. The distance from a node to 532 itself is always 10. If any pair of nodes is given a distance, then 533 all pairs must be given distances. Although, when distances are only 534 given in one direction for each pair of nodes, then the distances in 535 the opposite directions are assumed to be the same. If, however, an 536 asymmetrical pair of distances is given for even one node pair, then 537 all node pairs must be provided distance values for both directions, 538 even when they are symmetrical. When a node is unreachable from 539 another node, set the pair's distance to 255. 540 541 Note that the -``numa`` option doesn't allocate any of the specified 542 resources, it just assigns existing resources to NUMA nodes. This 543 means that one still has to use the ``-m``, ``-smp`` options to 544 allocate RAM and VCPUs respectively. 545 546 Use '\ ``hmat-lb``\ ' to set System Locality Latency and Bandwidth 547 Information between initiator and target NUMA nodes in ACPI 548 Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can 549 create memory requests, usually it has one or more processors. 550 Target NUMA node contains addressable memory. 551 552 In '\ ``hmat-lb``\ ' option, node are NUMA node IDs. hierarchy is 553 the memory hierarchy of the target NUMA node: if hierarchy is 554 'memory', the structure represents the memory performance; if 555 hierarchy is 'first-level\|second-level\|third-level', this 556 structure represents aggregated performance of memory side caches 557 for each domain. type of 'data-type' is type of data represented by 558 this structure instance: if 'hierarchy' is 'memory', 'data-type' is 559 'access\|read\|write' latency or 'access\|read\|write' bandwidth of 560 the target memory; if 'hierarchy' is 561 'first-level\|second-level\|third-level', 'data-type' is 562 'access\|read\|write' hit latency or 'access\|read\|write' hit 563 bandwidth of the target memory side cache. 564 565 lat is latency value in nanoseconds. bw is bandwidth value, the 566 possible value and units are NUM[M\|G\|T], mean that the bandwidth 567 value are NUM byte per second (or MB/s, GB/s or TB/s depending on 568 used suffix). Note that if latency or bandwidth value is 0, means 569 the corresponding latency or bandwidth information is not provided. 570 571 In '\ ``hmat-cache``\ ' option, node-id is the NUMA-id of the memory 572 belongs. size is the size of memory side cache in bytes. level is 573 the cache level described in this structure, note that the cache 574 level 0 should not be used with '\ ``hmat-cache``\ ' option. 575 associativity is the cache associativity, the possible value is 576 'none/direct(direct-mapped)/complex(complex cache indexing)'. policy 577 is the write policy. line is the cache Line size in bytes. 578 579 For example, the following options describe 2 NUMA nodes. Node 0 has 580 2 cpus and a ram, node 1 has only a ram. The processors in node 0 581 access memory in node 0 with access-latency 5 nanoseconds, 582 access-bandwidth is 200 MB/s; The processors in NUMA node 0 access 583 memory in NUMA node 1 with access-latency 10 nanoseconds, 584 access-bandwidth is 100 MB/s. And for memory side cache information, 585 NUMA node 0 and 1 both have 1 level memory cache, size is 10KB, 586 policy is write-back, the cache Line size is 8 bytes: 587 588 :: 589 590 -machine hmat=on \ 591 -m 2G \ 592 -object memory-backend-ram,size=1G,id=m0 \ 593 -object memory-backend-ram,size=1G,id=m1 \ 594 -smp 2 \ 595 -numa node,nodeid=0,memdev=m0 \ 596 -numa node,nodeid=1,memdev=m1,initiator=0 \ 597 -numa cpu,node-id=0,socket-id=0 \ 598 -numa cpu,node-id=0,socket-id=1 \ 599 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \ 600 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \ 601 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \ 602 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \ 603 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \ 604 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8 605ERST 606 607DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 608 "-add-fd fd=fd,set=set[,opaque=opaque]\n" 609 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 610STEXI 611@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 612@findex -add-fd 613 614Add a file descriptor to an fd set. Valid options are: 615 616@table @option 617@item fd=@var{fd} 618This option defines the file descriptor of which a duplicate is added to fd set. 619The file descriptor cannot be stdin, stdout, or stderr. 620@item set=@var{set} 621This option defines the ID of the fd set to add the file descriptor to. 622@item opaque=@var{opaque} 623This option defines a free-form string that can be used to describe @var{fd}. 624@end table 625 626You can open an image using pre-opened file descriptors from an fd set: 627@example 628@value{qemu_system} \ 629 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 630 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 631 -drive file=/dev/fdset/2,index=0,media=disk 632@end example 633ETEXI 634SRST 635``-add-fd fd=fd,set=set[,opaque=opaque]`` 636 Add a file descriptor to an fd set. Valid options are: 637 638 ``fd=fd`` 639 This option defines the file descriptor of which a duplicate is 640 added to fd set. The file descriptor cannot be stdin, stdout, or 641 stderr. 642 643 ``set=set`` 644 This option defines the ID of the fd set to add the file 645 descriptor to. 646 647 ``opaque=opaque`` 648 This option defines a free-form string that can be used to 649 describe fd. 650 651 You can open an image using pre-opened file descriptors from an fd 652 set: 653 654 .. parsed-literal:: 655 656 |qemu_system| \ 657 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 658 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 659 -drive file=/dev/fdset/2,index=0,media=disk 660ERST 661 662DEF("set", HAS_ARG, QEMU_OPTION_set, 663 "-set group.id.arg=value\n" 664 " set <arg> parameter for item <id> of type <group>\n" 665 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 666STEXI 667@item -set @var{group}.@var{id}.@var{arg}=@var{value} 668@findex -set 669Set parameter @var{arg} for item @var{id} of type @var{group} 670ETEXI 671SRST 672``-set group.id.arg=value`` 673 Set parameter arg for item id of type group 674ERST 675 676DEF("global", HAS_ARG, QEMU_OPTION_global, 677 "-global driver.property=value\n" 678 "-global driver=driver,property=property,value=value\n" 679 " set a global default for a driver property\n", 680 QEMU_ARCH_ALL) 681STEXI 682@item -global @var{driver}.@var{prop}=@var{value} 683@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 684@findex -global 685Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 686 687@example 688@value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img 689@end example 690 691In particular, you can use this to set driver properties for devices which are 692created automatically by the machine model. To create a device which is not 693created automatically and set properties on it, use -@option{device}. 694 695-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 696driver=@var{driver},property=@var{prop},value=@var{value}. The 697longhand syntax works even when @var{driver} contains a dot. 698ETEXI 699SRST 700``-global driver.prop=value`` 701 \ 702``-global driver=driver,property=property,value=value`` 703 Set default value of driver's property prop to value, e.g.: 704 705 .. parsed-literal:: 706 707 |qemu_system_x86| -global ide-hd.physical_block_size=4096 disk-image.img 708 709 In particular, you can use this to set driver properties for devices 710 which are created automatically by the machine model. To create a 711 device which is not created automatically and set properties on it, 712 use -``device``. 713 714 -global driver.prop=value is shorthand for -global 715 driver=driver,property=prop,value=value. The longhand syntax works 716 even when driver contains a dot. 717ERST 718 719DEF("boot", HAS_ARG, QEMU_OPTION_boot, 720 "-boot [order=drives][,once=drives][,menu=on|off]\n" 721 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 722 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 723 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 724 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 725 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 726 QEMU_ARCH_ALL) 727STEXI 728@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] 729@findex -boot 730Specify boot order @var{drives} as a string of drive letters. Valid 731drive letters depend on the target architecture. The x86 PC uses: a, b 732(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 733from network adapter 1-4), hard disk boot is the default. To apply a 734particular boot order only on the first startup, specify it via 735@option{once}. Note that the @option{order} or @option{once} parameter 736should not be used together with the @option{bootindex} property of 737devices, since the firmware implementations normally do not support both 738at the same time. 739 740Interactive boot menus/prompts can be enabled via @option{menu=on} as far 741as firmware/BIOS supports them. The default is non-interactive boot. 742 743A splash picture could be passed to bios, enabling user to show it as logo, 744when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 745supports them. Currently Seabios for X86 system support it. 746limitation: The splash file could be a jpeg file or a BMP file in 24 BPP 747format(true color). The resolution should be supported by the SVGA mode, so 748the recommended is 320x240, 640x480, 800x640. 749 750A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 751when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 752reboot, qemu passes '-1' to bios by default. Currently Seabios for X86 753system support it. 754 755Do strict boot via @option{strict=on} as far as firmware/BIOS 756supports it. This only effects when boot priority is changed by 757bootindex options. The default is non-strict boot. 758 759@example 760# try to boot from network first, then from hard disk 761@value{qemu_system_x86} -boot order=nc 762# boot from CD-ROM first, switch back to default order after reboot 763@value{qemu_system_x86} -boot once=d 764# boot with a splash picture for 5 seconds. 765@value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000 766@end example 767 768Note: The legacy format '-boot @var{drives}' is still supported but its 769use is discouraged as it may be removed from future versions. 770ETEXI 771SRST 772``-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]`` 773 Specify boot order drives as a string of drive letters. Valid drive 774 letters depend on the target architecture. The x86 PC uses: a, b 775 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p 776 (Etherboot from network adapter 1-4), hard disk boot is the default. 777 To apply a particular boot order only on the first startup, specify 778 it via ``once``. Note that the ``order`` or ``once`` parameter 779 should not be used together with the ``bootindex`` property of 780 devices, since the firmware implementations normally do not support 781 both at the same time. 782 783 Interactive boot menus/prompts can be enabled via ``menu=on`` as far 784 as firmware/BIOS supports them. The default is non-interactive boot. 785 786 A splash picture could be passed to bios, enabling user to show it 787 as logo, when option splash=sp\_name is given and menu=on, If 788 firmware/BIOS supports them. Currently Seabios for X86 system 789 support it. limitation: The splash file could be a jpeg file or a 790 BMP file in 24 BPP format(true color). The resolution should be 791 supported by the SVGA mode, so the recommended is 320x240, 640x480, 792 800x640. 793 794 A timeout could be passed to bios, guest will pause for rb\_timeout 795 ms when boot failed, then reboot. If rb\_timeout is '-1', guest will 796 not reboot, qemu passes '-1' to bios by default. Currently Seabios 797 for X86 system support it. 798 799 Do strict boot via ``strict=on`` as far as firmware/BIOS supports 800 it. This only effects when boot priority is changed by bootindex 801 options. The default is non-strict boot. 802 803 .. parsed-literal:: 804 805 # try to boot from network first, then from hard disk 806 |qemu_system_x86| -boot order=nc 807 # boot from CD-ROM first, switch back to default order after reboot 808 |qemu_system_x86| -boot once=d 809 # boot with a splash picture for 5 seconds. 810 |qemu_system_x86| -boot menu=on,splash=/root/boot.bmp,splash-time=5000 811 812 Note: The legacy format '-boot drives' is still supported but its 813 use is discouraged as it may be removed from future versions. 814ERST 815 816DEF("m", HAS_ARG, QEMU_OPTION_m, 817 "-m [size=]megs[,slots=n,maxmem=size]\n" 818 " configure guest RAM\n" 819 " size: initial amount of guest memory\n" 820 " slots: number of hotplug slots (default: none)\n" 821 " maxmem: maximum amount of guest memory (default: none)\n" 822 "NOTE: Some architectures might enforce a specific granularity\n", 823 QEMU_ARCH_ALL) 824STEXI 825@item -m [size=]@var{megs}[,slots=n,maxmem=size] 826@findex -m 827Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 828Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in 829megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 830could be used to set amount of hotpluggable memory slots and maximum amount of 831memory. Note that @var{maxmem} must be aligned to the page size. 832 833For example, the following command-line sets the guest startup RAM size to 8341GB, creates 3 slots to hotplug additional memory and sets the maximum 835memory the guest can reach to 4GB: 836 837@example 838@value{qemu_system} -m 1G,slots=3,maxmem=4G 839@end example 840 841If @var{slots} and @var{maxmem} are not specified, memory hotplug won't 842be enabled and the guest startup RAM will never increase. 843ETEXI 844SRST 845``-m [size=]megs[,slots=n,maxmem=size]`` 846 Sets guest startup RAM size to megs megabytes. Default is 128 MiB. 847 Optionally, a suffix of "M" or "G" can be used to signify a value in 848 megabytes or gigabytes respectively. Optional pair slots, maxmem 849 could be used to set amount of hotpluggable memory slots and maximum 850 amount of memory. Note that maxmem must be aligned to the page size. 851 852 For example, the following command-line sets the guest startup RAM 853 size to 1GB, creates 3 slots to hotplug additional memory and sets 854 the maximum memory the guest can reach to 4GB: 855 856 .. parsed-literal:: 857 858 |qemu_system| -m 1G,slots=3,maxmem=4G 859 860 If slots and maxmem are not specified, memory hotplug won't be 861 enabled and the guest startup RAM will never increase. 862ERST 863 864DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 865 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 866STEXI 867@item -mem-path @var{path} 868@findex -mem-path 869Allocate guest RAM from a temporarily created file in @var{path}. 870ETEXI 871SRST 872``-mem-path path`` 873 Allocate guest RAM from a temporarily created file in path. 874ERST 875 876DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 877 "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 878 QEMU_ARCH_ALL) 879STEXI 880@item -mem-prealloc 881@findex -mem-prealloc 882Preallocate memory when using -mem-path. 883ETEXI 884SRST 885``-mem-prealloc`` 886 Preallocate memory when using -mem-path. 887ERST 888 889DEF("k", HAS_ARG, QEMU_OPTION_k, 890 "-k language use keyboard layout (for example 'fr' for French)\n", 891 QEMU_ARCH_ALL) 892STEXI 893@item -k @var{language} 894@findex -k 895Use keyboard layout @var{language} (for example @code{fr} for 896French). This option is only needed where it is not easy to get raw PC 897keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 898display). You don't normally need to use it on PC/Linux or PC/Windows 899hosts. 900 901The available layouts are: 902@example 903ar de-ch es fo fr-ca hu ja mk no pt-br sv 904da en-gb et fr fr-ch is lt nl pl ru th 905de en-us fi fr-be hr it lv nl-be pt sl tr 906@end example 907 908The default is @code{en-us}. 909ETEXI 910SRST 911``-k language`` 912 Use keyboard layout language (for example ``fr`` for French). This 913 option is only needed where it is not easy to get raw PC keycodes 914 (e.g. on Macs, with some X11 servers or with a VNC or curses 915 display). You don't normally need to use it on PC/Linux or 916 PC/Windows hosts. 917 918 The available layouts are: 919 920 :: 921 922 ar de-ch es fo fr-ca hu ja mk no pt-br sv 923 da en-gb et fr fr-ch is lt nl pl ru th 924 de en-us fi fr-be hr it lv nl-be pt sl tr 925 926 The default is ``en-us``. 927ERST 928 929 930HXCOMM Deprecated by -audiodev 931DEF("audio-help", 0, QEMU_OPTION_audio_help, 932 "-audio-help show -audiodev equivalent of the currently specified audio settings\n", 933 QEMU_ARCH_ALL) 934STEXI 935@item -audio-help 936@findex -audio-help 937Will show the -audiodev equivalent of the currently specified 938(deprecated) environment variables. 939ETEXI 940SRST 941``-audio-help`` 942 Will show the -audiodev equivalent of the currently specified 943 (deprecated) environment variables. 944ERST 945 946DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev, 947 "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n" 948 " specifies the audio backend to use\n" 949 " id= identifier of the backend\n" 950 " timer-period= timer period in microseconds\n" 951 " in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n" 952 " in|out.fixed-settings= use fixed settings for host audio\n" 953 " in|out.frequency= frequency to use with fixed settings\n" 954 " in|out.channels= number of channels to use with fixed settings\n" 955 " in|out.format= sample format to use with fixed settings\n" 956 " valid values: s8, s16, s32, u8, u16, u32\n" 957 " in|out.voices= number of voices to use\n" 958 " in|out.buffer-length= length of buffer in microseconds\n" 959 "-audiodev none,id=id,[,prop[=value][,...]]\n" 960 " dummy driver that discards all output\n" 961#ifdef CONFIG_AUDIO_ALSA 962 "-audiodev alsa,id=id[,prop[=value][,...]]\n" 963 " in|out.dev= name of the audio device to use\n" 964 " in|out.period-length= length of period in microseconds\n" 965 " in|out.try-poll= attempt to use poll mode\n" 966 " threshold= threshold (in microseconds) when playback starts\n" 967#endif 968#ifdef CONFIG_AUDIO_COREAUDIO 969 "-audiodev coreaudio,id=id[,prop[=value][,...]]\n" 970 " in|out.buffer-count= number of buffers\n" 971#endif 972#ifdef CONFIG_AUDIO_DSOUND 973 "-audiodev dsound,id=id[,prop[=value][,...]]\n" 974 " latency= add extra latency to playback in microseconds\n" 975#endif 976#ifdef CONFIG_AUDIO_OSS 977 "-audiodev oss,id=id[,prop[=value][,...]]\n" 978 " in|out.dev= path of the audio device to use\n" 979 " in|out.buffer-count= number of buffers\n" 980 " in|out.try-poll= attempt to use poll mode\n" 981 " try-mmap= try using memory mapped access\n" 982 " exclusive= open device in exclusive mode\n" 983 " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n" 984#endif 985#ifdef CONFIG_AUDIO_PA 986 "-audiodev pa,id=id[,prop[=value][,...]]\n" 987 " server= PulseAudio server address\n" 988 " in|out.name= source/sink device name\n" 989 " in|out.latency= desired latency in microseconds\n" 990#endif 991#ifdef CONFIG_AUDIO_SDL 992 "-audiodev sdl,id=id[,prop[=value][,...]]\n" 993#endif 994#ifdef CONFIG_SPICE 995 "-audiodev spice,id=id[,prop[=value][,...]]\n" 996#endif 997 "-audiodev wav,id=id[,prop[=value][,...]]\n" 998 " path= path of wav file to record\n", 999 QEMU_ARCH_ALL) 1000STEXI 1001@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]] 1002@findex -audiodev 1003Adds a new audio backend @var{driver} identified by @var{id}. There are 1004global and driver specific properties. Some values can be set 1005differently for input and output, they're marked with @code{in|out.}. 1006You can set the input's property with @code{in.@var{prop}} and the 1007output's property with @code{out.@var{prop}}. For example: 1008@example 1009-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 1010-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified 1011@end example 1012 1013NOTE: parameter validation is known to be incomplete, in many cases 1014specifying an invalid option causes QEMU to print an error message and 1015continue emulation without sound. 1016 1017Valid global options are: 1018 1019@table @option 1020@item id=@var{identifier} 1021Identifies the audio backend. 1022 1023@item timer-period=@var{period} 1024Sets the timer @var{period} used by the audio subsystem in microseconds. 1025Default is 10000 (10 ms). 1026 1027@item in|out.mixing-engine=on|off 1028Use QEMU's mixing engine to mix all streams inside QEMU and convert 1029audio formats when not supported by the backend. When off, 1030@var{fixed-settings} must be off too. Note that disabling this option 1031means that the selected backend must support multiple streams and the 1032audio formats used by the virtual cards, otherwise you'll get no sound. 1033It's not recommended to disable this option unless you want to use 5.1 1034or 7.1 audio, as mixing engine only supports mono and stereo audio. 1035Default is on. 1036 1037@item in|out.fixed-settings=on|off 1038Use fixed settings for host audio. When off, it will change based on 1039how the guest opens the sound card. In this case you must not specify 1040@var{frequency}, @var{channels} or @var{format}. Default is on. 1041 1042@item in|out.frequency=@var{frequency} 1043Specify the @var{frequency} to use when using @var{fixed-settings}. 1044Default is 44100Hz. 1045 1046@item in|out.channels=@var{channels} 1047Specify the number of @var{channels} to use when using 1048@var{fixed-settings}. Default is 2 (stereo). 1049 1050@item in|out.format=@var{format} 1051Specify the sample @var{format} to use when using @var{fixed-settings}. 1052Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8}, 1053@code{u16}, @code{u32}. Default is @code{s16}. 1054 1055@item in|out.voices=@var{voices} 1056Specify the number of @var{voices} to use. Default is 1. 1057 1058@item in|out.buffer-length=@var{usecs} 1059Sets the size of the buffer in microseconds. 1060 1061@end table 1062 1063@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1064Creates a dummy backend that discards all outputs. This backend has no 1065backend specific properties. 1066 1067@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1068Creates backend using the ALSA. This backend is only available on 1069Linux. 1070 1071ALSA specific options are: 1072 1073@table @option 1074 1075@item in|out.dev=@var{device} 1076Specify the ALSA @var{device} to use for input and/or output. Default 1077is @code{default}. 1078 1079@item in|out.period-length=@var{usecs} 1080Sets the period length in microseconds. 1081 1082@item in|out.try-poll=on|off 1083Attempt to use poll mode with the device. Default is on. 1084 1085@item threshold=@var{threshold} 1086Threshold (in microseconds) when playback starts. Default is 0. 1087 1088@end table 1089 1090@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1091Creates a backend using Apple's Core Audio. This backend is only 1092available on Mac OS and only supports playback. 1093 1094Core Audio specific options are: 1095 1096@table @option 1097 1098@item in|out.buffer-count=@var{count} 1099Sets the @var{count} of the buffers. 1100 1101@end table 1102 1103@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1104Creates a backend using Microsoft's DirectSound. This backend is only 1105available on Windows and only supports playback. 1106 1107DirectSound specific options are: 1108 1109@table @option 1110 1111@item latency=@var{usecs} 1112Add extra @var{usecs} microseconds latency to playback. Default is 111310000 (10 ms). 1114 1115@end table 1116 1117@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1118Creates a backend using OSS. This backend is available on most 1119Unix-like systems. 1120 1121OSS specific options are: 1122 1123@table @option 1124 1125@item in|out.dev=@var{device} 1126Specify the file name of the OSS @var{device} to use. Default is 1127@code{/dev/dsp}. 1128 1129@item in|out.buffer-count=@var{count} 1130Sets the @var{count} of the buffers. 1131 1132@item in|out.try-poll=on|of 1133Attempt to use poll mode with the device. Default is on. 1134 1135@item try-mmap=on|off 1136Try using memory mapped device access. Default is off. 1137 1138@item exclusive=on|off 1139Open the device in exclusive mode (vmix won't work in this case). 1140Default is off. 1141 1142@item dsp-policy=@var{policy} 1143Sets the timing policy (between 0 and 10, where smaller number means 1144smaller latency but higher CPU usage). Use -1 to use buffer sizes 1145specified by @code{buffer} and @code{buffer-count}. This option is 1146ignored if you do not have OSS 4. Default is 5. 1147 1148@end table 1149 1150@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1151Creates a backend using PulseAudio. This backend is available on most 1152systems. 1153 1154PulseAudio specific options are: 1155 1156@table @option 1157 1158@item server=@var{server} 1159Sets the PulseAudio @var{server} to connect to. 1160 1161@item in|out.name=@var{sink} 1162Use the specified source/sink for recording/playback. 1163 1164@item in|out.latency=@var{usecs} 1165Desired latency in microseconds. The PulseAudio server will try to honor this 1166value but actual latencies may be lower or higher. 1167 1168@end table 1169 1170@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1171Creates a backend using SDL. This backend is available on most systems, 1172but you should use your platform's native backend if possible. This 1173backend has no backend specific properties. 1174 1175@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1176Creates a backend that sends audio through SPICE. This backend requires 1177@code{-spice} and automatically selected in that case, so usually you 1178can ignore this option. This backend has no backend specific 1179properties. 1180 1181@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]] 1182Creates a backend that writes audio to a WAV file. 1183 1184Backend specific options are: 1185 1186@table @option 1187 1188@item path=@var{path} 1189Write recorded audio into the specified file. Default is 1190@code{qemu.wav}. 1191 1192@end table 1193ETEXI 1194SRST 1195``-audiodev [driver=]driver,id=id[,prop[=value][,...]]`` 1196 Adds a new audio backend driver identified by id. There are global 1197 and driver specific properties. Some values can be set differently 1198 for input and output, they're marked with ``in|out.``. You can set 1199 the input's property with ``in.prop`` and the output's property with 1200 ``out.prop``. For example: 1201 1202 :: 1203 1204 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 1205 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified 1206 1207 NOTE: parameter validation is known to be incomplete, in many cases 1208 specifying an invalid option causes QEMU to print an error message 1209 and continue emulation without sound. 1210 1211 Valid global options are: 1212 1213 ``id=identifier`` 1214 Identifies the audio backend. 1215 1216 ``timer-period=period`` 1217 Sets the timer period used by the audio subsystem in 1218 microseconds. Default is 10000 (10 ms). 1219 1220 ``in|out.mixing-engine=on|off`` 1221 Use QEMU's mixing engine to mix all streams inside QEMU and 1222 convert audio formats when not supported by the backend. When 1223 off, fixed-settings must be off too. Note that disabling this 1224 option means that the selected backend must support multiple 1225 streams and the audio formats used by the virtual cards, 1226 otherwise you'll get no sound. It's not recommended to disable 1227 this option unless you want to use 5.1 or 7.1 audio, as mixing 1228 engine only supports mono and stereo audio. Default is on. 1229 1230 ``in|out.fixed-settings=on|off`` 1231 Use fixed settings for host audio. When off, it will change 1232 based on how the guest opens the sound card. In this case you 1233 must not specify frequency, channels or format. Default is on. 1234 1235 ``in|out.frequency=frequency`` 1236 Specify the frequency to use when using fixed-settings. Default 1237 is 44100Hz. 1238 1239 ``in|out.channels=channels`` 1240 Specify the number of channels to use when using fixed-settings. 1241 Default is 2 (stereo). 1242 1243 ``in|out.format=format`` 1244 Specify the sample format to use when using fixed-settings. 1245 Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``, 1246 ``u32``. Default is ``s16``. 1247 1248 ``in|out.voices=voices`` 1249 Specify the number of voices to use. Default is 1. 1250 1251 ``in|out.buffer-length=usecs`` 1252 Sets the size of the buffer in microseconds. 1253 1254``-audiodev none,id=id[,prop[=value][,...]]`` 1255 Creates a dummy backend that discards all outputs. This backend has 1256 no backend specific properties. 1257 1258``-audiodev alsa,id=id[,prop[=value][,...]]`` 1259 Creates backend using the ALSA. This backend is only available on 1260 Linux. 1261 1262 ALSA specific options are: 1263 1264 ``in|out.dev=device`` 1265 Specify the ALSA device to use for input and/or output. Default 1266 is ``default``. 1267 1268 ``in|out.period-length=usecs`` 1269 Sets the period length in microseconds. 1270 1271 ``in|out.try-poll=on|off`` 1272 Attempt to use poll mode with the device. Default is on. 1273 1274 ``threshold=threshold`` 1275 Threshold (in microseconds) when playback starts. Default is 0. 1276 1277``-audiodev coreaudio,id=id[,prop[=value][,...]]`` 1278 Creates a backend using Apple's Core Audio. This backend is only 1279 available on Mac OS and only supports playback. 1280 1281 Core Audio specific options are: 1282 1283 ``in|out.buffer-count=count`` 1284 Sets the count of the buffers. 1285 1286``-audiodev dsound,id=id[,prop[=value][,...]]`` 1287 Creates a backend using Microsoft's DirectSound. This backend is 1288 only available on Windows and only supports playback. 1289 1290 DirectSound specific options are: 1291 1292 ``latency=usecs`` 1293 Add extra usecs microseconds latency to playback. Default is 1294 10000 (10 ms). 1295 1296``-audiodev oss,id=id[,prop[=value][,...]]`` 1297 Creates a backend using OSS. This backend is available on most 1298 Unix-like systems. 1299 1300 OSS specific options are: 1301 1302 ``in|out.dev=device`` 1303 Specify the file name of the OSS device to use. Default is 1304 ``/dev/dsp``. 1305 1306 ``in|out.buffer-count=count`` 1307 Sets the count of the buffers. 1308 1309 ``in|out.try-poll=on|of`` 1310 Attempt to use poll mode with the device. Default is on. 1311 1312 ``try-mmap=on|off`` 1313 Try using memory mapped device access. Default is off. 1314 1315 ``exclusive=on|off`` 1316 Open the device in exclusive mode (vmix won't work in this 1317 case). Default is off. 1318 1319 ``dsp-policy=policy`` 1320 Sets the timing policy (between 0 and 10, where smaller number 1321 means smaller latency but higher CPU usage). Use -1 to use 1322 buffer sizes specified by ``buffer`` and ``buffer-count``. This 1323 option is ignored if you do not have OSS 4. Default is 5. 1324 1325``-audiodev pa,id=id[,prop[=value][,...]]`` 1326 Creates a backend using PulseAudio. This backend is available on 1327 most systems. 1328 1329 PulseAudio specific options are: 1330 1331 ``server=server`` 1332 Sets the PulseAudio server to connect to. 1333 1334 ``in|out.name=sink`` 1335 Use the specified source/sink for recording/playback. 1336 1337 ``in|out.latency=usecs`` 1338 Desired latency in microseconds. The PulseAudio server will try 1339 to honor this value but actual latencies may be lower or higher. 1340 1341``-audiodev sdl,id=id[,prop[=value][,...]]`` 1342 Creates a backend using SDL. This backend is available on most 1343 systems, but you should use your platform's native backend if 1344 possible. This backend has no backend specific properties. 1345 1346``-audiodev spice,id=id[,prop[=value][,...]]`` 1347 Creates a backend that sends audio through SPICE. This backend 1348 requires ``-spice`` and automatically selected in that case, so 1349 usually you can ignore this option. This backend has no backend 1350 specific properties. 1351 1352``-audiodev wav,id=id[,prop[=value][,...]]`` 1353 Creates a backend that writes audio to a WAV file. 1354 1355 Backend specific options are: 1356 1357 ``path=path`` 1358 Write recorded audio into the specified file. Default is 1359 ``qemu.wav``. 1360ERST 1361 1362DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 1363 "-soundhw c1,... enable audio support\n" 1364 " and only specified sound cards (comma separated list)\n" 1365 " use '-soundhw help' to get the list of supported cards\n" 1366 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 1367STEXI 1368@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 1369@findex -soundhw 1370Enable audio and selected sound hardware. Use 'help' to print all 1371available sound hardware. For example: 1372 1373@example 1374@value{qemu_system_x86} -soundhw sb16,adlib disk.img 1375@value{qemu_system_x86} -soundhw es1370 disk.img 1376@value{qemu_system_x86} -soundhw ac97 disk.img 1377@value{qemu_system_x86} -soundhw hda disk.img 1378@value{qemu_system_x86} -soundhw all disk.img 1379@value{qemu_system_x86} -soundhw help 1380@end example 1381 1382Note that Linux's i810_audio OSS kernel (for AC97) module might 1383require manually specifying clocking. 1384 1385@example 1386modprobe i810_audio clocking=48000 1387@end example 1388ETEXI 1389SRST 1390``-soundhw card1[,card2,...] or -soundhw all`` 1391 Enable audio and selected sound hardware. Use 'help' to print all 1392 available sound hardware. For example: 1393 1394 .. parsed-literal:: 1395 1396 |qemu_system_x86| -soundhw sb16,adlib disk.img 1397 |qemu_system_x86| -soundhw es1370 disk.img 1398 |qemu_system_x86| -soundhw ac97 disk.img 1399 |qemu_system_x86| -soundhw hda disk.img 1400 |qemu_system_x86| -soundhw all disk.img 1401 |qemu_system_x86| -soundhw help 1402 1403 Note that Linux's i810\_audio OSS kernel (for AC97) module might 1404 require manually specifying clocking. 1405 1406 :: 1407 1408 modprobe i810_audio clocking=48000 1409ERST 1410 1411DEF("device", HAS_ARG, QEMU_OPTION_device, 1412 "-device driver[,prop[=value][,...]]\n" 1413 " add device (based on driver)\n" 1414 " prop=value,... sets driver properties\n" 1415 " use '-device help' to print all possible drivers\n" 1416 " use '-device driver,help' to print all possible properties\n", 1417 QEMU_ARCH_ALL) 1418STEXI 1419@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 1420@findex -device 1421Add device @var{driver}. @var{prop}=@var{value} sets driver 1422properties. Valid properties depend on the driver. To get help on 1423possible drivers and properties, use @code{-device help} and 1424@code{-device @var{driver},help}. 1425 1426Some drivers are: 1427@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}] 1428 1429Add an IPMI BMC. This is a simulation of a hardware management 1430interface processor that normally sits on a system. It provides 1431a watchdog and the ability to reset and power control the system. 1432You need to connect this to an IPMI interface to make it useful 1433 1434The IPMI slave address to use for the BMC. The default is 0x20. 1435This address is the BMC's address on the I2C network of management 1436controllers. If you don't know what this means, it is safe to ignore 1437it. 1438 1439@table @option 1440@item id=@var{id} 1441The BMC id for interfaces to use this device. 1442@item slave_addr=@var{val} 1443Define slave address to use for the BMC. The default is 0x20. 1444@item sdrfile=@var{file} 1445file containing raw Sensor Data Records (SDR) data. The default is none. 1446@item fruareasize=@var{val} 1447size of a Field Replaceable Unit (FRU) area. The default is 1024. 1448@item frudatafile=@var{file} 1449file containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 1450@item guid=@var{uuid} 1451value for the GUID for the BMC, in standard UUID format. If this is set, 1452get "Get GUID" command to the BMC will return it. Otherwise "Get GUID" 1453will return an error. 1454@end table 1455 1456@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 1457 1458Add a connection to an external IPMI BMC simulator. Instead of 1459locally emulating the BMC like the above item, instead connect 1460to an external entity that provides the IPMI services. 1461 1462A connection is made to an external BMC simulator. If you do this, it 1463is strongly recommended that you use the "reconnect=" chardev option 1464to reconnect to the simulator if the connection is lost. Note that if 1465this is not used carefully, it can be a security issue, as the 1466interface has the ability to send resets, NMIs, and power off the VM. 1467It's best if QEMU makes a connection to an external simulator running 1468on a secure port on localhost, so neither the simulator nor QEMU is 1469exposed to any outside network. 1470 1471See the "lanserv/README.vm" file in the OpenIPMI library for more 1472details on the external interface. 1473 1474@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 1475 1476Add a KCS IPMI interafce on the ISA bus. This also adds a 1477corresponding ACPI and SMBIOS entries, if appropriate. 1478 1479@table @option 1480@item bmc=@var{id} 1481The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 1482@item ioport=@var{val} 1483Define the I/O address of the interface. The default is 0xca0 for KCS. 1484@item irq=@var{val} 1485Define the interrupt to use. The default is 5. To disable interrupts, 1486set this to 0. 1487@end table 1488 1489@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 1490 1491Like the KCS interface, but defines a BT interface. The default port is 14920xe4 and the default interrupt is 5. 1493 1494ETEXI 1495SRST 1496``-device driver[,prop[=value][,...]]`` 1497 Add device driver. prop=value sets driver properties. Valid 1498 properties depend on the driver. To get help on possible drivers and 1499 properties, use ``-device help`` and ``-device driver,help``. 1500 1501 Some drivers are: 1502 1503``-device ipmi-bmc-sim,id=id[,slave_addr=val][,sdrfile=file][,furareasize=val][,furdatafile=file][,guid=uuid]`` 1504 Add an IPMI BMC. This is a simulation of a hardware management 1505 interface processor that normally sits on a system. It provides a 1506 watchdog and the ability to reset and power control the system. You 1507 need to connect this to an IPMI interface to make it useful 1508 1509 The IPMI slave address to use for the BMC. The default is 0x20. This 1510 address is the BMC's address on the I2C network of management 1511 controllers. If you don't know what this means, it is safe to ignore 1512 it. 1513 1514 ``id=id`` 1515 The BMC id for interfaces to use this device. 1516 1517 ``slave_addr=val`` 1518 Define slave address to use for the BMC. The default is 0x20. 1519 1520 ``sdrfile=file`` 1521 file containing raw Sensor Data Records (SDR) data. The default 1522 is none. 1523 1524 ``fruareasize=val`` 1525 size of a Field Replaceable Unit (FRU) area. The default is 1526 1024. 1527 1528 ``frudatafile=file`` 1529 file containing raw Field Replaceable Unit (FRU) inventory data. 1530 The default is none. 1531 1532 ``guid=uuid`` 1533 value for the GUID for the BMC, in standard UUID format. If this 1534 is set, get "Get GUID" command to the BMC will return it. 1535 Otherwise "Get GUID" will return an error. 1536 1537``-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]`` 1538 Add a connection to an external IPMI BMC simulator. Instead of 1539 locally emulating the BMC like the above item, instead connect to an 1540 external entity that provides the IPMI services. 1541 1542 A connection is made to an external BMC simulator. If you do this, 1543 it is strongly recommended that you use the "reconnect=" chardev 1544 option to reconnect to the simulator if the connection is lost. Note 1545 that if this is not used carefully, it can be a security issue, as 1546 the interface has the ability to send resets, NMIs, and power off 1547 the VM. It's best if QEMU makes a connection to an external 1548 simulator running on a secure port on localhost, so neither the 1549 simulator nor QEMU is exposed to any outside network. 1550 1551 See the "lanserv/README.vm" file in the OpenIPMI library for more 1552 details on the external interface. 1553 1554``-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]`` 1555 Add a KCS IPMI interafce on the ISA bus. This also adds a 1556 corresponding ACPI and SMBIOS entries, if appropriate. 1557 1558 ``bmc=id`` 1559 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern 1560 above. 1561 1562 ``ioport=val`` 1563 Define the I/O address of the interface. The default is 0xca0 1564 for KCS. 1565 1566 ``irq=val`` 1567 Define the interrupt to use. The default is 5. To disable 1568 interrupts, set this to 0. 1569 1570``-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]`` 1571 Like the KCS interface, but defines a BT interface. The default port 1572 is 0xe4 and the default interrupt is 5. 1573ERST 1574 1575DEF("name", HAS_ARG, QEMU_OPTION_name, 1576 "-name string1[,process=string2][,debug-threads=on|off]\n" 1577 " set the name of the guest\n" 1578 " string1 sets the window title and string2 the process name\n" 1579 " When debug-threads is enabled, individual threads are given a separate name\n" 1580 " NOTE: The thread names are for debugging and not a stable API.\n", 1581 QEMU_ARCH_ALL) 1582STEXI 1583@item -name @var{name} 1584@findex -name 1585Sets the @var{name} of the guest. 1586This name will be displayed in the SDL window caption. 1587The @var{name} will also be used for the VNC server. 1588Also optionally set the top visible process name in Linux. 1589Naming of individual threads can also be enabled on Linux to aid debugging. 1590ETEXI 1591SRST 1592``-name name`` 1593 Sets the name of the guest. This name will be displayed in the SDL 1594 window caption. The name will also be used for the VNC server. Also 1595 optionally set the top visible process name in Linux. Naming of 1596 individual threads can also be enabled on Linux to aid debugging. 1597ERST 1598 1599DEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 1600 "-uuid %08x-%04x-%04x-%04x-%012x\n" 1601 " specify machine UUID\n", QEMU_ARCH_ALL) 1602STEXI 1603@item -uuid @var{uuid} 1604@findex -uuid 1605Set system UUID. 1606ETEXI 1607SRST 1608``-uuid uuid`` 1609 Set system UUID. 1610ERST 1611 1612STEXI 1613@end table 1614ETEXI 1615DEFHEADING() 1616 1617DEFHEADING(Block device options:) 1618STEXI 1619@table @option 1620ETEXI 1621 1622DEF("fda", HAS_ARG, QEMU_OPTION_fda, 1623 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 1624DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 1625STEXI 1626@item -fda @var{file} 1627@itemx -fdb @var{file} 1628@findex -fda 1629@findex -fdb 1630Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 1631ETEXI 1632SRST 1633``-fda file`` 1634 \ 1635``-fdb file`` 1636 Use file as floppy disk 0/1 image (see 1637 :ref:`disk_005fimages`). 1638ERST 1639 1640DEF("hda", HAS_ARG, QEMU_OPTION_hda, 1641 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 1642DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 1643DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 1644 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 1645DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 1646STEXI 1647@item -hda @var{file} 1648@itemx -hdb @var{file} 1649@itemx -hdc @var{file} 1650@itemx -hdd @var{file} 1651@findex -hda 1652@findex -hdb 1653@findex -hdc 1654@findex -hdd 1655Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 1656ETEXI 1657SRST 1658``-hda file`` 1659 \ 1660``-hdb file`` 1661 \ 1662``-hdc file`` 1663 \ 1664``-hdd file`` 1665 Use file as hard disk 0, 1, 2 or 3 image (see 1666 :ref:`disk_005fimages`). 1667ERST 1668 1669DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 1670 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 1671 QEMU_ARCH_ALL) 1672STEXI 1673@item -cdrom @var{file} 1674@findex -cdrom 1675Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 1676@option{-cdrom} at the same time). You can use the host CD-ROM by 1677using @file{/dev/cdrom} as filename. 1678ETEXI 1679SRST 1680``-cdrom file`` 1681 Use file as CD-ROM image (you cannot use ``-hdc`` and ``-cdrom`` at 1682 the same time). You can use the host CD-ROM by using ``/dev/cdrom`` 1683 as filename. 1684ERST 1685 1686DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 1687 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 1688 " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 1689 " [,read-only=on|off][,auto-read-only=on|off]\n" 1690 " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n" 1691 " [,driver specific parameters...]\n" 1692 " configure a block backend\n", QEMU_ARCH_ALL) 1693STEXI 1694@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 1695@findex -blockdev 1696 1697Define a new block driver node. Some of the options apply to all block drivers, 1698other options are only accepted for a specific block driver. See below for a 1699list of generic options and options for the most common block drivers. 1700 1701Options that expect a reference to another node (e.g. @code{file}) can be 1702given in two ways. Either you specify the node name of an already existing node 1703(file=@var{node-name}), or you define a new node inline, adding options 1704for the referenced node after a dot (file.filename=@var{path},file.aio=native). 1705 1706A block driver node created with @option{-blockdev} can be used for a guest 1707device by specifying its node name for the @code{drive} property in a 1708@option{-device} argument that defines a block device. 1709 1710@table @option 1711@item Valid options for any block driver node: 1712 1713@table @code 1714@item driver 1715Specifies the block driver to use for the given node. 1716@item node-name 1717This defines the name of the block driver node by which it will be referenced 1718later. The name must be unique, i.e. it must not match the name of a different 1719block driver node, or (if you use @option{-drive} as well) the ID of a drive. 1720 1721If no node name is specified, it is automatically generated. The generated node 1722name is not intended to be predictable and changes between QEMU invocations. 1723For the top level, an explicit node name must be specified. 1724@item read-only 1725Open the node read-only. Guest write attempts will fail. 1726 1727Note that some block drivers support only read-only access, either generally or 1728in certain configurations. In this case, the default value 1729@option{read-only=off} does not work and the option must be specified 1730explicitly. 1731@item auto-read-only 1732If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage 1733even when @option{read-only=off} is requested, or even switch between modes as 1734needed, e.g. depending on whether the image file is writable or whether a 1735writing user is attached to the node. 1736@item force-share 1737Override the image locking system of QEMU by forcing the node to utilize 1738weaker shared access for permissions where it would normally request exclusive 1739access. When there is the potential for multiple instances to have the same 1740file open (whether this invocation of QEMU is the first or the second 1741instance), both instances must permit shared access for the second instance to 1742succeed at opening the file. 1743 1744Enabling @option{force-share=on} requires @option{read-only=on}. 1745@item cache.direct 1746The host page cache can be avoided with @option{cache.direct=on}. This will 1747attempt to do disk IO directly to the guest's memory. QEMU may still perform an 1748internal copy of the data. 1749@item cache.no-flush 1750In case you don't care about data integrity over host failures, you can use 1751@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 1752any data to the disk but can instead keep things in cache. If anything goes 1753wrong, like your host losing power, the disk storage getting disconnected 1754accidentally, etc. your image will most probably be rendered unusable. 1755@item discard=@var{discard} 1756@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 1757whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 1758ignored or passed to the filesystem. Some machine types may not support 1759discard requests. 1760@item detect-zeroes=@var{detect-zeroes} 1761@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 1762conversion of plain zero writes by the OS to driver specific optimized 1763zero write commands. You may even choose "unmap" if @var{discard} is set 1764to "unmap" to allow a zero write to be converted to an @code{unmap} operation. 1765@end table 1766 1767@item Driver-specific options for @code{file} 1768 1769This is the protocol-level block driver for accessing regular files. 1770 1771@table @code 1772@item filename 1773The path to the image file in the local filesystem 1774@item aio 1775Specifies the AIO backend (threads/native, default: threads) 1776@item locking 1777Specifies whether the image file is protected with Linux OFD / POSIX locks. The 1778default is to use the Linux Open File Descriptor API if available, otherwise no 1779lock is applied. (auto/on/off, default: auto) 1780@end table 1781Example: 1782@example 1783-blockdev driver=file,node-name=disk,filename=disk.img 1784@end example 1785 1786@item Driver-specific options for @code{raw} 1787 1788This is the image format block driver for raw images. It is usually 1789stacked on top of a protocol level block driver such as @code{file}. 1790 1791@table @code 1792@item file 1793Reference to or definition of the data source block driver node 1794(e.g. a @code{file} driver node) 1795@end table 1796Example 1: 1797@example 1798-blockdev driver=file,node-name=disk_file,filename=disk.img 1799-blockdev driver=raw,node-name=disk,file=disk_file 1800@end example 1801Example 2: 1802@example 1803-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 1804@end example 1805 1806@item Driver-specific options for @code{qcow2} 1807 1808This is the image format block driver for qcow2 images. It is usually 1809stacked on top of a protocol level block driver such as @code{file}. 1810 1811@table @code 1812@item file 1813Reference to or definition of the data source block driver node 1814(e.g. a @code{file} driver node) 1815 1816@item backing 1817Reference to or definition of the backing file block device (default is taken 1818from the image file). It is allowed to pass @code{null} here in order to disable 1819the default backing file. 1820 1821@item lazy-refcounts 1822Whether to enable the lazy refcounts feature (on/off; default is taken from the 1823image file) 1824 1825@item cache-size 1826The maximum total size of the L2 table and refcount block caches in bytes 1827(default: the sum of l2-cache-size and refcount-cache-size) 1828 1829@item l2-cache-size 1830The maximum size of the L2 table cache in bytes 1831(default: if cache-size is not specified - 32M on Linux platforms, and 8M on 1832non-Linux platforms; otherwise, as large as possible within the cache-size, 1833while permitting the requested or the minimal refcount cache size) 1834 1835@item refcount-cache-size 1836The maximum size of the refcount block cache in bytes 1837(default: 4 times the cluster size; or if cache-size is specified, the part of 1838it which is not used for the L2 cache) 1839 1840@item cache-clean-interval 1841Clean unused entries in the L2 and refcount caches. The interval is in seconds. 1842The default value is 600 on supporting platforms, and 0 on other platforms. 1843Setting it to 0 disables this feature. 1844 1845@item pass-discard-request 1846Whether discard requests to the qcow2 device should be forwarded to the data 1847source (on/off; default: on if discard=unmap is specified, off otherwise) 1848 1849@item pass-discard-snapshot 1850Whether discard requests for the data source should be issued when a snapshot 1851operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 1852default: on) 1853 1854@item pass-discard-other 1855Whether discard requests for the data source should be issued on other 1856occasions where a cluster gets freed (on/off; default: off) 1857 1858@item overlap-check 1859Which overlap checks to perform for writes to the image 1860(none/constant/cached/all; default: cached). For details or finer 1861granularity control refer to the QAPI documentation of @code{blockdev-add}. 1862@end table 1863 1864Example 1: 1865@example 1866-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 1867-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 1868@end example 1869Example 2: 1870@example 1871-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 1872@end example 1873 1874@item Driver-specific options for other drivers 1875Please refer to the QAPI documentation of the @code{blockdev-add} QMP command. 1876 1877@end table 1878 1879ETEXI 1880SRST 1881``-blockdev option[,option[,option[,...]]]`` 1882 Define a new block driver node. Some of the options apply to all 1883 block drivers, other options are only accepted for a specific block 1884 driver. See below for a list of generic options and options for the 1885 most common block drivers. 1886 1887 Options that expect a reference to another node (e.g. ``file``) can 1888 be given in two ways. Either you specify the node name of an already 1889 existing node (file=node-name), or you define a new node inline, 1890 adding options for the referenced node after a dot 1891 (file.filename=path,file.aio=native). 1892 1893 A block driver node created with ``-blockdev`` can be used for a 1894 guest device by specifying its node name for the ``drive`` property 1895 in a ``-device`` argument that defines a block device. 1896 1897 ``Valid options for any block driver node:`` 1898 ``driver`` 1899 Specifies the block driver to use for the given node. 1900 1901 ``node-name`` 1902 This defines the name of the block driver node by which it 1903 will be referenced later. The name must be unique, i.e. it 1904 must not match the name of a different block driver node, or 1905 (if you use ``-drive`` as well) the ID of a drive. 1906 1907 If no node name is specified, it is automatically generated. 1908 The generated node name is not intended to be predictable 1909 and changes between QEMU invocations. For the top level, an 1910 explicit node name must be specified. 1911 1912 ``read-only`` 1913 Open the node read-only. Guest write attempts will fail. 1914 1915 Note that some block drivers support only read-only access, 1916 either generally or in certain configurations. In this case, 1917 the default value ``read-only=off`` does not work and the 1918 option must be specified explicitly. 1919 1920 ``auto-read-only`` 1921 If ``auto-read-only=on`` is set, QEMU may fall back to 1922 read-only usage even when ``read-only=off`` is requested, or 1923 even switch between modes as needed, e.g. depending on 1924 whether the image file is writable or whether a writing user 1925 is attached to the node. 1926 1927 ``force-share`` 1928 Override the image locking system of QEMU by forcing the 1929 node to utilize weaker shared access for permissions where 1930 it would normally request exclusive access. When there is 1931 the potential for multiple instances to have the same file 1932 open (whether this invocation of QEMU is the first or the 1933 second instance), both instances must permit shared access 1934 for the second instance to succeed at opening the file. 1935 1936 Enabling ``force-share=on`` requires ``read-only=on``. 1937 1938 ``cache.direct`` 1939 The host page cache can be avoided with ``cache.direct=on``. 1940 This will attempt to do disk IO directly to the guest's 1941 memory. QEMU may still perform an internal copy of the data. 1942 1943 ``cache.no-flush`` 1944 In case you don't care about data integrity over host 1945 failures, you can use ``cache.no-flush=on``. This option 1946 tells QEMU that it never needs to write any data to the disk 1947 but can instead keep things in cache. If anything goes 1948 wrong, like your host losing power, the disk storage getting 1949 disconnected accidentally, etc. your image will most 1950 probably be rendered unusable. 1951 1952 ``discard=discard`` 1953 discard is one of "ignore" (or "off") or "unmap" (or "on") 1954 and controls whether ``discard`` (also known as ``trim`` or 1955 ``unmap``) requests are ignored or passed to the filesystem. 1956 Some machine types may not support discard requests. 1957 1958 ``detect-zeroes=detect-zeroes`` 1959 detect-zeroes is "off", "on" or "unmap" and enables the 1960 automatic conversion of plain zero writes by the OS to 1961 driver specific optimized zero write commands. You may even 1962 choose "unmap" if discard is set to "unmap" to allow a zero 1963 write to be converted to an ``unmap`` operation. 1964 1965 ``Driver-specific options for file`` 1966 This is the protocol-level block driver for accessing regular 1967 files. 1968 1969 ``filename`` 1970 The path to the image file in the local filesystem 1971 1972 ``aio`` 1973 Specifies the AIO backend (threads/native, default: threads) 1974 1975 ``locking`` 1976 Specifies whether the image file is protected with Linux OFD 1977 / POSIX locks. The default is to use the Linux Open File 1978 Descriptor API if available, otherwise no lock is applied. 1979 (auto/on/off, default: auto) 1980 1981 Example: 1982 1983 :: 1984 1985 -blockdev driver=file,node-name=disk,filename=disk.img 1986 1987 ``Driver-specific options for raw`` 1988 This is the image format block driver for raw images. It is 1989 usually stacked on top of a protocol level block driver such as 1990 ``file``. 1991 1992 ``file`` 1993 Reference to or definition of the data source block driver 1994 node (e.g. a ``file`` driver node) 1995 1996 Example 1: 1997 1998 :: 1999 2000 -blockdev driver=file,node-name=disk_file,filename=disk.img 2001 -blockdev driver=raw,node-name=disk,file=disk_file 2002 2003 Example 2: 2004 2005 :: 2006 2007 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 2008 2009 ``Driver-specific options for qcow2`` 2010 This is the image format block driver for qcow2 images. It is 2011 usually stacked on top of a protocol level block driver such as 2012 ``file``. 2013 2014 ``file`` 2015 Reference to or definition of the data source block driver 2016 node (e.g. a ``file`` driver node) 2017 2018 ``backing`` 2019 Reference to or definition of the backing file block device 2020 (default is taken from the image file). It is allowed to 2021 pass ``null`` here in order to disable the default backing 2022 file. 2023 2024 ``lazy-refcounts`` 2025 Whether to enable the lazy refcounts feature (on/off; 2026 default is taken from the image file) 2027 2028 ``cache-size`` 2029 The maximum total size of the L2 table and refcount block 2030 caches in bytes (default: the sum of l2-cache-size and 2031 refcount-cache-size) 2032 2033 ``l2-cache-size`` 2034 The maximum size of the L2 table cache in bytes (default: if 2035 cache-size is not specified - 32M on Linux platforms, and 8M 2036 on non-Linux platforms; otherwise, as large as possible 2037 within the cache-size, while permitting the requested or the 2038 minimal refcount cache size) 2039 2040 ``refcount-cache-size`` 2041 The maximum size of the refcount block cache in bytes 2042 (default: 4 times the cluster size; or if cache-size is 2043 specified, the part of it which is not used for the L2 2044 cache) 2045 2046 ``cache-clean-interval`` 2047 Clean unused entries in the L2 and refcount caches. The 2048 interval is in seconds. The default value is 600 on 2049 supporting platforms, and 0 on other platforms. Setting it 2050 to 0 disables this feature. 2051 2052 ``pass-discard-request`` 2053 Whether discard requests to the qcow2 device should be 2054 forwarded to the data source (on/off; default: on if 2055 discard=unmap is specified, off otherwise) 2056 2057 ``pass-discard-snapshot`` 2058 Whether discard requests for the data source should be 2059 issued when a snapshot operation (e.g. deleting a snapshot) 2060 frees clusters in the qcow2 file (on/off; default: on) 2061 2062 ``pass-discard-other`` 2063 Whether discard requests for the data source should be 2064 issued on other occasions where a cluster gets freed 2065 (on/off; default: off) 2066 2067 ``overlap-check`` 2068 Which overlap checks to perform for writes to the image 2069 (none/constant/cached/all; default: cached). For details or 2070 finer granularity control refer to the QAPI documentation of 2071 ``blockdev-add``. 2072 2073 Example 1: 2074 2075 :: 2076 2077 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 2078 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 2079 2080 Example 2: 2081 2082 :: 2083 2084 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 2085 2086 ``Driver-specific options for other drivers`` 2087 Please refer to the QAPI documentation of the ``blockdev-add`` 2088 QMP command. 2089ERST 2090 2091DEF("drive", HAS_ARG, QEMU_OPTION_drive, 2092 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 2093 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 2094 " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 2095 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 2096 " [,readonly=on|off][,copy-on-read=on|off]\n" 2097 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 2098 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 2099 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 2100 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 2101 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 2102 " [[,iops_size=is]]\n" 2103 " [[,group=g]]\n" 2104 " use 'file' as a drive image\n", QEMU_ARCH_ALL) 2105STEXI 2106@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 2107@findex -drive 2108 2109Define a new drive. This includes creating a block driver node (the backend) as 2110well as a guest device, and is mostly a shortcut for defining the corresponding 2111@option{-blockdev} and @option{-device} options. 2112 2113@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 2114addition, it knows the following options: 2115 2116@table @option 2117@item file=@var{file} 2118This option defines which disk image (@pxref{disk_images}) to use with 2119this drive. If the filename contains comma, you must double it 2120(for instance, "file=my,,file" to use file "my,file"). 2121 2122Special files such as iSCSI devices can be specified using protocol 2123specific URLs. See the section for "Device URL Syntax" for more information. 2124@item if=@var{interface} 2125This option defines on which type on interface the drive is connected. 2126Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 2127@item bus=@var{bus},unit=@var{unit} 2128These options define where is connected the drive by defining the bus number and 2129the unit id. 2130@item index=@var{index} 2131This option defines where is connected the drive by using an index in the list 2132of available connectors of a given interface type. 2133@item media=@var{media} 2134This option defines the type of the media: disk or cdrom. 2135@item snapshot=@var{snapshot} 2136@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 2137(see @option{-snapshot}). 2138@item cache=@var{cache} 2139@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 2140and controls how the host cache is used to access block data. This is a 2141shortcut that sets the @option{cache.direct} and @option{cache.no-flush} 2142options (as in @option{-blockdev}), and additionally @option{cache.writeback}, 2143which provides a default for the @option{write-cache} option of block guest 2144devices (as in @option{-device}). The modes correspond to the following 2145settings: 2146 2147@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 2148@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 2149@c and the HTML output. 2150@example 2151@ │ cache.writeback cache.direct cache.no-flush 2152─────────────┼───────────────────────────────────────────────── 2153writeback │ on off off 2154none │ on on off 2155writethrough │ off off off 2156directsync │ off on off 2157unsafe │ on off on 2158@end example 2159 2160The default mode is @option{cache=writeback}. 2161 2162@item aio=@var{aio} 2163@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 2164@item format=@var{format} 2165Specify which disk @var{format} will be used rather than detecting 2166the format. Can be used to specify format=raw to avoid interpreting 2167an untrusted format header. 2168@item werror=@var{action},rerror=@var{action} 2169Specify which @var{action} to take on write and read errors. Valid actions are: 2170"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 2171"report" (report the error to the guest), "enospc" (pause QEMU only if the 2172host disk is full; report the error to the guest otherwise). 2173The default setting is @option{werror=enospc} and @option{rerror=report}. 2174@item copy-on-read=@var{copy-on-read} 2175@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 2176file sectors into the image file. 2177@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 2178Specify bandwidth throttling limits in bytes per second, either for all request 2179types or for reads or writes only. Small values can lead to timeouts or hangs 2180inside the guest. A safe minimum for disks is 2 MB/s. 2181@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 2182Specify bursts in bytes per second, either for all request types or for reads 2183or writes only. Bursts allow the guest I/O to spike above the limit 2184temporarily. 2185@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 2186Specify request rate limits in requests per second, either for all request 2187types or for reads or writes only. 2188@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 2189Specify bursts in requests per second, either for all request types or for reads 2190or writes only. Bursts allow the guest I/O to spike above the limit 2191temporarily. 2192@item iops_size=@var{is} 2193Let every @var{is} bytes of a request count as a new request for iops 2194throttling purposes. Use this option to prevent guests from circumventing iops 2195limits by sending fewer but larger requests. 2196@item group=@var{g} 2197Join a throttling quota group with given name @var{g}. All drives that are 2198members of the same group are accounted for together. Use this option to 2199prevent guests from circumventing throttling limits by using many small disks 2200instead of a single larger disk. 2201@end table 2202 2203By default, the @option{cache.writeback=on} mode is used. It will report data 2204writes as completed as soon as the data is present in the host page cache. 2205This is safe as long as your guest OS makes sure to correctly flush disk caches 2206where needed. If your guest OS does not handle volatile disk write caches 2207correctly and your host crashes or loses power, then the guest may experience 2208data corruption. 2209 2210For such guests, you should consider using @option{cache.writeback=off}. This 2211means that the host page cache will be used to read and write data, but write 2212notification will be sent to the guest only after QEMU has made sure to flush 2213each write to the disk. Be aware that this has a major impact on performance. 2214 2215When using the @option{-snapshot} option, unsafe caching is always used. 2216 2217Copy-on-read avoids accessing the same backing file sectors repeatedly and is 2218useful when the backing file is over a slow network. By default copy-on-read 2219is off. 2220 2221Instead of @option{-cdrom} you can use: 2222@example 2223@value{qemu_system} -drive file=file,index=2,media=cdrom 2224@end example 2225 2226Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 2227use: 2228@example 2229@value{qemu_system} -drive file=file,index=0,media=disk 2230@value{qemu_system} -drive file=file,index=1,media=disk 2231@value{qemu_system} -drive file=file,index=2,media=disk 2232@value{qemu_system} -drive file=file,index=3,media=disk 2233@end example 2234 2235You can open an image using pre-opened file descriptors from an fd set: 2236@example 2237@value{qemu_system} \ 2238 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 2239 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 2240 -drive file=/dev/fdset/2,index=0,media=disk 2241@end example 2242 2243You can connect a CDROM to the slave of ide0: 2244@example 2245@value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom 2246@end example 2247 2248If you don't specify the "file=" argument, you define an empty drive: 2249@example 2250@value{qemu_system_x86} -drive if=ide,index=1,media=cdrom 2251@end example 2252 2253Instead of @option{-fda}, @option{-fdb}, you can use: 2254@example 2255@value{qemu_system_x86} -drive file=file,index=0,if=floppy 2256@value{qemu_system_x86} -drive file=file,index=1,if=floppy 2257@end example 2258 2259By default, @var{interface} is "ide" and @var{index} is automatically 2260incremented: 2261@example 2262@value{qemu_system_x86} -drive file=a -drive file=b" 2263@end example 2264is interpreted like: 2265@example 2266@value{qemu_system_x86} -hda a -hdb b 2267@end example 2268ETEXI 2269SRST 2270``-drive option[,option[,option[,...]]]`` 2271 Define a new drive. This includes creating a block driver node (the 2272 backend) as well as a guest device, and is mostly a shortcut for 2273 defining the corresponding ``-blockdev`` and ``-device`` options. 2274 2275 ``-drive`` accepts all options that are accepted by ``-blockdev``. 2276 In addition, it knows the following options: 2277 2278 ``file=file`` 2279 This option defines which disk image (see 2280 :ref:`disk_005fimages`) to use with this drive. If 2281 the filename contains comma, you must double it (for instance, 2282 "file=my,,file" to use file "my,file"). 2283 2284 Special files such as iSCSI devices can be specified using 2285 protocol specific URLs. See the section for "Device URL Syntax" 2286 for more information. 2287 2288 ``if=interface`` 2289 This option defines on which type on interface the drive is 2290 connected. Available types are: ide, scsi, sd, mtd, floppy, 2291 pflash, virtio, none. 2292 2293 ``bus=bus,unit=unit`` 2294 These options define where is connected the drive by defining 2295 the bus number and the unit id. 2296 2297 ``index=index`` 2298 This option defines where is connected the drive by using an 2299 index in the list of available connectors of a given interface 2300 type. 2301 2302 ``media=media`` 2303 This option defines the type of the media: disk or cdrom. 2304 2305 ``snapshot=snapshot`` 2306 snapshot is "on" or "off" and controls snapshot mode for the 2307 given drive (see ``-snapshot``). 2308 2309 ``cache=cache`` 2310 cache is "none", "writeback", "unsafe", "directsync" or 2311 "writethrough" and controls how the host cache is used to access 2312 block data. This is a shortcut that sets the ``cache.direct`` 2313 and ``cache.no-flush`` options (as in ``-blockdev``), and 2314 additionally ``cache.writeback``, which provides a default for 2315 the ``write-cache`` option of block guest devices (as in 2316 ``-device``). The modes correspond to the following settings: 2317 2318 ============= =============== ============ ============== 2319 \ cache.writeback cache.direct cache.no-flush 2320 ============= =============== ============ ============== 2321 writeback on off off 2322 none on on off 2323 writethrough off off off 2324 directsync off on off 2325 unsafe on off on 2326 ============= =============== ============ ============== 2327 2328 The default mode is ``cache=writeback``. 2329 2330 ``aio=aio`` 2331 aio is "threads", or "native" and selects between pthread based 2332 disk I/O and native Linux AIO. 2333 2334 ``format=format`` 2335 Specify which disk format will be used rather than detecting the 2336 format. Can be used to specify format=raw to avoid interpreting 2337 an untrusted format header. 2338 2339 ``werror=action,rerror=action`` 2340 Specify which action to take on write and read errors. Valid 2341 actions are: "ignore" (ignore the error and try to continue), 2342 "stop" (pause QEMU), "report" (report the error to the guest), 2343 "enospc" (pause QEMU only if the host disk is full; report the 2344 error to the guest otherwise). The default setting is 2345 ``werror=enospc`` and ``rerror=report``. 2346 2347 ``copy-on-read=copy-on-read`` 2348 copy-on-read is "on" or "off" and enables whether to copy read 2349 backing file sectors into the image file. 2350 2351 ``bps=b,bps_rd=r,bps_wr=w`` 2352 Specify bandwidth throttling limits in bytes per second, either 2353 for all request types or for reads or writes only. Small values 2354 can lead to timeouts or hangs inside the guest. A safe minimum 2355 for disks is 2 MB/s. 2356 2357 ``bps_max=bm,bps_rd_max=rm,bps_wr_max=wm`` 2358 Specify bursts in bytes per second, either for all request types 2359 or for reads or writes only. Bursts allow the guest I/O to spike 2360 above the limit temporarily. 2361 2362 ``iops=i,iops_rd=r,iops_wr=w`` 2363 Specify request rate limits in requests per second, either for 2364 all request types or for reads or writes only. 2365 2366 ``iops_max=bm,iops_rd_max=rm,iops_wr_max=wm`` 2367 Specify bursts in requests per second, either for all request 2368 types or for reads or writes only. Bursts allow the guest I/O to 2369 spike above the limit temporarily. 2370 2371 ``iops_size=is`` 2372 Let every is bytes of a request count as a new request for iops 2373 throttling purposes. Use this option to prevent guests from 2374 circumventing iops limits by sending fewer but larger requests. 2375 2376 ``group=g`` 2377 Join a throttling quota group with given name g. All drives that 2378 are members of the same group are accounted for together. Use 2379 this option to prevent guests from circumventing throttling 2380 limits by using many small disks instead of a single larger 2381 disk. 2382 2383 By default, the ``cache.writeback=on`` mode is used. It will report 2384 data writes as completed as soon as the data is present in the host 2385 page cache. This is safe as long as your guest OS makes sure to 2386 correctly flush disk caches where needed. If your guest OS does not 2387 handle volatile disk write caches correctly and your host crashes or 2388 loses power, then the guest may experience data corruption. 2389 2390 For such guests, you should consider using ``cache.writeback=off``. 2391 This means that the host page cache will be used to read and write 2392 data, but write notification will be sent to the guest only after 2393 QEMU has made sure to flush each write to the disk. Be aware that 2394 this has a major impact on performance. 2395 2396 When using the ``-snapshot`` option, unsafe caching is always used. 2397 2398 Copy-on-read avoids accessing the same backing file sectors 2399 repeatedly and is useful when the backing file is over a slow 2400 network. By default copy-on-read is off. 2401 2402 Instead of ``-cdrom`` you can use: 2403 2404 .. parsed-literal:: 2405 2406 |qemu_system| -drive file=file,index=2,media=cdrom 2407 2408 Instead of ``-hda``, ``-hdb``, ``-hdc``, ``-hdd``, you can use: 2409 2410 .. parsed-literal:: 2411 2412 |qemu_system| -drive file=file,index=0,media=disk 2413 |qemu_system| -drive file=file,index=1,media=disk 2414 |qemu_system| -drive file=file,index=2,media=disk 2415 |qemu_system| -drive file=file,index=3,media=disk 2416 2417 You can open an image using pre-opened file descriptors from an fd 2418 set: 2419 2420 .. parsed-literal:: 2421 2422 |qemu_system| \ 2423 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \ 2424 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ 2425 -drive file=/dev/fdset/2,index=0,media=disk 2426 2427 You can connect a CDROM to the slave of ide0: 2428 2429 .. parsed-literal:: 2430 2431 |qemu_system_x86| -drive file=file,if=ide,index=1,media=cdrom 2432 2433 If you don't specify the "file=" argument, you define an empty 2434 drive: 2435 2436 .. parsed-literal:: 2437 2438 |qemu_system_x86| -drive if=ide,index=1,media=cdrom 2439 2440 Instead of ``-fda``, ``-fdb``, you can use: 2441 2442 .. parsed-literal:: 2443 2444 |qemu_system_x86| -drive file=file,index=0,if=floppy 2445 |qemu_system_x86| -drive file=file,index=1,if=floppy 2446 2447 By default, interface is "ide" and index is automatically 2448 incremented: 2449 2450 .. parsed-literal:: 2451 2452 |qemu_system_x86| -drive file=a -drive file=b" 2453 2454 is interpreted like: 2455 2456 .. parsed-literal:: 2457 2458 |qemu_system_x86| -hda a -hdb b 2459ERST 2460 2461DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 2462 "-mtdblock file use 'file' as on-board Flash memory image\n", 2463 QEMU_ARCH_ALL) 2464STEXI 2465@item -mtdblock @var{file} 2466@findex -mtdblock 2467Use @var{file} as on-board Flash memory image. 2468ETEXI 2469SRST 2470``-mtdblock file`` 2471 Use file as on-board Flash memory image. 2472ERST 2473 2474DEF("sd", HAS_ARG, QEMU_OPTION_sd, 2475 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 2476STEXI 2477@item -sd @var{file} 2478@findex -sd 2479Use @var{file} as SecureDigital card image. 2480ETEXI 2481SRST 2482``-sd file`` 2483 Use file as SecureDigital card image. 2484ERST 2485 2486DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 2487 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 2488STEXI 2489@item -pflash @var{file} 2490@findex -pflash 2491Use @var{file} as a parallel flash image. 2492ETEXI 2493SRST 2494``-pflash file`` 2495 Use file as a parallel flash image. 2496ERST 2497 2498DEF("snapshot", 0, QEMU_OPTION_snapshot, 2499 "-snapshot write to temporary files instead of disk image files\n", 2500 QEMU_ARCH_ALL) 2501STEXI 2502@item -snapshot 2503@findex -snapshot 2504Write to temporary files instead of disk image files. In this case, 2505the raw disk image you use is not written back. You can however force 2506the write back by pressing @key{C-a s} (@pxref{disk_images}). 2507ETEXI 2508SRST 2509``-snapshot`` 2510 Write to temporary files instead of disk image files. In this case, 2511 the raw disk image you use is not written back. You can however 2512 force the write back by pressing C-a s (see 2513 :ref:`disk_005fimages`). 2514ERST 2515 2516DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 2517 "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n" 2518 " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n" 2519 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 2520 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 2521 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 2522 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 2523 " [[,throttling.iops-size=is]]\n" 2524 "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n" 2525 "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n" 2526 "-fsdev synth,id=id\n", 2527 QEMU_ARCH_ALL) 2528 2529STEXI 2530 2531@item -fsdev local,id=@var{id},path=@var{path},security_model=@var{security_model} [,writeout=@var{writeout}][,readonly][,fmode=@var{fmode}][,dmode=@var{dmode}] [,throttling.@var{option}=@var{value}[,throttling.@var{option}=@var{value}[,...]]] 2532@itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly] 2533@itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly] 2534@itemx -fsdev synth,id=@var{id}[,readonly] 2535@findex -fsdev 2536Define a new file system device. Valid options are: 2537@table @option 2538@item local 2539Accesses to the filesystem are done by QEMU. 2540@item proxy 2541Accesses to the filesystem are done by virtfs-proxy-helper(1). 2542@item synth 2543Synthetic filesystem, only used by QTests. 2544@item id=@var{id} 2545Specifies identifier for this device. 2546@item path=@var{path} 2547Specifies the export path for the file system device. Files under 2548this path will be available to the 9p client on the guest. 2549@item security_model=@var{security_model} 2550Specifies the security model to be used for this export path. 2551Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 2552In "passthrough" security model, files are stored using the same 2553credentials as they are created on the guest. This requires QEMU 2554to run as root. In "mapped-xattr" security model, some of the file 2555attributes like uid, gid, mode bits and link target are stored as 2556file attributes. For "mapped-file" these attributes are stored in the 2557hidden .virtfs_metadata directory. Directories exported by this security model cannot 2558interact with other unix tools. "none" security model is same as 2559passthrough except the sever won't report failures if it fails to 2560set file attributes like ownership. Security model is mandatory 2561only for local fsdriver. Other fsdrivers (like proxy) don't take 2562security model as a parameter. 2563@item writeout=@var{writeout} 2564This is an optional argument. The only supported value is "immediate". 2565This means that host page cache will be used to read and write data but 2566write notification will be sent to the guest only when the data has been 2567reported as written by the storage subsystem. 2568@item readonly 2569Enables exporting 9p share as a readonly mount for guests. By default 2570read-write access is given. 2571@item socket=@var{socket} 2572Enables proxy filesystem driver to use passed socket file for communicating 2573with virtfs-proxy-helper(1). 2574@item sock_fd=@var{sock_fd} 2575Enables proxy filesystem driver to use passed socket descriptor for 2576communicating with virtfs-proxy-helper(1). Usually a helper like libvirt 2577will create socketpair and pass one of the fds as sock_fd. 2578@item fmode=@var{fmode} 2579Specifies the default mode for newly created files on the host. Works only 2580with security models "mapped-xattr" and "mapped-file". 2581@item dmode=@var{dmode} 2582Specifies the default mode for newly created directories on the host. Works 2583only with security models "mapped-xattr" and "mapped-file". 2584@item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w} 2585Specify bandwidth throttling limits in bytes per second, either for all request 2586types or for reads or writes only. 2587@item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm} 2588Specify bursts in bytes per second, either for all request types or for reads 2589or writes only. Bursts allow the guest I/O to spike above the limit 2590temporarily. 2591@item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w} 2592Specify request rate limits in requests per second, either for all request 2593types or for reads or writes only. 2594@item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm} 2595Specify bursts in requests per second, either for all request types or for reads 2596or writes only. Bursts allow the guest I/O to spike above the limit temporarily. 2597@item throttling.iops-size=@var{is} 2598Let every @var{is} bytes of a request count as a new request for iops 2599throttling purposes. 2600@end table 2601 2602-fsdev option is used along with -device driver "virtio-9p-...". 2603@item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag} 2604Options for virtio-9p-... driver are: 2605@table @option 2606@item @var{type} 2607Specifies the variant to be used. Supported values are "pci", "ccw" or "device", 2608depending on the machine type. 2609@item fsdev=@var{id} 2610Specifies the id value specified along with -fsdev option. 2611@item mount_tag=@var{mount_tag} 2612Specifies the tag name to be used by the guest to mount this export point. 2613@end table 2614 2615ETEXI 2616SRST 2617``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]`` 2618 \ 2619``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]`` 2620 \ 2621``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]`` 2622 \ 2623``-fsdev synth,id=id[,readonly]`` 2624 Define a new file system device. Valid options are: 2625 2626 ``local`` 2627 Accesses to the filesystem are done by QEMU. 2628 2629 ``proxy`` 2630 Accesses to the filesystem are done by virtfs-proxy-helper(1). 2631 2632 ``synth`` 2633 Synthetic filesystem, only used by QTests. 2634 2635 ``id=id`` 2636 Specifies identifier for this device. 2637 2638 ``path=path`` 2639 Specifies the export path for the file system device. Files 2640 under this path will be available to the 9p client on the guest. 2641 2642 ``security_model=security_model`` 2643 Specifies the security model to be used for this export path. 2644 Supported security models are "passthrough", "mapped-xattr", 2645 "mapped-file" and "none". In "passthrough" security model, files 2646 are stored using the same credentials as they are created on the 2647 guest. This requires QEMU to run as root. In "mapped-xattr" 2648 security model, some of the file attributes like uid, gid, mode 2649 bits and link target are stored as file attributes. For 2650 "mapped-file" these attributes are stored in the hidden 2651 .virtfs\_metadata directory. Directories exported by this 2652 security model cannot interact with other unix tools. "none" 2653 security model is same as passthrough except the sever won't 2654 report failures if it fails to set file attributes like 2655 ownership. Security model is mandatory only for local fsdriver. 2656 Other fsdrivers (like proxy) don't take security model as a 2657 parameter. 2658 2659 ``writeout=writeout`` 2660 This is an optional argument. The only supported value is 2661 "immediate". This means that host page cache will be used to 2662 read and write data but write notification will be sent to the 2663 guest only when the data has been reported as written by the 2664 storage subsystem. 2665 2666 ``readonly`` 2667 Enables exporting 9p share as a readonly mount for guests. By 2668 default read-write access is given. 2669 2670 ``socket=socket`` 2671 Enables proxy filesystem driver to use passed socket file for 2672 communicating with virtfs-proxy-helper(1). 2673 2674 ``sock_fd=sock_fd`` 2675 Enables proxy filesystem driver to use passed socket descriptor 2676 for communicating with virtfs-proxy-helper(1). Usually a helper 2677 like libvirt will create socketpair and pass one of the fds as 2678 sock\_fd. 2679 2680 ``fmode=fmode`` 2681 Specifies the default mode for newly created files on the host. 2682 Works only with security models "mapped-xattr" and 2683 "mapped-file". 2684 2685 ``dmode=dmode`` 2686 Specifies the default mode for newly created directories on the 2687 host. Works only with security models "mapped-xattr" and 2688 "mapped-file". 2689 2690 ``throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w`` 2691 Specify bandwidth throttling limits in bytes per second, either 2692 for all request types or for reads or writes only. 2693 2694 ``throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm`` 2695 Specify bursts in bytes per second, either for all request types 2696 or for reads or writes only. Bursts allow the guest I/O to spike 2697 above the limit temporarily. 2698 2699 ``throttling.iops-total=i,throttling.iops-read=r, throttling.iops-write=w`` 2700 Specify request rate limits in requests per second, either for 2701 all request types or for reads or writes only. 2702 2703 ``throttling.iops-total-max=im,throttling.iops-read-max=irm, throttling.iops-write-max=iwm`` 2704 Specify bursts in requests per second, either for all request 2705 types or for reads or writes only. Bursts allow the guest I/O to 2706 spike above the limit temporarily. 2707 2708 ``throttling.iops-size=is`` 2709 Let every is bytes of a request count as a new request for iops 2710 throttling purposes. 2711 2712 -fsdev option is used along with -device driver "virtio-9p-...". 2713 2714``-device virtio-9p-type,fsdev=id,mount_tag=mount_tag`` 2715 Options for virtio-9p-... driver are: 2716 2717 ``type`` 2718 Specifies the variant to be used. Supported values are "pci", 2719 "ccw" or "device", depending on the machine type. 2720 2721 ``fsdev=id`` 2722 Specifies the id value specified along with -fsdev option. 2723 2724 ``mount_tag=mount_tag`` 2725 Specifies the tag name to be used by the guest to mount this 2726 export point. 2727ERST 2728 2729DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 2730 "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n" 2731 " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n" 2732 "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n" 2733 "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n" 2734 "-virtfs synth,mount_tag=tag[,id=id][,readonly]\n", 2735 QEMU_ARCH_ALL) 2736 2737STEXI 2738 2739@item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}][,multidevs=@var{multidevs}] 2740@itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 2741@itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly] 2742@itemx -virtfs synth,mount_tag=@var{mount_tag} 2743@findex -virtfs 2744 2745Define a new filesystem device and expose it to the guest using a virtio-9p-device. The general form of a Virtual File system pass-through options are: 2746@table @option 2747@item local 2748Accesses to the filesystem are done by QEMU. 2749@item proxy 2750Accesses to the filesystem are done by virtfs-proxy-helper(1). 2751@item synth 2752Synthetic filesystem, only used by QTests. 2753@item id=@var{id} 2754Specifies identifier for the filesystem device 2755@item path=@var{path} 2756Specifies the export path for the file system device. Files under 2757this path will be available to the 9p client on the guest. 2758@item security_model=@var{security_model} 2759Specifies the security model to be used for this export path. 2760Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 2761In "passthrough" security model, files are stored using the same 2762credentials as they are created on the guest. This requires QEMU 2763to run as root. In "mapped-xattr" security model, some of the file 2764attributes like uid, gid, mode bits and link target are stored as 2765file attributes. For "mapped-file" these attributes are stored in the 2766hidden .virtfs_metadata directory. Directories exported by this security model cannot 2767interact with other unix tools. "none" security model is same as 2768passthrough except the sever won't report failures if it fails to 2769set file attributes like ownership. Security model is mandatory only 2770for local fsdriver. Other fsdrivers (like proxy) don't take security 2771model as a parameter. 2772@item writeout=@var{writeout} 2773This is an optional argument. The only supported value is "immediate". 2774This means that host page cache will be used to read and write data but 2775write notification will be sent to the guest only when the data has been 2776reported as written by the storage subsystem. 2777@item readonly 2778Enables exporting 9p share as a readonly mount for guests. By default 2779read-write access is given. 2780@item socket=@var{socket} 2781Enables proxy filesystem driver to use passed socket file for 2782communicating with virtfs-proxy-helper(1). Usually a helper like libvirt 2783will create socketpair and pass one of the fds as sock_fd. 2784@item sock_fd 2785Enables proxy filesystem driver to use passed 'sock_fd' as the socket 2786descriptor for interfacing with virtfs-proxy-helper(1). 2787@item fmode=@var{fmode} 2788Specifies the default mode for newly created files on the host. Works only 2789with security models "mapped-xattr" and "mapped-file". 2790@item dmode=@var{dmode} 2791Specifies the default mode for newly created directories on the host. Works 2792only with security models "mapped-xattr" and "mapped-file". 2793@item mount_tag=@var{mount_tag} 2794Specifies the tag name to be used by the guest to mount this export point. 2795@item multidevs=@var{multidevs} 2796Specifies how to deal with multiple devices being shared with a 9p export. 2797Supported behaviours are either "remap", "forbid" or "warn". The latter is 2798the default behaviour on which virtfs 9p expects only one device to be 2799shared with the same export, and if more than one device is shared and 2800accessed via the same 9p export then only a warning message is logged 2801(once) by qemu on host side. In order to avoid file ID collisions on guest 2802you should either create a separate virtfs export for each device to be 2803shared with guests (recommended way) or you might use "remap" instead which 2804allows you to share multiple devices with only one export instead, which is 2805achieved by remapping the original inode numbers from host to guest in a 2806way that would prevent such collisions. Remapping inodes in such use cases 2807is required because the original device IDs from host are never passed and 2808exposed on guest. Instead all files of an export shared with virtfs always 2809share the same device id on guest. So two files with identical inode 2810numbers but from actually different devices on host would otherwise cause a 2811file ID collision and hence potential misbehaviours on guest. "forbid" on 2812the other hand assumes like "warn" that only one device is shared by the 2813same export, however it will not only log a warning message but also 2814deny access to additional devices on guest. Note though that "forbid" does 2815currently not block all possible file access operations (e.g. readdir() 2816would still return entries from other devices). 2817@end table 2818ETEXI 2819SRST 2820``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]`` 2821 \ 2822``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly]`` 2823 \ 2824``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly]`` 2825 \ 2826``-virtfs synth,mount_tag=mount_tag`` 2827 Define a new filesystem device and expose it to the guest using a 2828 virtio-9p-device. The general form of a Virtual File system 2829 pass-through options are: 2830 2831 ``local`` 2832 Accesses to the filesystem are done by QEMU. 2833 2834 ``proxy`` 2835 Accesses to the filesystem are done by virtfs-proxy-helper(1). 2836 2837 ``synth`` 2838 Synthetic filesystem, only used by QTests. 2839 2840 ``id=id`` 2841 Specifies identifier for the filesystem device 2842 2843 ``path=path`` 2844 Specifies the export path for the file system device. Files 2845 under this path will be available to the 9p client on the guest. 2846 2847 ``security_model=security_model`` 2848 Specifies the security model to be used for this export path. 2849 Supported security models are "passthrough", "mapped-xattr", 2850 "mapped-file" and "none". In "passthrough" security model, files 2851 are stored using the same credentials as they are created on the 2852 guest. This requires QEMU to run as root. In "mapped-xattr" 2853 security model, some of the file attributes like uid, gid, mode 2854 bits and link target are stored as file attributes. For 2855 "mapped-file" these attributes are stored in the hidden 2856 .virtfs\_metadata directory. Directories exported by this 2857 security model cannot interact with other unix tools. "none" 2858 security model is same as passthrough except the sever won't 2859 report failures if it fails to set file attributes like 2860 ownership. Security model is mandatory only for local fsdriver. 2861 Other fsdrivers (like proxy) don't take security model as a 2862 parameter. 2863 2864 ``writeout=writeout`` 2865 This is an optional argument. The only supported value is 2866 "immediate". This means that host page cache will be used to 2867 read and write data but write notification will be sent to the 2868 guest only when the data has been reported as written by the 2869 storage subsystem. 2870 2871 ``readonly`` 2872 Enables exporting 9p share as a readonly mount for guests. By 2873 default read-write access is given. 2874 2875 ``socket=socket`` 2876 Enables proxy filesystem driver to use passed socket file for 2877 communicating with virtfs-proxy-helper(1). Usually a helper like 2878 libvirt will create socketpair and pass one of the fds as 2879 sock\_fd. 2880 2881 ``sock_fd`` 2882 Enables proxy filesystem driver to use passed 'sock\_fd' as the 2883 socket descriptor for interfacing with virtfs-proxy-helper(1). 2884 2885 ``fmode=fmode`` 2886 Specifies the default mode for newly created files on the host. 2887 Works only with security models "mapped-xattr" and 2888 "mapped-file". 2889 2890 ``dmode=dmode`` 2891 Specifies the default mode for newly created directories on the 2892 host. Works only with security models "mapped-xattr" and 2893 "mapped-file". 2894 2895 ``mount_tag=mount_tag`` 2896 Specifies the tag name to be used by the guest to mount this 2897 export point. 2898 2899 ``multidevs=multidevs`` 2900 Specifies how to deal with multiple devices being shared with a 2901 9p export. Supported behaviours are either "remap", "forbid" or 2902 "warn". The latter is the default behaviour on which virtfs 9p 2903 expects only one device to be shared with the same export, and 2904 if more than one device is shared and accessed via the same 9p 2905 export then only a warning message is logged (once) by qemu on 2906 host side. In order to avoid file ID collisions on guest you 2907 should either create a separate virtfs export for each device to 2908 be shared with guests (recommended way) or you might use "remap" 2909 instead which allows you to share multiple devices with only one 2910 export instead, which is achieved by remapping the original 2911 inode numbers from host to guest in a way that would prevent 2912 such collisions. Remapping inodes in such use cases is required 2913 because the original device IDs from host are never passed and 2914 exposed on guest. Instead all files of an export shared with 2915 virtfs always share the same device id on guest. So two files 2916 with identical inode numbers but from actually different devices 2917 on host would otherwise cause a file ID collision and hence 2918 potential misbehaviours on guest. "forbid" on the other hand 2919 assumes like "warn" that only one device is shared by the same 2920 export, however it will not only log a warning message but also 2921 deny access to additional devices on guest. Note though that 2922 "forbid" does currently not block all possible file access 2923 operations (e.g. readdir() would still return entries from other 2924 devices). 2925ERST 2926 2927DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2928 "-iscsi [user=user][,password=password]\n" 2929 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 2930 " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 2931 " [,timeout=timeout]\n" 2932 " iSCSI session parameters\n", QEMU_ARCH_ALL) 2933 2934STEXI 2935@item -iscsi 2936@findex -iscsi 2937Configure iSCSI session parameters. 2938ETEXI 2939SRST 2940``-iscsi`` 2941 Configure iSCSI session parameters. 2942ERST 2943 2944STEXI 2945@end table 2946ETEXI 2947DEFHEADING() 2948 2949DEFHEADING(USB options:) 2950STEXI 2951@table @option 2952ETEXI 2953 2954DEF("usb", 0, QEMU_OPTION_usb, 2955 "-usb enable on-board USB host controller (if not enabled by default)\n", 2956 QEMU_ARCH_ALL) 2957STEXI 2958@item -usb 2959@findex -usb 2960Enable USB emulation on machine types with an on-board USB host controller (if 2961not enabled by default). Note that on-board USB host controllers may not 2962support USB 3.0. In this case @option{-device qemu-xhci} can be used instead 2963on machines with PCI. 2964ETEXI 2965SRST 2966``-usb`` 2967 Enable USB emulation on machine types with an on-board USB host 2968 controller (if not enabled by default). Note that on-board USB host 2969 controllers may not support USB 3.0. In this case 2970 ``-device qemu-xhci`` can be used instead on machines with PCI. 2971ERST 2972 2973DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 2974 "-usbdevice name add the host or guest USB device 'name'\n", 2975 QEMU_ARCH_ALL) 2976STEXI 2977 2978@item -usbdevice @var{devname} 2979@findex -usbdevice 2980Add the USB device @var{devname}. Note that this option is deprecated, 2981please use @code{-device usb-...} instead. @xref{usb_devices}. 2982 2983@table @option 2984 2985@item mouse 2986Virtual Mouse. This will override the PS/2 mouse emulation when activated. 2987 2988@item tablet 2989Pointer device that uses absolute coordinates (like a touchscreen). This 2990means QEMU is able to report the mouse position without having to grab the 2991mouse. Also overrides the PS/2 mouse emulation when activated. 2992 2993@item braille 2994Braille device. This will use BrlAPI to display the braille output on a real 2995or fake device. 2996 2997@end table 2998ETEXI 2999SRST 3000``-usbdevice devname`` 3001 Add the USB device devname. Note that this option is deprecated, 3002 please use ``-device usb-...`` instead. See 3003 :ref:`usb_005fdevices`. 3004 3005 ``mouse`` 3006 Virtual Mouse. This will override the PS/2 mouse emulation when 3007 activated. 3008 3009 ``tablet`` 3010 Pointer device that uses absolute coordinates (like a 3011 touchscreen). This means QEMU is able to report the mouse 3012 position without having to grab the mouse. Also overrides the 3013 PS/2 mouse emulation when activated. 3014 3015 ``braille`` 3016 Braille device. This will use BrlAPI to display the braille 3017 output on a real or fake device. 3018ERST 3019 3020STEXI 3021@end table 3022ETEXI 3023DEFHEADING() 3024 3025DEFHEADING(Display options:) 3026STEXI 3027@table @option 3028ETEXI 3029 3030DEF("display", HAS_ARG, QEMU_OPTION_display, 3031#if defined(CONFIG_SPICE) 3032 "-display spice-app[,gl=on|off]\n" 3033#endif 3034#if defined(CONFIG_SDL) 3035 "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n" 3036 " [,window_close=on|off][,gl=on|core|es|off]\n" 3037#endif 3038#if defined(CONFIG_GTK) 3039 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 3040#endif 3041#if defined(CONFIG_VNC) 3042 "-display vnc=<display>[,<optargs>]\n" 3043#endif 3044#if defined(CONFIG_CURSES) 3045 "-display curses[,charset=<encoding>]\n" 3046#endif 3047#if defined(CONFIG_OPENGL) 3048 "-display egl-headless[,rendernode=<file>]\n" 3049#endif 3050 "-display none\n" 3051 " select display backend type\n" 3052 " The default display is equivalent to\n " 3053#if defined(CONFIG_GTK) 3054 "\"-display gtk\"\n" 3055#elif defined(CONFIG_SDL) 3056 "\"-display sdl\"\n" 3057#elif defined(CONFIG_COCOA) 3058 "\"-display cocoa\"\n" 3059#elif defined(CONFIG_VNC) 3060 "\"-vnc localhost:0,to=99,id=default\"\n" 3061#else 3062 "\"-display none\"\n" 3063#endif 3064 , QEMU_ARCH_ALL) 3065STEXI 3066@item -display @var{type} 3067@findex -display 3068Select type of display to use. This option is a replacement for the 3069old style -sdl/-curses/... options. Use @code{-display help} to list 3070the available display types. Valid values for @var{type} are 3071@table @option 3072@item sdl 3073Display video output via SDL (usually in a separate graphics 3074window; see the SDL documentation for other possibilities). 3075@item curses 3076Display video output via curses. For graphics device models which 3077support a text mode, QEMU can display this output using a 3078curses/ncurses interface. Nothing is displayed when the graphics 3079device is in graphical mode or if the graphics device does not support 3080a text mode. Generally only the VGA device models support text mode. 3081The font charset used by the guest can be specified with the 3082@code{charset} option, for example @code{charset=CP850} for IBM CP850 3083encoding. The default is @code{CP437}. 3084@item none 3085Do not display video output. The guest will still see an emulated 3086graphics card, but its output will not be displayed to the QEMU 3087user. This option differs from the -nographic option in that it 3088only affects what is done with video output; -nographic also changes 3089the destination of the serial and parallel port data. 3090@item gtk 3091Display video output in a GTK window. This interface provides drop-down 3092menus and other UI elements to configure and control the VM during 3093runtime. 3094@item vnc 3095Start a VNC server on display <arg> 3096@item egl-headless 3097Offload all OpenGL operations to a local DRI device. For any graphical display, 3098this display needs to be paired with either VNC or SPICE displays. 3099@item spice-app 3100Start QEMU as a Spice server and launch the default Spice client 3101application. The Spice server will redirect the serial consoles and 3102QEMU monitors. (Since 4.0) 3103@end table 3104ETEXI 3105SRST 3106``-display type`` 3107 Select type of display to use. This option is a replacement for the 3108 old style -sdl/-curses/... options. Use ``-display help`` to list 3109 the available display types. Valid values for type are 3110 3111 ``sdl`` 3112 Display video output via SDL (usually in a separate graphics 3113 window; see the SDL documentation for other possibilities). 3114 3115 ``curses`` 3116 Display video output via curses. For graphics device models 3117 which support a text mode, QEMU can display this output using a 3118 curses/ncurses interface. Nothing is displayed when the graphics 3119 device is in graphical mode or if the graphics device does not 3120 support a text mode. Generally only the VGA device models 3121 support text mode. The font charset used by the guest can be 3122 specified with the ``charset`` option, for example 3123 ``charset=CP850`` for IBM CP850 encoding. The default is 3124 ``CP437``. 3125 3126 ``none`` 3127 Do not display video output. The guest will still see an 3128 emulated graphics card, but its output will not be displayed to 3129 the QEMU user. This option differs from the -nographic option in 3130 that it only affects what is done with video output; -nographic 3131 also changes the destination of the serial and parallel port 3132 data. 3133 3134 ``gtk`` 3135 Display video output in a GTK window. This interface provides 3136 drop-down menus and other UI elements to configure and control 3137 the VM during runtime. 3138 3139 ``vnc`` 3140 Start a VNC server on display <arg> 3141 3142 ``egl-headless`` 3143 Offload all OpenGL operations to a local DRI device. For any 3144 graphical display, this display needs to be paired with either 3145 VNC or SPICE displays. 3146 3147 ``spice-app`` 3148 Start QEMU as a Spice server and launch the default Spice client 3149 application. The Spice server will redirect the serial consoles 3150 and QEMU monitors. (Since 4.0) 3151ERST 3152 3153DEF("nographic", 0, QEMU_OPTION_nographic, 3154 "-nographic disable graphical output and redirect serial I/Os to console\n", 3155 QEMU_ARCH_ALL) 3156STEXI 3157@item -nographic 3158@findex -nographic 3159Normally, if QEMU is compiled with graphical window support, it displays 3160output such as guest graphics, guest console, and the QEMU monitor in a 3161window. With this option, you can totally disable graphical output so 3162that QEMU is a simple command line application. The emulated serial port 3163is redirected on the console and muxed with the monitor (unless 3164redirected elsewhere explicitly). Therefore, you can still use QEMU to 3165debug a Linux kernel with a serial console. Use @key{C-a h} for help on 3166switching between the console and monitor. 3167ETEXI 3168SRST 3169``-nographic`` 3170 Normally, if QEMU is compiled with graphical window support, it 3171 displays output such as guest graphics, guest console, and the QEMU 3172 monitor in a window. With this option, you can totally disable 3173 graphical output so that QEMU is a simple command line application. 3174 The emulated serial port is redirected on the console and muxed with 3175 the monitor (unless redirected elsewhere explicitly). Therefore, you 3176 can still use QEMU to debug a Linux kernel with a serial console. 3177 Use C-a h for help on switching between the console and monitor. 3178ERST 3179 3180DEF("curses", 0, QEMU_OPTION_curses, 3181 "-curses shorthand for -display curses\n", 3182 QEMU_ARCH_ALL) 3183STEXI 3184@item -curses 3185@findex -curses 3186Normally, if QEMU is compiled with graphical window support, it displays 3187output such as guest graphics, guest console, and the QEMU monitor in a 3188window. With this option, QEMU can display the VGA output when in text 3189mode using a curses/ncurses interface. Nothing is displayed in graphical 3190mode. 3191ETEXI 3192SRST 3193``-curses`` 3194 Normally, if QEMU is compiled with graphical window support, it 3195 displays output such as guest graphics, guest console, and the QEMU 3196 monitor in a window. With this option, QEMU can display the VGA 3197 output when in text mode using a curses/ncurses interface. Nothing 3198 is displayed in graphical mode. 3199ERST 3200 3201DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 3202 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 3203 QEMU_ARCH_ALL) 3204STEXI 3205@item -alt-grab 3206@findex -alt-grab 3207Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 3208affects the special keys (for fullscreen, monitor-mode switching, etc). 3209ETEXI 3210SRST 3211``-alt-grab`` 3212 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that 3213 this also affects the special keys (for fullscreen, monitor-mode 3214 switching, etc). 3215ERST 3216 3217DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 3218 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 3219 QEMU_ARCH_ALL) 3220STEXI 3221@item -ctrl-grab 3222@findex -ctrl-grab 3223Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 3224affects the special keys (for fullscreen, monitor-mode switching, etc). 3225ETEXI 3226SRST 3227``-ctrl-grab`` 3228 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this 3229 also affects the special keys (for fullscreen, monitor-mode 3230 switching, etc). 3231ERST 3232 3233DEF("no-quit", 0, QEMU_OPTION_no_quit, 3234 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 3235STEXI 3236@item -no-quit 3237@findex -no-quit 3238Disable SDL window close capability. 3239ETEXI 3240SRST 3241``-no-quit`` 3242 Disable SDL window close capability. 3243ERST 3244 3245DEF("sdl", 0, QEMU_OPTION_sdl, 3246 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 3247STEXI 3248@item -sdl 3249@findex -sdl 3250Enable SDL. 3251ETEXI 3252SRST 3253``-sdl`` 3254 Enable SDL. 3255ERST 3256 3257DEF("spice", HAS_ARG, QEMU_OPTION_spice, 3258 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 3259 " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 3260 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 3261 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 3262 " [,tls-ciphers=<list>]\n" 3263 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 3264 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 3265 " [,sasl][,password=<secret>][,disable-ticketing]\n" 3266 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 3267 " [,jpeg-wan-compression=[auto|never|always]]\n" 3268 " [,zlib-glz-wan-compression=[auto|never|always]]\n" 3269 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 3270 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 3271 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 3272 " [,gl=[on|off]][,rendernode=<file>]\n" 3273 " enable spice\n" 3274 " at least one of {port, tls-port} is mandatory\n", 3275 QEMU_ARCH_ALL) 3276STEXI 3277@item -spice @var{option}[,@var{option}[,...]] 3278@findex -spice 3279Enable the spice remote desktop protocol. Valid options are 3280 3281@table @option 3282 3283@item port=<nr> 3284Set the TCP port spice is listening on for plaintext channels. 3285 3286@item addr=<addr> 3287Set the IP address spice is listening on. Default is any address. 3288 3289@item ipv4 3290@itemx ipv6 3291@itemx unix 3292Force using the specified IP version. 3293 3294@item password=<secret> 3295Set the password you need to authenticate. 3296 3297@item sasl 3298Require that the client use SASL to authenticate with the spice. 3299The exact choice of authentication method used is controlled from the 3300system / user's SASL configuration file for the 'qemu' service. This 3301is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 3302unprivileged user, an environment variable SASL_CONF_PATH can be used 3303to make it search alternate locations for the service config. 3304While some SASL auth methods can also provide data encryption (eg GSSAPI), 3305it is recommended that SASL always be combined with the 'tls' and 3306'x509' settings to enable use of SSL and server certificates. This 3307ensures a data encryption preventing compromise of authentication 3308credentials. 3309 3310@item disable-ticketing 3311Allow client connects without authentication. 3312 3313@item disable-copy-paste 3314Disable copy paste between the client and the guest. 3315 3316@item disable-agent-file-xfer 3317Disable spice-vdagent based file-xfer between the client and the guest. 3318 3319@item tls-port=<nr> 3320Set the TCP port spice is listening on for encrypted channels. 3321 3322@item x509-dir=<dir> 3323Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 3324 3325@item x509-key-file=<file> 3326@itemx x509-key-password=<file> 3327@itemx x509-cert-file=<file> 3328@itemx x509-cacert-file=<file> 3329@itemx x509-dh-key-file=<file> 3330The x509 file names can also be configured individually. 3331 3332@item tls-ciphers=<list> 3333Specify which ciphers to use. 3334 3335@item tls-channel=[main|display|cursor|inputs|record|playback] 3336@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 3337Force specific channel to be used with or without TLS encryption. The 3338options can be specified multiple times to configure multiple 3339channels. The special name "default" can be used to set the default 3340mode. For channels which are not explicitly forced into one mode the 3341spice client is allowed to pick tls/plaintext as he pleases. 3342 3343@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 3344Configure image compression (lossless). 3345Default is auto_glz. 3346 3347@item jpeg-wan-compression=[auto|never|always] 3348@itemx zlib-glz-wan-compression=[auto|never|always] 3349Configure wan image compression (lossy for slow links). 3350Default is auto. 3351 3352@item streaming-video=[off|all|filter] 3353Configure video stream detection. Default is off. 3354 3355@item agent-mouse=[on|off] 3356Enable/disable passing mouse events via vdagent. Default is on. 3357 3358@item playback-compression=[on|off] 3359Enable/disable audio stream compression (using celt 0.5.1). Default is on. 3360 3361@item seamless-migration=[on|off] 3362Enable/disable spice seamless migration. Default is off. 3363 3364@item gl=[on|off] 3365Enable/disable OpenGL context. Default is off. 3366 3367@item rendernode=<file> 3368DRM render node for OpenGL rendering. If not specified, it will pick 3369the first available. (Since 2.9) 3370 3371@end table 3372ETEXI 3373SRST 3374``-spice option[,option[,...]]`` 3375 Enable the spice remote desktop protocol. Valid options are 3376 3377 ``port=<nr>`` 3378 Set the TCP port spice is listening on for plaintext channels. 3379 3380 ``addr=<addr>`` 3381 Set the IP address spice is listening on. Default is any 3382 address. 3383 3384 ``ipv4``; \ ``ipv6``; \ ``unix`` 3385 Force using the specified IP version. 3386 3387 ``password=<secret>`` 3388 Set the password you need to authenticate. 3389 3390 ``sasl`` 3391 Require that the client use SASL to authenticate with the spice. 3392 The exact choice of authentication method used is controlled 3393 from the system / user's SASL configuration file for the 'qemu' 3394 service. This is typically found in /etc/sasl2/qemu.conf. If 3395 running QEMU as an unprivileged user, an environment variable 3396 SASL\_CONF\_PATH can be used to make it search alternate 3397 locations for the service config. While some SASL auth methods 3398 can also provide data encryption (eg GSSAPI), it is recommended 3399 that SASL always be combined with the 'tls' and 'x509' settings 3400 to enable use of SSL and server certificates. This ensures a 3401 data encryption preventing compromise of authentication 3402 credentials. 3403 3404 ``disable-ticketing`` 3405 Allow client connects without authentication. 3406 3407 ``disable-copy-paste`` 3408 Disable copy paste between the client and the guest. 3409 3410 ``disable-agent-file-xfer`` 3411 Disable spice-vdagent based file-xfer between the client and the 3412 guest. 3413 3414 ``tls-port=<nr>`` 3415 Set the TCP port spice is listening on for encrypted channels. 3416 3417 ``x509-dir=<dir>`` 3418 Set the x509 file directory. Expects same filenames as -vnc 3419 $display,x509=$dir 3420 3421 ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>`` 3422 The x509 file names can also be configured individually. 3423 3424 ``tls-ciphers=<list>`` 3425 Specify which ciphers to use. 3426 3427 ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]`` 3428 Force specific channel to be used with or without TLS 3429 encryption. The options can be specified multiple times to 3430 configure multiple channels. The special name "default" can be 3431 used to set the default mode. For channels which are not 3432 explicitly forced into one mode the spice client is allowed to 3433 pick tls/plaintext as he pleases. 3434 3435 ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]`` 3436 Configure image compression (lossless). Default is auto\_glz. 3437 3438 ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]`` 3439 Configure wan image compression (lossy for slow links). Default 3440 is auto. 3441 3442 ``streaming-video=[off|all|filter]`` 3443 Configure video stream detection. Default is off. 3444 3445 ``agent-mouse=[on|off]`` 3446 Enable/disable passing mouse events via vdagent. Default is on. 3447 3448 ``playback-compression=[on|off]`` 3449 Enable/disable audio stream compression (using celt 0.5.1). 3450 Default is on. 3451 3452 ``seamless-migration=[on|off]`` 3453 Enable/disable spice seamless migration. Default is off. 3454 3455 ``gl=[on|off]`` 3456 Enable/disable OpenGL context. Default is off. 3457 3458 ``rendernode=<file>`` 3459 DRM render node for OpenGL rendering. If not specified, it will 3460 pick the first available. (Since 2.9) 3461ERST 3462 3463DEF("portrait", 0, QEMU_OPTION_portrait, 3464 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 3465 QEMU_ARCH_ALL) 3466STEXI 3467@item -portrait 3468@findex -portrait 3469Rotate graphical output 90 deg left (only PXA LCD). 3470ETEXI 3471SRST 3472``-portrait`` 3473 Rotate graphical output 90 deg left (only PXA LCD). 3474ERST 3475 3476DEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 3477 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 3478 QEMU_ARCH_ALL) 3479STEXI 3480@item -rotate @var{deg} 3481@findex -rotate 3482Rotate graphical output some deg left (only PXA LCD). 3483ETEXI 3484SRST 3485``-rotate deg`` 3486 Rotate graphical output some deg left (only PXA LCD). 3487ERST 3488 3489DEF("vga", HAS_ARG, QEMU_OPTION_vga, 3490 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 3491 " select video card type\n", QEMU_ARCH_ALL) 3492STEXI 3493@item -vga @var{type} 3494@findex -vga 3495Select type of VGA card to emulate. Valid values for @var{type} are 3496@table @option 3497@item cirrus 3498Cirrus Logic GD5446 Video card. All Windows versions starting from 3499Windows 95 should recognize and use this graphic card. For optimal 3500performances, use 16 bit color depth in the guest and the host OS. 3501(This card was the default before QEMU 2.2) 3502@item std 3503Standard VGA card with Bochs VBE extensions. If your guest OS 3504supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 3505to use high resolution modes (>= 1280x1024x16) then you should use 3506this option. (This card is the default since QEMU 2.2) 3507@item vmware 3508VMWare SVGA-II compatible adapter. Use it if you have sufficiently 3509recent XFree86/XOrg server or Windows guest with a driver for this 3510card. 3511@item qxl 3512QXL paravirtual graphic card. It is VGA compatible (including VESA 35132.0 VBE support). Works best with qxl guest drivers installed though. 3514Recommended choice when using the spice protocol. 3515@item tcx 3516(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 3517sun4m machines and offers both 8-bit and 24-bit colour depths at a 3518fixed resolution of 1024x768. 3519@item cg3 3520(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 3521for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 3522resolutions aimed at people wishing to run older Solaris versions. 3523@item virtio 3524Virtio VGA card. 3525@item none 3526Disable VGA card. 3527@end table 3528ETEXI 3529SRST 3530``-vga type`` 3531 Select type of VGA card to emulate. Valid values for type are 3532 3533 ``cirrus`` 3534 Cirrus Logic GD5446 Video card. All Windows versions starting 3535 from Windows 95 should recognize and use this graphic card. For 3536 optimal performances, use 16 bit color depth in the guest and 3537 the host OS. (This card was the default before QEMU 2.2) 3538 3539 ``std`` 3540 Standard VGA card with Bochs VBE extensions. If your guest OS 3541 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if 3542 you want to use high resolution modes (>= 1280x1024x16) then you 3543 should use this option. (This card is the default since QEMU 3544 2.2) 3545 3546 ``vmware`` 3547 VMWare SVGA-II compatible adapter. Use it if you have 3548 sufficiently recent XFree86/XOrg server or Windows guest with a 3549 driver for this card. 3550 3551 ``qxl`` 3552 QXL paravirtual graphic card. It is VGA compatible (including 3553 VESA 2.0 VBE support). Works best with qxl guest drivers 3554 installed though. Recommended choice when using the spice 3555 protocol. 3556 3557 ``tcx`` 3558 (sun4m only) Sun TCX framebuffer. This is the default 3559 framebuffer for sun4m machines and offers both 8-bit and 24-bit 3560 colour depths at a fixed resolution of 1024x768. 3561 3562 ``cg3`` 3563 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit 3564 framebuffer for sun4m machines available in both 1024x768 3565 (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people 3566 wishing to run older Solaris versions. 3567 3568 ``virtio`` 3569 Virtio VGA card. 3570 3571 ``none`` 3572 Disable VGA card. 3573ERST 3574 3575DEF("full-screen", 0, QEMU_OPTION_full_screen, 3576 "-full-screen start in full screen\n", QEMU_ARCH_ALL) 3577STEXI 3578@item -full-screen 3579@findex -full-screen 3580Start in full screen. 3581ETEXI 3582SRST 3583``-full-screen`` 3584 Start in full screen. 3585ERST 3586 3587DEF("g", HAS_ARG, QEMU_OPTION_g , 3588 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 3589 QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K) 3590STEXI 3591@item -g @var{width}x@var{height}[x@var{depth}] 3592@findex -g 3593Set the initial graphical resolution and depth (PPC, SPARC only). 3594 3595For PPC the default is 800x600x32. 3596 3597For SPARC with the TCX graphics device, the default is 1024x768x8 with the 3598option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option 3599of 1152x900x8 for people who wish to use OBP. 3600 3601ETEXI 3602SRST 3603``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]`` 3604 Set the initial graphical resolution and depth (PPC, SPARC only). 3605 3606 For PPC the default is 800x600x32. 3607 3608 For SPARC with the TCX graphics device, the default is 1024x768x8 3609 with the option of 1024x768x24. For cgthree, the default is 3610 1024x768x8 with the option of 1152x900x8 for people who wish to use 3611 OBP. 3612ERST 3613 3614DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 3615 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 3616STEXI 3617@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 3618@findex -vnc 3619Normally, if QEMU is compiled with graphical window support, it displays 3620output such as guest graphics, guest console, and the QEMU monitor in a 3621window. With this option, you can have QEMU listen on VNC display 3622@var{display} and redirect the VGA display over the VNC session. It is 3623very useful to enable the usb tablet device when using this option 3624(option @option{-device usb-tablet}). When using the VNC display, you 3625must use the @option{-k} parameter to set the keyboard layout if you are 3626not using en-us. Valid syntax for the @var{display} is 3627 3628@table @option 3629 3630@item to=@var{L} 3631 3632With this option, QEMU will try next available VNC @var{display}s, until the 3633number @var{L}, if the origianlly defined "-vnc @var{display}" is not 3634available, e.g. port 5900+@var{display} is already used by another 3635application. By default, to=0. 3636 3637@item @var{host}:@var{d} 3638 3639TCP connections will only be allowed from @var{host} on display @var{d}. 3640By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 3641be omitted in which case the server will accept connections from any host. 3642 3643@item unix:@var{path} 3644 3645Connections will be allowed over UNIX domain sockets where @var{path} is the 3646location of a unix socket to listen for connections on. 3647 3648@item none 3649 3650VNC is initialized but not started. The monitor @code{change} command 3651can be used to later start the VNC server. 3652 3653@end table 3654 3655Following the @var{display} value there may be one or more @var{option} flags 3656separated by commas. Valid options are 3657 3658@table @option 3659 3660@item reverse 3661 3662Connect to a listening VNC client via a ``reverse'' connection. The 3663client is specified by the @var{display}. For reverse network 3664connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 3665is a TCP port number, not a display number. 3666 3667@item websocket 3668 3669Opens an additional TCP listening port dedicated to VNC Websocket connections. 3670If a bare @var{websocket} option is given, the Websocket port is 36715700+@var{display}. An alternative port can be specified with the 3672syntax @code{websocket}=@var{port}. 3673 3674If @var{host} is specified connections will only be allowed from this host. 3675It is possible to control the websocket listen address independently, using 3676the syntax @code{websocket}=@var{host}:@var{port}. 3677 3678If no TLS credentials are provided, the websocket connection runs in 3679unencrypted mode. If TLS credentials are provided, the websocket connection 3680requires encrypted client connections. 3681 3682@item password 3683 3684Require that password based authentication is used for client connections. 3685 3686The password must be set separately using the @code{set_password} command in 3687the @ref{pcsys_monitor}. The syntax to change your password is: 3688@code{set_password <protocol> <password>} where <protocol> could be either 3689"vnc" or "spice". 3690 3691If you would like to change <protocol> password expiration, you should use 3692@code{expire_password <protocol> <expiration-time>} where expiration time could 3693be one of the following options: now, never, +seconds or UNIX time of 3694expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 3695to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 3696date and time). 3697 3698You can also use keywords "now" or "never" for the expiration time to 3699allow <protocol> password to expire immediately or never expire. 3700 3701@item tls-creds=@var{ID} 3702 3703Provides the ID of a set of TLS credentials to use to secure the 3704VNC server. They will apply to both the normal VNC server socket 3705and the websocket socket (if enabled). Setting TLS credentials 3706will cause the VNC server socket to enable the VeNCrypt auth 3707mechanism. The credentials should have been previously created 3708using the @option{-object tls-creds} argument. 3709 3710@item tls-authz=@var{ID} 3711 3712Provides the ID of the QAuthZ authorization object against which 3713the client's x509 distinguished name will validated. This object is 3714only resolved at time of use, so can be deleted and recreated on the 3715fly while the VNC server is active. If missing, it will default 3716to denying access. 3717 3718@item sasl 3719 3720Require that the client use SASL to authenticate with the VNC server. 3721The exact choice of authentication method used is controlled from the 3722system / user's SASL configuration file for the 'qemu' service. This 3723is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 3724unprivileged user, an environment variable SASL_CONF_PATH can be used 3725to make it search alternate locations for the service config. 3726While some SASL auth methods can also provide data encryption (eg GSSAPI), 3727it is recommended that SASL always be combined with the 'tls' and 3728'x509' settings to enable use of SSL and server certificates. This 3729ensures a data encryption preventing compromise of authentication 3730credentials. See the @ref{vnc_security} section for details on using 3731SASL authentication. 3732 3733@item sasl-authz=@var{ID} 3734 3735Provides the ID of the QAuthZ authorization object against which 3736the client's SASL username will validated. This object is 3737only resolved at time of use, so can be deleted and recreated on the 3738fly while the VNC server is active. If missing, it will default 3739to denying access. 3740 3741@item acl 3742 3743Legacy method for enabling authorization of clients against the 3744x509 distinguished name and SASL username. It results in the creation 3745of two @code{authz-list} objects with IDs of @code{vnc.username} and 3746@code{vnc.x509dname}. The rules for these objects must be configured 3747with the HMP ACL commands. 3748 3749This option is deprecated and should no longer be used. The new 3750@option{sasl-authz} and @option{tls-authz} options are a 3751replacement. 3752 3753@item lossy 3754 3755Enable lossy compression methods (gradient, JPEG, ...). If this 3756option is set, VNC client may receive lossy framebuffer updates 3757depending on its encoding settings. Enabling this option can save 3758a lot of bandwidth at the expense of quality. 3759 3760@item non-adaptive 3761 3762Disable adaptive encodings. Adaptive encodings are enabled by default. 3763An adaptive encoding will try to detect frequently updated screen regions, 3764and send updates in these regions using a lossy encoding (like JPEG). 3765This can be really helpful to save bandwidth when playing videos. Disabling 3766adaptive encodings restores the original static behavior of encodings 3767like Tight. 3768 3769@item share=[allow-exclusive|force-shared|ignore] 3770 3771Set display sharing policy. 'allow-exclusive' allows clients to ask 3772for exclusive access. As suggested by the rfb spec this is 3773implemented by dropping other connections. Connecting multiple 3774clients in parallel requires all clients asking for a shared session 3775(vncviewer: -shared switch). This is the default. 'force-shared' 3776disables exclusive client access. Useful for shared desktop sessions, 3777where you don't want someone forgetting specify -shared disconnect 3778everybody else. 'ignore' completely ignores the shared flag and 3779allows everybody connect unconditionally. Doesn't conform to the rfb 3780spec but is traditional QEMU behavior. 3781 3782@item key-delay-ms 3783 3784Set keyboard delay, for key down and key up events, in milliseconds. 3785Default is 10. Keyboards are low-bandwidth devices, so this slowdown 3786can help the device and guest to keep up and not lose events in case 3787events are arriving in bulk. Possible causes for the latter are flaky 3788network connections, or scripts for automated testing. 3789 3790@item audiodev=@var{audiodev} 3791 3792Use the specified @var{audiodev} when the VNC client requests audio 3793transmission. When not using an -audiodev argument, this option must 3794be omitted, otherwise is must be present and specify a valid audiodev. 3795 3796@end table 3797ETEXI 3798SRST 3799``-vnc display[,option[,option[,...]]]`` 3800 Normally, if QEMU is compiled with graphical window support, it 3801 displays output such as guest graphics, guest console, and the QEMU 3802 monitor in a window. With this option, you can have QEMU listen on 3803 VNC display display and redirect the VGA display over the VNC 3804 session. It is very useful to enable the usb tablet device when 3805 using this option (option ``-device usb-tablet``). When using the 3806 VNC display, you must use the ``-k`` parameter to set the keyboard 3807 layout if you are not using en-us. Valid syntax for the display is 3808 3809 ``to=L`` 3810 With this option, QEMU will try next available VNC displays, 3811 until the number L, if the origianlly defined "-vnc display" is 3812 not available, e.g. port 5900+display is already used by another 3813 application. By default, to=0. 3814 3815 ``host:d`` 3816 TCP connections will only be allowed from host on display d. By 3817 convention the TCP port is 5900+d. Optionally, host can be 3818 omitted in which case the server will accept connections from 3819 any host. 3820 3821 ``unix:path`` 3822 Connections will be allowed over UNIX domain sockets where path 3823 is the location of a unix socket to listen for connections on. 3824 3825 ``none`` 3826 VNC is initialized but not started. The monitor ``change`` 3827 command can be used to later start the VNC server. 3828 3829 Following the display value there may be one or more option flags 3830 separated by commas. Valid options are 3831 3832 ``reverse`` 3833 Connect to a listening VNC client via a "reverse" connection. 3834 The client is specified by the display. For reverse network 3835 connections (host:d,``reverse``), the d argument is a TCP port 3836 number, not a display number. 3837 3838 ``websocket`` 3839 Opens an additional TCP listening port dedicated to VNC 3840 Websocket connections. If a bare websocket option is given, the 3841 Websocket port is 5700+display. An alternative port can be 3842 specified with the syntax ``websocket``\ =port. 3843 3844 If host is specified connections will only be allowed from this 3845 host. It is possible to control the websocket listen address 3846 independently, using the syntax ``websocket``\ =host:port. 3847 3848 If no TLS credentials are provided, the websocket connection 3849 runs in unencrypted mode. If TLS credentials are provided, the 3850 websocket connection requires encrypted client connections. 3851 3852 ``password`` 3853 Require that password based authentication is used for client 3854 connections. 3855 3856 The password must be set separately using the ``set_password`` 3857 command in the :ref:`pcsys_005fmonitor`. The 3858 syntax to change your password is: 3859 ``set_password <protocol> <password>`` where <protocol> could be 3860 either "vnc" or "spice". 3861 3862 If you would like to change <protocol> password expiration, you 3863 should use ``expire_password <protocol> <expiration-time>`` 3864 where expiration time could be one of the following options: 3865 now, never, +seconds or UNIX time of expiration, e.g. +60 to 3866 make password expire in 60 seconds, or 1335196800 to make 3867 password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for 3868 this date and time). 3869 3870 You can also use keywords "now" or "never" for the expiration 3871 time to allow <protocol> password to expire immediately or never 3872 expire. 3873 3874 ``tls-creds=ID`` 3875 Provides the ID of a set of TLS credentials to use to secure the 3876 VNC server. They will apply to both the normal VNC server socket 3877 and the websocket socket (if enabled). Setting TLS credentials 3878 will cause the VNC server socket to enable the VeNCrypt auth 3879 mechanism. The credentials should have been previously created 3880 using the ``-object tls-creds`` argument. 3881 3882 ``tls-authz=ID`` 3883 Provides the ID of the QAuthZ authorization object against which 3884 the client's x509 distinguished name will validated. This object 3885 is only resolved at time of use, so can be deleted and recreated 3886 on the fly while the VNC server is active. If missing, it will 3887 default to denying access. 3888 3889 ``sasl`` 3890 Require that the client use SASL to authenticate with the VNC 3891 server. The exact choice of authentication method used is 3892 controlled from the system / user's SASL configuration file for 3893 the 'qemu' service. This is typically found in 3894 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user, 3895 an environment variable SASL\_CONF\_PATH can be used to make it 3896 search alternate locations for the service config. While some 3897 SASL auth methods can also provide data encryption (eg GSSAPI), 3898 it is recommended that SASL always be combined with the 'tls' 3899 and 'x509' settings to enable use of SSL and server 3900 certificates. This ensures a data encryption preventing 3901 compromise of authentication credentials. See the 3902 :ref:`vnc_005fsecurity` section for details on 3903 using SASL authentication. 3904 3905 ``sasl-authz=ID`` 3906 Provides the ID of the QAuthZ authorization object against which 3907 the client's SASL username will validated. This object is only 3908 resolved at time of use, so can be deleted and recreated on the 3909 fly while the VNC server is active. If missing, it will default 3910 to denying access. 3911 3912 ``acl`` 3913 Legacy method for enabling authorization of clients against the 3914 x509 distinguished name and SASL username. It results in the 3915 creation of two ``authz-list`` objects with IDs of 3916 ``vnc.username`` and ``vnc.x509dname``. The rules for these 3917 objects must be configured with the HMP ACL commands. 3918 3919 This option is deprecated and should no longer be used. The new 3920 ``sasl-authz`` and ``tls-authz`` options are a replacement. 3921 3922 ``lossy`` 3923 Enable lossy compression methods (gradient, JPEG, ...). If this 3924 option is set, VNC client may receive lossy framebuffer updates 3925 depending on its encoding settings. Enabling this option can 3926 save a lot of bandwidth at the expense of quality. 3927 3928 ``non-adaptive`` 3929 Disable adaptive encodings. Adaptive encodings are enabled by 3930 default. An adaptive encoding will try to detect frequently 3931 updated screen regions, and send updates in these regions using 3932 a lossy encoding (like JPEG). This can be really helpful to save 3933 bandwidth when playing videos. Disabling adaptive encodings 3934 restores the original static behavior of encodings like Tight. 3935 3936 ``share=[allow-exclusive|force-shared|ignore]`` 3937 Set display sharing policy. 'allow-exclusive' allows clients to 3938 ask for exclusive access. As suggested by the rfb spec this is 3939 implemented by dropping other connections. Connecting multiple 3940 clients in parallel requires all clients asking for a shared 3941 session (vncviewer: -shared switch). This is the default. 3942 'force-shared' disables exclusive client access. Useful for 3943 shared desktop sessions, where you don't want someone forgetting 3944 specify -shared disconnect everybody else. 'ignore' completely 3945 ignores the shared flag and allows everybody connect 3946 unconditionally. Doesn't conform to the rfb spec but is 3947 traditional QEMU behavior. 3948 3949 ``key-delay-ms`` 3950 Set keyboard delay, for key down and key up events, in 3951 milliseconds. Default is 10. Keyboards are low-bandwidth 3952 devices, so this slowdown can help the device and guest to keep 3953 up and not lose events in case events are arriving in bulk. 3954 Possible causes for the latter are flaky network connections, or 3955 scripts for automated testing. 3956 3957 ``audiodev=audiodev`` 3958 Use the specified audiodev when the VNC client requests audio 3959 transmission. When not using an -audiodev argument, this option 3960 must be omitted, otherwise is must be present and specify a 3961 valid audiodev. 3962ERST 3963 3964STEXI 3965@end table 3966ETEXI 3967ARCHHEADING(, QEMU_ARCH_I386) 3968 3969ARCHHEADING(i386 target only:, QEMU_ARCH_I386) 3970STEXI 3971@table @option 3972ETEXI 3973 3974DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 3975 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 3976 QEMU_ARCH_I386) 3977STEXI 3978@item -win2k-hack 3979@findex -win2k-hack 3980Use it when installing Windows 2000 to avoid a disk full bug. After 3981Windows 2000 is installed, you no longer need this option (this option 3982slows down the IDE transfers). 3983ETEXI 3984SRST 3985``-win2k-hack`` 3986 Use it when installing Windows 2000 to avoid a disk full bug. After 3987 Windows 2000 is installed, you no longer need this option (this 3988 option slows down the IDE transfers). 3989ERST 3990 3991DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 3992 "-no-fd-bootchk disable boot signature checking for floppy disks\n", 3993 QEMU_ARCH_I386) 3994STEXI 3995@item -no-fd-bootchk 3996@findex -no-fd-bootchk 3997Disable boot signature checking for floppy disks in BIOS. May 3998be needed to boot from old floppy disks. 3999ETEXI 4000SRST 4001``-no-fd-bootchk`` 4002 Disable boot signature checking for floppy disks in BIOS. May be 4003 needed to boot from old floppy disks. 4004ERST 4005 4006DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 4007 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 4008STEXI 4009@item -no-acpi 4010@findex -no-acpi 4011Disable ACPI (Advanced Configuration and Power Interface) support. Use 4012it if your guest OS complains about ACPI problems (PC target machine 4013only). 4014ETEXI 4015SRST 4016``-no-acpi`` 4017 Disable ACPI (Advanced Configuration and Power Interface) support. 4018 Use it if your guest OS complains about ACPI problems (PC target 4019 machine only). 4020ERST 4021 4022DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 4023 "-no-hpet disable HPET\n", QEMU_ARCH_I386) 4024STEXI 4025@item -no-hpet 4026@findex -no-hpet 4027Disable HPET support. 4028ETEXI 4029SRST 4030``-no-hpet`` 4031 Disable HPET support. 4032ERST 4033 4034DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 4035 "-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" 4036 " ACPI table description\n", QEMU_ARCH_I386) 4037STEXI 4038@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}]...] 4039@findex -acpitable 4040Add ACPI table with specified header fields and context from specified files. 4041For file=, take whole ACPI table from the specified files, including all 4042ACPI headers (possible overridden by other options). 4043For data=, only data 4044portion of the table is used, all header information is specified in the 4045command line. 4046If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 4047fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 4048to ensure the field matches required by the Microsoft SLIC spec and the ACPI 4049spec. 4050ETEXI 4051SRST 4052``-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n] [,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]`` 4053 Add ACPI table with specified header fields and context from 4054 specified files. For file=, take whole ACPI table from the specified 4055 files, including all ACPI headers (possible overridden by other 4056 options). For data=, only data portion of the table is used, all 4057 header information is specified in the command line. If a SLIC table 4058 is supplied to QEMU, then the SLIC's oem\_id and oem\_table\_id 4059 fields will override the same in the RSDT and the FADT (a.k.a. 4060 FACP), in order to ensure the field matches required by the 4061 Microsoft SLIC spec and the ACPI spec. 4062ERST 4063 4064DEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 4065 "-smbios file=binary\n" 4066 " load SMBIOS entry from binary file\n" 4067 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 4068 " [,uefi=on|off]\n" 4069 " specify SMBIOS type 0 fields\n" 4070 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 4071 " [,uuid=uuid][,sku=str][,family=str]\n" 4072 " specify SMBIOS type 1 fields\n" 4073 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 4074 " [,asset=str][,location=str]\n" 4075 " specify SMBIOS type 2 fields\n" 4076 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 4077 " [,sku=str]\n" 4078 " specify SMBIOS type 3 fields\n" 4079 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 4080 " [,asset=str][,part=str]\n" 4081 " specify SMBIOS type 4 fields\n" 4082 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 4083 " [,asset=str][,part=str][,speed=%d]\n" 4084 " specify SMBIOS type 17 fields\n", 4085 QEMU_ARCH_I386 | QEMU_ARCH_ARM) 4086STEXI 4087@item -smbios file=@var{binary} 4088@findex -smbios 4089Load SMBIOS entry from binary file. 4090 4091@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 4092Specify SMBIOS type 0 fields 4093 4094@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}] 4095Specify SMBIOS type 1 fields 4096 4097@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}] 4098Specify SMBIOS type 2 fields 4099 4100@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 4101Specify SMBIOS type 3 fields 4102 4103@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}] 4104Specify SMBIOS type 4 fields 4105 4106@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}] 4107Specify SMBIOS type 17 fields 4108ETEXI 4109SRST 4110``-smbios file=binary`` 4111 Load SMBIOS entry from binary file. 4112 4113``-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]`` 4114 Specify SMBIOS type 0 fields 4115 4116``-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]`` 4117 Specify SMBIOS type 1 fields 4118 4119``-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]`` 4120 Specify SMBIOS type 2 fields 4121 4122``-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]`` 4123 Specify SMBIOS type 3 fields 4124 4125``-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str]`` 4126 Specify SMBIOS type 4 fields 4127 4128``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]`` 4129 Specify SMBIOS type 17 fields 4130ERST 4131 4132STEXI 4133@end table 4134ETEXI 4135DEFHEADING() 4136 4137DEFHEADING(Network options:) 4138STEXI 4139@table @option 4140ETEXI 4141 4142DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 4143#ifdef CONFIG_SLIRP 4144 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 4145 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 4146 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 4147 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 4148 " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 4149#ifndef _WIN32 4150 "[,smb=dir[,smbserver=addr]]\n" 4151#endif 4152 " configure a user mode network backend with ID 'str',\n" 4153 " its DHCP server and optional services\n" 4154#endif 4155#ifdef _WIN32 4156 "-netdev tap,id=str,ifname=name\n" 4157 " configure a host TAP network backend with ID 'str'\n" 4158#else 4159 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 4160 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 4161 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 4162 " [,poll-us=n]\n" 4163 " configure a host TAP network backend with ID 'str'\n" 4164 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 4165 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 4166 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 4167 " to deconfigure it\n" 4168 " use '[down]script=no' to disable script execution\n" 4169 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 4170 " configure it\n" 4171 " use 'fd=h' to connect to an already opened TAP interface\n" 4172 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 4173 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 4174 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 4175 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 4176 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 4177 " use vhost=on to enable experimental in kernel accelerator\n" 4178 " (only has effect for virtio guests which use MSIX)\n" 4179 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 4180 " use 'vhostfd=h' to connect to an already opened vhost net device\n" 4181 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 4182 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 4183 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 4184 " spent on busy polling for vhost net\n" 4185 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 4186 " configure a host TAP network backend with ID 'str' that is\n" 4187 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 4188 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 4189#endif 4190#ifdef __linux__ 4191 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 4192 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 4193 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 4194 " [,rxcookie=rxcookie][,offset=offset]\n" 4195 " configure a network backend with ID 'str' connected to\n" 4196 " an Ethernet over L2TPv3 pseudowire.\n" 4197 " Linux kernel 3.3+ as well as most routers can talk\n" 4198 " L2TPv3. This transport allows connecting a VM to a VM,\n" 4199 " VM to a router and even VM to Host. It is a nearly-universal\n" 4200 " standard (RFC3931). Note - this implementation uses static\n" 4201 " pre-configured tunnels (same as the Linux kernel).\n" 4202 " use 'src=' to specify source address\n" 4203 " use 'dst=' to specify destination address\n" 4204 " use 'udp=on' to specify udp encapsulation\n" 4205 " use 'srcport=' to specify source udp port\n" 4206 " use 'dstport=' to specify destination udp port\n" 4207 " use 'ipv6=on' to force v6\n" 4208 " L2TPv3 uses cookies to prevent misconfiguration as\n" 4209 " well as a weak security measure\n" 4210 " use 'rxcookie=0x012345678' to specify a rxcookie\n" 4211 " use 'txcookie=0x012345678' to specify a txcookie\n" 4212 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 4213 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 4214 " use 'pincounter=on' to work around broken counter handling in peer\n" 4215 " use 'offset=X' to add an extra offset between header and data\n" 4216#endif 4217 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 4218 " configure a network backend to connect to another network\n" 4219 " using a socket connection\n" 4220 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 4221 " configure a network backend to connect to a multicast maddr and port\n" 4222 " use 'localaddr=addr' to specify the host address to send packets from\n" 4223 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 4224 " configure a network backend to connect to another network\n" 4225 " using an UDP tunnel\n" 4226#ifdef CONFIG_VDE 4227 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 4228 " configure a network backend to connect to port 'n' of a vde switch\n" 4229 " running on host and listening for incoming connections on 'socketpath'.\n" 4230 " Use group 'groupname' and mode 'octalmode' to change default\n" 4231 " ownership and permissions for communication port.\n" 4232#endif 4233#ifdef CONFIG_NETMAP 4234 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 4235 " attach to the existing netmap-enabled network interface 'name', or to a\n" 4236 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 4237 " netmap device, defaults to '/dev/netmap')\n" 4238#endif 4239#ifdef CONFIG_POSIX 4240 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 4241 " configure a vhost-user network, backed by a chardev 'dev'\n" 4242#endif 4243 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 4244 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 4245DEF("nic", HAS_ARG, QEMU_OPTION_nic, 4246 "-nic [tap|bridge|" 4247#ifdef CONFIG_SLIRP 4248 "user|" 4249#endif 4250#ifdef __linux__ 4251 "l2tpv3|" 4252#endif 4253#ifdef CONFIG_VDE 4254 "vde|" 4255#endif 4256#ifdef CONFIG_NETMAP 4257 "netmap|" 4258#endif 4259#ifdef CONFIG_POSIX 4260 "vhost-user|" 4261#endif 4262 "socket][,option][,...][mac=macaddr]\n" 4263 " initialize an on-board / default host NIC (using MAC address\n" 4264 " macaddr) and connect it to the given host network backend\n" 4265 "-nic none use it alone to have zero network devices (the default is to\n" 4266 " provided a 'user' network connection)\n", 4267 QEMU_ARCH_ALL) 4268DEF("net", HAS_ARG, QEMU_OPTION_net, 4269 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 4270 " configure or create an on-board (or machine default) NIC and\n" 4271 " connect it to hub 0 (please use -nic unless you need a hub)\n" 4272 "-net [" 4273#ifdef CONFIG_SLIRP 4274 "user|" 4275#endif 4276 "tap|" 4277 "bridge|" 4278#ifdef CONFIG_VDE 4279 "vde|" 4280#endif 4281#ifdef CONFIG_NETMAP 4282 "netmap|" 4283#endif 4284 "socket][,option][,option][,...]\n" 4285 " old way to initialize a host network interface\n" 4286 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 4287STEXI 4288@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 4289@findex -nic 4290This option is a shortcut for configuring both the on-board (default) guest 4291NIC hardware and the host network backend in one go. The host backend options 4292are the same as with the corresponding @option{-netdev} options below. 4293The guest NIC model can be set with @option{model=@var{modelname}}. 4294Use @option{model=help} to list the available device types. 4295The hardware MAC address can be set with @option{mac=@var{macaddr}}. 4296 4297The following two example do exactly the same, to show how @option{-nic} can 4298be used to shorten the command line length: 4299@example 4300@value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 4301@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 4302@end example 4303 4304@item -nic none 4305Indicate that no network devices should be configured. It is used to override 4306the default configuration (default NIC with ``user'' host network backend) 4307which is activated if no other networking options are provided. 4308 4309@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 4310@findex -netdev 4311Configure user mode host network backend which requires no administrator 4312privilege to run. Valid options are: 4313 4314@table @option 4315@item id=@var{id} 4316Assign symbolic name for use in monitor commands. 4317 4318@item ipv4=on|off and ipv6=on|off 4319Specify that either IPv4 or IPv6 must be enabled. If neither is specified 4320both protocols are enabled. 4321 4322@item net=@var{addr}[/@var{mask}] 4323Set IP network address the guest will see. Optionally specify the netmask, 4324either in the form a.b.c.d or as number of valid top-most bits. Default is 432510.0.2.0/24. 4326 4327@item host=@var{addr} 4328Specify the guest-visible address of the host. Default is the 2nd IP in the 4329guest network, i.e. x.x.x.2. 4330 4331@item ipv6-net=@var{addr}[/@var{int}] 4332Set IPv6 network address the guest will see (default is fec0::/64). The 4333network prefix is given in the usual hexadecimal IPv6 address 4334notation. The prefix size is optional, and is given as the number of 4335valid top-most bits (default is 64). 4336 4337@item ipv6-host=@var{addr} 4338Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 4339the guest network, i.e. xxxx::2. 4340 4341@item restrict=on|off 4342If this option is enabled, the guest will be isolated, i.e. it will not be 4343able to contact the host and no guest IP packets will be routed over the host 4344to the outside. This option does not affect any explicitly set forwarding rules. 4345 4346@item hostname=@var{name} 4347Specifies the client hostname reported by the built-in DHCP server. 4348 4349@item dhcpstart=@var{addr} 4350Specify the first of the 16 IPs the built-in DHCP server can assign. Default 4351is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 4352 4353@item dns=@var{addr} 4354Specify the guest-visible address of the virtual nameserver. The address must 4355be different from the host address. Default is the 3rd IP in the guest network, 4356i.e. x.x.x.3. 4357 4358@item ipv6-dns=@var{addr} 4359Specify the guest-visible address of the IPv6 virtual nameserver. The address 4360must be different from the host address. Default is the 3rd IP in the guest 4361network, i.e. xxxx::3. 4362 4363@item dnssearch=@var{domain} 4364Provides an entry for the domain-search list sent by the built-in 4365DHCP server. More than one domain suffix can be transmitted by specifying 4366this option multiple times. If supported, this will cause the guest to 4367automatically try to append the given domain suffix(es) in case a domain name 4368can not be resolved. 4369 4370Example: 4371@example 4372@value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 4373@end example 4374 4375@item domainname=@var{domain} 4376Specifies the client domain name reported by the built-in DHCP server. 4377 4378@item tftp=@var{dir} 4379When using the user mode network stack, activate a built-in TFTP 4380server. The files in @var{dir} will be exposed as the root of a TFTP server. 4381The TFTP client on the guest must be configured in binary mode (use the command 4382@code{bin} of the Unix TFTP client). 4383 4384@item tftp-server-name=@var{name} 4385In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option 438666). This can be used to advise the guest to load boot files or configurations 4387from a different server than the host address. 4388 4389@item bootfile=@var{file} 4390When using the user mode network stack, broadcast @var{file} as the BOOTP 4391filename. In conjunction with @option{tftp}, this can be used to network boot 4392a guest from a local directory. 4393 4394Example (using pxelinux): 4395@example 4396@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \ 4397 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 4398@end example 4399 4400@item smb=@var{dir}[,smbserver=@var{addr}] 4401When using the user mode network stack, activate a built-in SMB 4402server so that Windows OSes can access to the host files in @file{@var{dir}} 4403transparently. The IP address of the SMB server can be set to @var{addr}. By 4404default the 4th IP in the guest network is used, i.e. x.x.x.4. 4405 4406In the guest Windows OS, the line: 4407@example 440810.0.2.4 smbserver 4409@end example 4410must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 4411or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 4412 4413Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 4414 4415Note that a SAMBA server must be installed on the host OS. 4416 4417@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 4418Redirect incoming TCP or UDP connections to the host port @var{hostport} to 4419the guest IP address @var{guestaddr} on guest port @var{guestport}. If 4420@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 4421given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 4422be bound to a specific host interface. If no connection type is set, TCP is 4423used. This option can be given multiple times. 4424 4425For example, to redirect host X11 connection from screen 1 to guest 4426screen 0, use the following: 4427 4428@example 4429# on the host 4430@value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 4431# this host xterm should open in the guest X11 server 4432xterm -display :1 4433@end example 4434 4435To redirect telnet connections from host port 5555 to telnet port on 4436the guest, use the following: 4437 4438@example 4439# on the host 4440@value{qemu_system} -nic user,hostfwd=tcp::5555-:23 4441telnet localhost 5555 4442@end example 4443 4444Then when you use on the host @code{telnet localhost 5555}, you 4445connect to the guest telnet server. 4446 4447@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 4448@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 4449Forward guest TCP connections to the IP address @var{server} on port @var{port} 4450to the character device @var{dev} or to a program executed by @var{cmd:command} 4451which gets spawned for each connection. This option can be given multiple times. 4452 4453You can either use a chardev directly and have that one used throughout QEMU's 4454lifetime, like in the following example: 4455 4456@example 4457# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 4458# the guest accesses it 4459@value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 4460@end example 4461 4462Or you can execute a command on every TCP connection established by the guest, 4463so that QEMU behaves similar to an inetd process for that virtual server: 4464 4465@example 4466# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 4467# and connect the TCP stream to its stdin/stdout 4468@value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 4469@end example 4470 4471@end table 4472 4473@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}] 4474Configure a host TAP network backend with ID @var{id}. 4475 4476Use the network script @var{file} to configure it and the network script 4477@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 4478automatically provides one. The default network configure script is 4479@file{/etc/qemu-ifup} and the default network deconfigure script is 4480@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 4481to disable script execution. 4482 4483If running QEMU as an unprivileged user, use the network helper 4484@var{helper} to configure the TAP interface and attach it to the bridge. 4485The default network helper executable is @file{/path/to/qemu-bridge-helper} 4486and the default bridge device is @file{br0}. 4487 4488@option{fd}=@var{h} can be used to specify the handle of an already 4489opened host TAP interface. 4490 4491Examples: 4492 4493@example 4494#launch a QEMU instance with the default network script 4495@value{qemu_system} linux.img -nic tap 4496@end example 4497 4498@example 4499#launch a QEMU instance with two NICs, each one connected 4500#to a TAP device 4501@value{qemu_system} linux.img \ 4502 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 4503 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 4504@end example 4505 4506@example 4507#launch a QEMU instance with the default network helper to 4508#connect a TAP device to bridge br0 4509@value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \ 4510 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 4511@end example 4512 4513@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 4514Connect a host TAP network interface to a host bridge device. 4515 4516Use the network helper @var{helper} to configure the TAP interface and 4517attach it to the bridge. The default network helper executable is 4518@file{/path/to/qemu-bridge-helper} and the default bridge 4519device is @file{br0}. 4520 4521Examples: 4522 4523@example 4524#launch a QEMU instance with the default network helper to 4525#connect a TAP device to bridge br0 4526@value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 4527@end example 4528 4529@example 4530#launch a QEMU instance with the default network helper to 4531#connect a TAP device to bridge qemubr0 4532@value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 4533@end example 4534 4535@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 4536 4537This host network backend can be used to connect the guest's network to 4538another QEMU virtual machine using a TCP socket connection. If @option{listen} 4539is specified, QEMU waits for incoming connections on @var{port} 4540(@var{host} is optional). @option{connect} is used to connect to 4541another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 4542specifies an already opened TCP socket. 4543 4544Example: 4545@example 4546# launch a first QEMU instance 4547@value{qemu_system} linux.img \ 4548 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 4549 -netdev socket,id=n1,listen=:1234 4550# connect the network of this instance to the network of the first instance 4551@value{qemu_system} linux.img \ 4552 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 4553 -netdev socket,id=n2,connect=127.0.0.1:1234 4554@end example 4555 4556@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 4557 4558Configure a socket host network backend to share the guest's network traffic 4559with another QEMU virtual machines using a UDP multicast socket, effectively 4560making a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 4561NOTES: 4562@enumerate 4563@item 4564Several QEMU can be running on different hosts and share same bus (assuming 4565correct multicast setup for these hosts). 4566@item 4567mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 4568@url{http://user-mode-linux.sf.net}. 4569@item 4570Use @option{fd=h} to specify an already opened UDP multicast socket. 4571@end enumerate 4572 4573Example: 4574@example 4575# launch one QEMU instance 4576@value{qemu_system} linux.img \ 4577 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 4578 -netdev socket,id=n1,mcast=230.0.0.1:1234 4579# launch another QEMU instance on same "bus" 4580@value{qemu_system} linux.img \ 4581 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 4582 -netdev socket,id=n2,mcast=230.0.0.1:1234 4583# launch yet another QEMU instance on same "bus" 4584@value{qemu_system} linux.img \ 4585 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 4586 -netdev socket,id=n3,mcast=230.0.0.1:1234 4587@end example 4588 4589Example (User Mode Linux compat.): 4590@example 4591# launch QEMU instance (note mcast address selected is UML's default) 4592@value{qemu_system} linux.img \ 4593 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 4594 -netdev socket,id=n1,mcast=239.192.168.1:1102 4595# launch UML 4596/path/to/linux ubd0=/path/to/root_fs eth0=mcast 4597@end example 4598 4599Example (send packets from host's 1.2.3.4): 4600@example 4601@value{qemu_system} linux.img \ 4602 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 4603 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 4604@end example 4605 4606@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}] 4607Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931) is a 4608popular protocol to transport Ethernet (and other Layer 2) data frames between 4609two systems. It is present in routers, firewalls and the Linux kernel 4610(from version 3.3 onwards). 4611 4612This transport allows a VM to communicate to another VM, router or firewall directly. 4613 4614@table @option 4615@item src=@var{srcaddr} 4616 source address (mandatory) 4617@item dst=@var{dstaddr} 4618 destination address (mandatory) 4619@item udp 4620 select udp encapsulation (default is ip). 4621@item srcport=@var{srcport} 4622 source udp port. 4623@item dstport=@var{dstport} 4624 destination udp port. 4625@item ipv6 4626 force v6, otherwise defaults to v4. 4627@item rxcookie=@var{rxcookie} 4628@itemx txcookie=@var{txcookie} 4629 Cookies are a weak form of security in the l2tpv3 specification. 4630Their function is mostly to prevent misconfiguration. By default they are 32 4631bit. 4632@item cookie64 4633 Set cookie size to 64 bit instead of the default 32 4634@item counter=off 4635 Force a 'cut-down' L2TPv3 with no counter as in 4636draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 4637@item pincounter=on 4638 Work around broken counter handling in peer. This may also help on 4639networks which have packet reorder. 4640@item offset=@var{offset} 4641 Add an extra offset between header and data 4642@end table 4643 4644For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 4645on the remote Linux host 1.2.3.4: 4646@example 4647# Setup tunnel on linux host using raw ip as encapsulation 4648# on 1.2.3.4 4649ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 4650 encap udp udp_sport 16384 udp_dport 16384 4651ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 4652 0xFFFFFFFF peer_session_id 0xFFFFFFFF 4653ifconfig vmtunnel0 mtu 1500 4654ifconfig vmtunnel0 up 4655brctl addif br-lan vmtunnel0 4656 4657 4658# on 4.3.2.1 4659# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 4660 4661@value{qemu_system} linux.img -device e1000,netdev=n1 \ 4662 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 4663 4664@end example 4665 4666@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 4667Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and 4668listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 4669and MODE @var{octalmode} to change default ownership and permissions for 4670communication port. This option is only available if QEMU has been compiled 4671with vde support enabled. 4672 4673Example: 4674@example 4675# launch vde switch 4676vde_switch -F -sock /tmp/myswitch 4677# launch QEMU instance 4678@value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch 4679@end example 4680 4681@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 4682 4683Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 4684be a unix domain socket backed one. The vhost-user uses a specifically defined 4685protocol to pass vhost ioctl replacement messages to an application on the other 4686end of the socket. On non-MSIX guests, the feature can be forced with 4687@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 4688be created for multiqueue vhost-user. 4689 4690Example: 4691@example 4692qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 4693 -numa node,memdev=mem \ 4694 -chardev socket,id=chr0,path=/path/to/socket \ 4695 -netdev type=vhost-user,id=net0,chardev=chr0 \ 4696 -device virtio-net-pci,netdev=net0 4697@end example 4698 4699@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 4700 4701Create a hub port on the emulated hub with ID @var{hubid}. 4702 4703The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 4704single netdev. Alternatively, you can also connect the hubport to another 4705netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 4706 4707@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 4708@findex -net 4709Legacy option to configure or create an on-board (or machine default) Network 4710Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 4711the default hub), or to the netdev @var{nd}. 4712If @var{model} is omitted, then the default NIC model associated with 4713the machine type is used. Note that the default NIC model may change in 4714future QEMU releases, so it is highly recommended to always specify a model. 4715Optionally, the MAC address can be changed to @var{mac}, the device 4716address set to @var{addr} (PCI cards only), and a @var{name} can be 4717assigned for use in monitor commands. 4718Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 4719that the card should have; this option currently only affects virtio cards; set 4720@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 4721NIC is created. QEMU can emulate several different models of network card. 4722Use @code{-net nic,model=help} for a list of available devices for your target. 4723 4724@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 4725Configure a host network backend (with the options corresponding to the same 4726@option{-netdev} option) and connect it to the emulated hub 0 (the default 4727hub). Use @var{name} to specify the name of the hub port. 4728ETEXI 4729SRST 4730``-nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]`` 4731 This option is a shortcut for configuring both the on-board 4732 (default) guest NIC hardware and the host network backend in one go. 4733 The host backend options are the same as with the corresponding 4734 ``-netdev`` options below. The guest NIC model can be set with 4735 ``model=modelname``. Use ``model=help`` to list the available device 4736 types. The hardware MAC address can be set with ``mac=macaddr``. 4737 4738 The following two example do exactly the same, to show how ``-nic`` 4739 can be used to shorten the command line length: 4740 4741 .. parsed-literal:: 4742 4743 |qemu_system| -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 4744 |qemu_system| -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 4745 4746``-nic none`` 4747 Indicate that no network devices should be configured. It is used to 4748 override the default configuration (default NIC with "user" host 4749 network backend) which is activated if no other networking options 4750 are provided. 4751 4752``-netdev user,id=id[,option][,option][,...]`` 4753 Configure user mode host network backend which requires no 4754 administrator privilege to run. Valid options are: 4755 4756 ``id=id`` 4757 Assign symbolic name for use in monitor commands. 4758 4759 ``ipv4=on|off and ipv6=on|off`` 4760 Specify that either IPv4 or IPv6 must be enabled. If neither is 4761 specified both protocols are enabled. 4762 4763 ``net=addr[/mask]`` 4764 Set IP network address the guest will see. Optionally specify 4765 the netmask, either in the form a.b.c.d or as number of valid 4766 top-most bits. Default is 10.0.2.0/24. 4767 4768 ``host=addr`` 4769 Specify the guest-visible address of the host. Default is the 4770 2nd IP in the guest network, i.e. x.x.x.2. 4771 4772 ``ipv6-net=addr[/int]`` 4773 Set IPv6 network address the guest will see (default is 4774 fec0::/64). The network prefix is given in the usual hexadecimal 4775 IPv6 address notation. The prefix size is optional, and is given 4776 as the number of valid top-most bits (default is 64). 4777 4778 ``ipv6-host=addr`` 4779 Specify the guest-visible IPv6 address of the host. Default is 4780 the 2nd IPv6 in the guest network, i.e. xxxx::2. 4781 4782 ``restrict=on|off`` 4783 If this option is enabled, the guest will be isolated, i.e. it 4784 will not be able to contact the host and no guest IP packets 4785 will be routed over the host to the outside. This option does 4786 not affect any explicitly set forwarding rules. 4787 4788 ``hostname=name`` 4789 Specifies the client hostname reported by the built-in DHCP 4790 server. 4791 4792 ``dhcpstart=addr`` 4793 Specify the first of the 16 IPs the built-in DHCP server can 4794 assign. Default is the 15th to 31st IP in the guest network, 4795 i.e. x.x.x.15 to x.x.x.31. 4796 4797 ``dns=addr`` 4798 Specify the guest-visible address of the virtual nameserver. The 4799 address must be different from the host address. Default is the 4800 3rd IP in the guest network, i.e. x.x.x.3. 4801 4802 ``ipv6-dns=addr`` 4803 Specify the guest-visible address of the IPv6 virtual 4804 nameserver. The address must be different from the host address. 4805 Default is the 3rd IP in the guest network, i.e. xxxx::3. 4806 4807 ``dnssearch=domain`` 4808 Provides an entry for the domain-search list sent by the 4809 built-in DHCP server. More than one domain suffix can be 4810 transmitted by specifying this option multiple times. If 4811 supported, this will cause the guest to automatically try to 4812 append the given domain suffix(es) in case a domain name can not 4813 be resolved. 4814 4815 Example: 4816 4817 .. parsed-literal:: 4818 4819 |qemu_system| -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 4820 4821 ``domainname=domain`` 4822 Specifies the client domain name reported by the built-in DHCP 4823 server. 4824 4825 ``tftp=dir`` 4826 When using the user mode network stack, activate a built-in TFTP 4827 server. The files in dir will be exposed as the root of a TFTP 4828 server. The TFTP client on the guest must be configured in 4829 binary mode (use the command ``bin`` of the Unix TFTP client). 4830 4831 ``tftp-server-name=name`` 4832 In BOOTP reply, broadcast name as the "TFTP server name" 4833 (RFC2132 option 66). This can be used to advise the guest to 4834 load boot files or configurations from a different server than 4835 the host address. 4836 4837 ``bootfile=file`` 4838 When using the user mode network stack, broadcast file as the 4839 BOOTP filename. In conjunction with ``tftp``, this can be used 4840 to network boot a guest from a local directory. 4841 4842 Example (using pxelinux): 4843 4844 .. parsed-literal:: 4845 4846 |qemu_system| -hda linux.img -boot n -device e1000,netdev=n1 \ 4847 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 4848 4849 ``smb=dir[,smbserver=addr]`` 4850 When using the user mode network stack, activate a built-in SMB 4851 server so that Windows OSes can access to the host files in 4852 ``dir`` transparently. The IP address of the SMB server can be 4853 set to addr. By default the 4th IP in the guest network is used, 4854 i.e. x.x.x.4. 4855 4856 In the guest Windows OS, the line: 4857 4858 :: 4859 4860 10.0.2.4 smbserver 4861 4862 must be added in the file ``C:\WINDOWS\LMHOSTS`` (for windows 4863 9x/Me) or ``C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS`` (Windows 4864 NT/2000). 4865 4866 Then ``dir`` can be accessed in ``\\smbserver\qemu``. 4867 4868 Note that a SAMBA server must be installed on the host OS. 4869 4870 ``hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport`` 4871 Redirect incoming TCP or UDP connections to the host port 4872 hostport to the guest IP address guestaddr on guest port 4873 guestport. If guestaddr is not specified, its value is x.x.x.15 4874 (default first address given by the built-in DHCP server). By 4875 specifying hostaddr, the rule can be bound to a specific host 4876 interface. If no connection type is set, TCP is used. This 4877 option can be given multiple times. 4878 4879 For example, to redirect host X11 connection from screen 1 to 4880 guest screen 0, use the following: 4881 4882 .. parsed-literal:: 4883 4884 # on the host 4885 |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 4886 # this host xterm should open in the guest X11 server 4887 xterm -display :1 4888 4889 To redirect telnet connections from host port 5555 to telnet 4890 port on the guest, use the following: 4891 4892 .. parsed-literal:: 4893 4894 # on the host 4895 |qemu_system| -nic user,hostfwd=tcp::5555-:23 4896 telnet localhost 5555 4897 4898 Then when you use on the host ``telnet localhost 5555``, you 4899 connect to the guest telnet server. 4900 4901 ``guestfwd=[tcp]:server:port-dev``; \ ``guestfwd=[tcp]:server:port-cmd:command`` 4902 Forward guest TCP connections to the IP address server on port 4903 port to the character device dev or to a program executed by 4904 cmd:command which gets spawned for each connection. This option 4905 can be given multiple times. 4906 4907 You can either use a chardev directly and have that one used 4908 throughout QEMU's lifetime, like in the following example: 4909 4910 .. parsed-literal:: 4911 4912 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 4913 # the guest accesses it 4914 |qemu_system| -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 4915 4916 Or you can execute a command on every TCP connection established 4917 by the guest, so that QEMU behaves similar to an inetd process 4918 for that virtual server: 4919 4920 .. parsed-literal:: 4921 4922 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 4923 # and connect the TCP stream to its stdin/stdout 4924 |qemu_system| -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 4925 4926``-netdev tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]`` 4927 Configure a host TAP network backend with ID id. 4928 4929 Use the network script file to configure it and the network script 4930 dfile to deconfigure it. If name is not provided, the OS 4931 automatically provides one. The default network configure script is 4932 ``/etc/qemu-ifup`` and the default network deconfigure script is 4933 ``/etc/qemu-ifdown``. Use ``script=no`` or ``downscript=no`` to 4934 disable script execution. 4935 4936 If running QEMU as an unprivileged user, use the network helper 4937 helper to configure the TAP interface and attach it to the bridge. 4938 The default network helper executable is 4939 ``/path/to/qemu-bridge-helper`` and the default bridge device is 4940 ``br0``. 4941 4942 ``fd``\ =h can be used to specify the handle of an already opened 4943 host TAP interface. 4944 4945 Examples: 4946 4947 .. parsed-literal:: 4948 4949 #launch a QEMU instance with the default network script 4950 |qemu_system| linux.img -nic tap 4951 4952 .. parsed-literal:: 4953 4954 #launch a QEMU instance with two NICs, each one connected 4955 #to a TAP device 4956 |qemu_system| linux.img \ 4957 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 4958 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 4959 4960 .. parsed-literal:: 4961 4962 #launch a QEMU instance with the default network helper to 4963 #connect a TAP device to bridge br0 4964 |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \ 4965 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 4966 4967``-netdev bridge,id=id[,br=bridge][,helper=helper]`` 4968 Connect a host TAP network interface to a host bridge device. 4969 4970 Use the network helper helper to configure the TAP interface and 4971 attach it to the bridge. The default network helper executable is 4972 ``/path/to/qemu-bridge-helper`` and the default bridge device is 4973 ``br0``. 4974 4975 Examples: 4976 4977 .. parsed-literal:: 4978 4979 #launch a QEMU instance with the default network helper to 4980 #connect a TAP device to bridge br0 4981 |qemu_system| linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 4982 4983 .. parsed-literal:: 4984 4985 #launch a QEMU instance with the default network helper to 4986 #connect a TAP device to bridge qemubr0 4987 |qemu_system| linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 4988 4989``-netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]`` 4990 This host network backend can be used to connect the guest's network 4991 to another QEMU virtual machine using a TCP socket connection. If 4992 ``listen`` is specified, QEMU waits for incoming connections on port 4993 (host is optional). ``connect`` is used to connect to another QEMU 4994 instance using the ``listen`` option. ``fd``\ =h specifies an 4995 already opened TCP socket. 4996 4997 Example: 4998 4999 .. parsed-literal:: 5000 5001 # launch a first QEMU instance 5002 |qemu_system| linux.img \ 5003 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 5004 -netdev socket,id=n1,listen=:1234 5005 # connect the network of this instance to the network of the first instance 5006 |qemu_system| linux.img \ 5007 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 5008 -netdev socket,id=n2,connect=127.0.0.1:1234 5009 5010``-netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]`` 5011 Configure a socket host network backend to share the guest's network 5012 traffic with another QEMU virtual machines using a UDP multicast 5013 socket, effectively making a bus for every QEMU with same multicast 5014 address maddr and port. NOTES: 5015 5016 1. Several QEMU can be running on different hosts and share same bus 5017 (assuming correct multicast setup for these hosts). 5018 5019 2. mcast support is compatible with User Mode Linux (argument 5020 ``ethN=mcast``), see http://user-mode-linux.sf.net. 5021 5022 3. Use ``fd=h`` to specify an already opened UDP multicast socket. 5023 5024 Example: 5025 5026 .. parsed-literal:: 5027 5028 # launch one QEMU instance 5029 |qemu_system| linux.img \ 5030 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 5031 -netdev socket,id=n1,mcast=230.0.0.1:1234 5032 # launch another QEMU instance on same "bus" 5033 |qemu_system| linux.img \ 5034 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 5035 -netdev socket,id=n2,mcast=230.0.0.1:1234 5036 # launch yet another QEMU instance on same "bus" 5037 |qemu_system| linux.img \ 5038 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 5039 -netdev socket,id=n3,mcast=230.0.0.1:1234 5040 5041 Example (User Mode Linux compat.): 5042 5043 .. parsed-literal:: 5044 5045 # launch QEMU instance (note mcast address selected is UML's default) 5046 |qemu_system| linux.img \ 5047 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 5048 -netdev socket,id=n1,mcast=239.192.168.1:1102 5049 # launch UML 5050 /path/to/linux ubd0=/path/to/root_fs eth0=mcast 5051 5052 Example (send packets from host's 1.2.3.4): 5053 5054 .. parsed-literal:: 5055 5056 |qemu_system| linux.img \ 5057 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 5058 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 5059 5060``-netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]`` 5061 Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931) 5062 is a popular protocol to transport Ethernet (and other Layer 2) data 5063 frames between two systems. It is present in routers, firewalls and 5064 the Linux kernel (from version 3.3 onwards). 5065 5066 This transport allows a VM to communicate to another VM, router or 5067 firewall directly. 5068 5069 ``src=srcaddr`` 5070 source address (mandatory) 5071 5072 ``dst=dstaddr`` 5073 destination address (mandatory) 5074 5075 ``udp`` 5076 select udp encapsulation (default is ip). 5077 5078 ``srcport=srcport`` 5079 source udp port. 5080 5081 ``dstport=dstport`` 5082 destination udp port. 5083 5084 ``ipv6`` 5085 force v6, otherwise defaults to v4. 5086 5087 ``rxcookie=rxcookie``; \ ``txcookie=txcookie`` 5088 Cookies are a weak form of security in the l2tpv3 specification. 5089 Their function is mostly to prevent misconfiguration. By default 5090 they are 32 bit. 5091 5092 ``cookie64`` 5093 Set cookie size to 64 bit instead of the default 32 5094 5095 ``counter=off`` 5096 Force a 'cut-down' L2TPv3 with no counter as in 5097 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 5098 5099 ``pincounter=on`` 5100 Work around broken counter handling in peer. This may also help 5101 on networks which have packet reorder. 5102 5103 ``offset=offset`` 5104 Add an extra offset between header and data 5105 5106 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to 5107 the bridge br-lan on the remote Linux host 1.2.3.4: 5108 5109 .. parsed-literal:: 5110 5111 # Setup tunnel on linux host using raw ip as encapsulation 5112 # on 1.2.3.4 5113 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 5114 encap udp udp_sport 16384 udp_dport 16384 5115 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 5116 0xFFFFFFFF peer_session_id 0xFFFFFFFF 5117 ifconfig vmtunnel0 mtu 1500 5118 ifconfig vmtunnel0 up 5119 brctl addif br-lan vmtunnel0 5120 5121 5122 # on 4.3.2.1 5123 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 5124 5125 |qemu_system| linux.img -device e1000,netdev=n1 \ 5126 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 5127 5128``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]`` 5129 Configure VDE backend to connect to PORT n of a vde switch running 5130 on host and listening for incoming connections on socketpath. Use 5131 GROUP groupname and MODE octalmode to change default ownership and 5132 permissions for communication port. This option is only available if 5133 QEMU has been compiled with vde support enabled. 5134 5135 Example: 5136 5137 .. parsed-literal:: 5138 5139 # launch vde switch 5140 vde_switch -F -sock /tmp/myswitch 5141 # launch QEMU instance 5142 |qemu_system| linux.img -nic vde,sock=/tmp/myswitch 5143 5144``-netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]`` 5145 Establish a vhost-user netdev, backed by a chardev id. The chardev 5146 should be a unix domain socket backed one. The vhost-user uses a 5147 specifically defined protocol to pass vhost ioctl replacement 5148 messages to an application on the other end of the socket. On 5149 non-MSIX guests, the feature can be forced with vhostforce. Use 5150 'queues=n' to specify the number of queues to be created for 5151 multiqueue vhost-user. 5152 5153 Example: 5154 5155 :: 5156 5157 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 5158 -numa node,memdev=mem \ 5159 -chardev socket,id=chr0,path=/path/to/socket \ 5160 -netdev type=vhost-user,id=net0,chardev=chr0 \ 5161 -device virtio-net-pci,netdev=net0 5162 5163``-netdev hubport,id=id,hubid=hubid[,netdev=nd]`` 5164 Create a hub port on the emulated hub with ID hubid. 5165 5166 The hubport netdev lets you connect a NIC to a QEMU emulated hub 5167 instead of a single netdev. Alternatively, you can also connect the 5168 hubport to another netdev with ID nd by using the ``netdev=nd`` 5169 option. 5170 5171``-net nic[,netdev=nd][,macaddr=mac][,model=type] [,name=name][,addr=addr][,vectors=v]`` 5172 Legacy option to configure or create an on-board (or machine 5173 default) Network Interface Card(NIC) and connect it either to the 5174 emulated hub with ID 0 (i.e. the default hub), or to the netdev nd. 5175 If model is omitted, then the default NIC model associated with the 5176 machine type is used. Note that the default NIC model may change in 5177 future QEMU releases, so it is highly recommended to always specify 5178 a model. Optionally, the MAC address can be changed to mac, the 5179 device address set to addr (PCI cards only), and a name can be 5180 assigned for use in monitor commands. Optionally, for PCI cards, you 5181 can specify the number v of MSI-X vectors that the card should have; 5182 this option currently only affects virtio cards; set v = 0 to 5183 disable MSI-X. If no ``-net`` option is specified, a single NIC is 5184 created. QEMU can emulate several different models of network card. 5185 Use ``-net nic,model=help`` for a list of available devices for your 5186 target. 5187 5188``-net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]`` 5189 Configure a host network backend (with the options corresponding to 5190 the same ``-netdev`` option) and connect it to the emulated hub 0 5191 (the default hub). Use name to specify the name of the hub port. 5192ERST 5193 5194STEXI 5195@end table 5196ETEXI 5197DEFHEADING() 5198 5199DEFHEADING(Character device options:) 5200 5201DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 5202 "-chardev help\n" 5203 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5204 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 5205 " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n" 5206 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n" 5207 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n" 5208 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 5209 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 5210 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 5211 " [,logfile=PATH][,logappend=on|off]\n" 5212 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5213 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 5214 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5215 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 5216 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5217 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5218#ifdef _WIN32 5219 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5220 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5221#else 5222 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5223 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 5224#endif 5225#ifdef CONFIG_BRLAPI 5226 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5227#endif 5228#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 5229 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 5230 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5231 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5232#endif 5233#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 5234 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5235 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 5236#endif 5237#if defined(CONFIG_SPICE) 5238 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 5239 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 5240#endif 5241 , QEMU_ARCH_ALL 5242) 5243 5244STEXI 5245 5246The general form of a character device option is: 5247@table @option 5248@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 5249@findex -chardev 5250Backend is one of: 5251@option{null}, 5252@option{socket}, 5253@option{udp}, 5254@option{msmouse}, 5255@option{vc}, 5256@option{ringbuf}, 5257@option{file}, 5258@option{pipe}, 5259@option{console}, 5260@option{serial}, 5261@option{pty}, 5262@option{stdio}, 5263@option{braille}, 5264@option{tty}, 5265@option{parallel}, 5266@option{parport}, 5267@option{spicevmc}, 5268@option{spiceport}. 5269The specific backend will determine the applicable options. 5270 5271Use @code{-chardev help} to print all available chardev backend types. 5272 5273All devices must have an id, which can be any string up to 127 characters long. 5274It is used to uniquely identify this device in other command line directives. 5275 5276A character device may be used in multiplexing mode by multiple front-ends. 5277Specify @option{mux=on} to enable this mode. 5278A multiplexer is a "1:N" device, and here the "1" end is your specified chardev 5279backend, and the "N" end is the various parts of QEMU that can talk to a chardev. 5280If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 5281create a multiplexer with your specified ID, and you can then configure multiple 5282front ends to use that chardev ID for their input/output. Up to four different 5283front ends can be connected to a single multiplexed chardev. (Without 5284multiplexing enabled, a chardev can only be used by a single front end.) 5285For instance you could use this to allow a single stdio chardev to be used by 5286two serial ports and the QEMU monitor: 5287 5288@example 5289-chardev stdio,mux=on,id=char0 \ 5290-mon chardev=char0,mode=readline \ 5291-serial chardev:char0 \ 5292-serial chardev:char0 5293@end example 5294 5295You can have more than one multiplexer in a system configuration; for instance 5296you could have a TCP port multiplexed between UART 0 and UART 1, and stdio 5297multiplexed between the QEMU monitor and a parallel port: 5298 5299@example 5300-chardev stdio,mux=on,id=char0 \ 5301-mon chardev=char0,mode=readline \ 5302-parallel chardev:char0 \ 5303-chardev tcp,...,mux=on,id=char1 \ 5304-serial chardev:char1 \ 5305-serial chardev:char1 5306@end example 5307 5308When you're using a multiplexed character device, some escape sequences are 5309interpreted in the input. @xref{mux_keys, Keys in the character backend 5310multiplexer}. 5311 5312Note that some other command line options may implicitly create multiplexed 5313character backends; for instance @option{-serial mon:stdio} creates a 5314multiplexed stdio backend connected to the serial port and the QEMU monitor, 5315and @option{-nographic} also multiplexes the console and the monitor to 5316stdio. 5317 5318There is currently no support for multiplexing in the other direction 5319(where a single QEMU front end takes input and output from multiple chardevs). 5320 5321Every backend supports the @option{logfile} option, which supplies the path 5322to a file to record all data transmitted via the backend. The @option{logappend} 5323option controls whether the log file will be truncated or appended to when 5324opened. 5325 5326@end table 5327 5328The available backends are: 5329 5330@table @option 5331@item -chardev null,id=@var{id} 5332A void device. This device will not emit any data, and will drop any data it 5333receives. The null backend does not take any options. 5334 5335@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}] 5336 5337Create a two-way stream socket, which can be either a TCP or a unix socket. A 5338unix socket will be created if @option{path} is specified. Behaviour is 5339undefined if TCP options are specified for a unix socket. 5340 5341@option{server} specifies that the socket shall be a listening socket. 5342 5343@option{nowait} specifies that QEMU should not block waiting for a client to 5344connect to a listening socket. 5345 5346@option{telnet} specifies that traffic on the socket should interpret telnet 5347escape sequences. 5348 5349@option{websocket} specifies that the socket uses WebSocket protocol for 5350communication. 5351 5352@option{reconnect} sets the timeout for reconnecting on non-server sockets when 5353the remote end goes away. qemu will delay this many seconds and then attempt 5354to reconnect. Zero disables reconnecting, and is the default. 5355 5356@option{tls-creds} requests enablement of the TLS protocol for encryption, 5357and specifies the id of the TLS credentials to use for the handshake. The 5358credentials must be previously created with the @option{-object tls-creds} 5359argument. 5360 5361@option{tls-auth} provides the ID of the QAuthZ authorization object against 5362which the client's x509 distinguished name will be validated. This object is 5363only resolved at time of use, so can be deleted and recreated on the fly 5364while the chardev server is active. If missing, it will default to denying 5365access. 5366 5367TCP and unix socket options are given below: 5368 5369@table @option 5370 5371@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 5372 5373@option{host} for a listening socket specifies the local address to be bound. 5374For a connecting socket species the remote host to connect to. @option{host} is 5375optional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 5376 5377@option{port} for a listening socket specifies the local port to be bound. For a 5378connecting socket specifies the port on the remote host to connect to. 5379@option{port} can be given as either a port number or a service name. 5380@option{port} is required. 5381 5382@option{to} is only relevant to listening sockets. If it is specified, and 5383@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 5384to and including @option{to} until it succeeds. @option{to} must be specified 5385as a port number. 5386 5387@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 5388If neither is specified the socket may use either protocol. 5389 5390@option{nodelay} disables the Nagle algorithm. 5391 5392@item unix options: path=@var{path} 5393 5394@option{path} specifies the local path of the unix socket. @option{path} is 5395required. 5396 5397@end table 5398 5399@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 5400 5401Sends all traffic from the guest to a remote host over UDP. 5402 5403@option{host} specifies the remote host to connect to. If not specified it 5404defaults to @code{localhost}. 5405 5406@option{port} specifies the port on the remote host to connect to. @option{port} 5407is required. 5408 5409@option{localaddr} specifies the local address to bind to. If not specified it 5410defaults to @code{0.0.0.0}. 5411 5412@option{localport} specifies the local port to bind to. If not specified any 5413available local port will be used. 5414 5415@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 5416If neither is specified the device may use either protocol. 5417 5418@item -chardev msmouse,id=@var{id} 5419 5420Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 5421take any options. 5422 5423@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 5424 5425Connect to a QEMU text console. @option{vc} may optionally be given a specific 5426size. 5427 5428@option{width} and @option{height} specify the width and height respectively of 5429the console, in pixels. 5430 5431@option{cols} and @option{rows} specify that the console be sized to fit a text 5432console with the given dimensions. 5433 5434@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 5435 5436Create a ring buffer with fixed size @option{size}. 5437@var{size} must be a power of two and defaults to @code{64K}. 5438 5439@item -chardev file,id=@var{id},path=@var{path} 5440 5441Log all traffic received from the guest to a file. 5442 5443@option{path} specifies the path of the file to be opened. This file will be 5444created if it does not already exist, and overwritten if it does. @option{path} 5445is required. 5446 5447@item -chardev pipe,id=@var{id},path=@var{path} 5448 5449Create a two-way connection to the guest. The behaviour differs slightly between 5450Windows hosts and other hosts: 5451 5452On Windows, a single duplex pipe will be created at 5453@file{\\.pipe\@option{path}}. 5454 5455On other hosts, 2 pipes will be created called @file{@option{path}.in} and 5456@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 5457received by the guest. Data written by the guest can be read from 5458@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 5459be present. 5460 5461@option{path} forms part of the pipe path as described above. @option{path} is 5462required. 5463 5464@item -chardev console,id=@var{id} 5465 5466Send traffic from the guest to QEMU's standard output. @option{console} does not 5467take any options. 5468 5469@option{console} is only available on Windows hosts. 5470 5471@item -chardev serial,id=@var{id},path=@option{path} 5472 5473Send traffic from the guest to a serial device on the host. 5474 5475On Unix hosts serial will actually accept any tty device, 5476not only serial lines. 5477 5478@option{path} specifies the name of the serial device to open. 5479 5480@item -chardev pty,id=@var{id} 5481 5482Create a new pseudo-terminal on the host and connect to it. @option{pty} does 5483not take any options. 5484 5485@option{pty} is not available on Windows hosts. 5486 5487@item -chardev stdio,id=@var{id}[,signal=on|off] 5488Connect to standard input and standard output of the QEMU process. 5489 5490@option{signal} controls if signals are enabled on the terminal, that includes 5491exiting QEMU with the key sequence @key{Control-c}. This option is enabled by 5492default, use @option{signal=off} to disable it. 5493 5494@item -chardev braille,id=@var{id} 5495 5496Connect to a local BrlAPI server. @option{braille} does not take any options. 5497 5498@item -chardev tty,id=@var{id},path=@var{path} 5499 5500@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 5501DragonFlyBSD hosts. It is an alias for @option{serial}. 5502 5503@option{path} specifies the path to the tty. @option{path} is required. 5504 5505@item -chardev parallel,id=@var{id},path=@var{path} 5506@itemx -chardev parport,id=@var{id},path=@var{path} 5507 5508@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 5509 5510Connect to a local parallel port. 5511 5512@option{path} specifies the path to the parallel port device. @option{path} is 5513required. 5514 5515@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 5516 5517@option{spicevmc} is only available when spice support is built in. 5518 5519@option{debug} debug level for spicevmc 5520 5521@option{name} name of spice channel to connect to 5522 5523Connect to a spice virtual machine channel, such as vdiport. 5524 5525@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 5526 5527@option{spiceport} is only available when spice support is built in. 5528 5529@option{debug} debug level for spicevmc 5530 5531@option{name} name of spice port to connect to 5532 5533Connect to a spice port, allowing a Spice client to handle the traffic 5534identified by a name (preferably a fqdn). 5535ETEXI 5536SRST 5537The general form of a character device option is: 5538 5539``-chardev backend,id=id[,mux=on|off][,options]`` 5540 Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``, 5541 ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``, 5542 ``pty``, ``stdio``, ``braille``, ``tty``, ``parallel``, ``parport``, 5543 ``spicevmc``, ``spiceport``. The specific backend will determine the 5544 applicable options. 5545 5546 Use ``-chardev help`` to print all available chardev backend types. 5547 5548 All devices must have an id, which can be any string up to 127 5549 characters long. It is used to uniquely identify this device in 5550 other command line directives. 5551 5552 A character device may be used in multiplexing mode by multiple 5553 front-ends. Specify ``mux=on`` to enable this mode. A multiplexer is 5554 a "1:N" device, and here the "1" end is your specified chardev 5555 backend, and the "N" end is the various parts of QEMU that can talk 5556 to a chardev. If you create a chardev with ``id=myid`` and 5557 ``mux=on``, QEMU will create a multiplexer with your specified ID, 5558 and you can then configure multiple front ends to use that chardev 5559 ID for their input/output. Up to four different front ends can be 5560 connected to a single multiplexed chardev. (Without multiplexing 5561 enabled, a chardev can only be used by a single front end.) For 5562 instance you could use this to allow a single stdio chardev to be 5563 used by two serial ports and the QEMU monitor: 5564 5565 :: 5566 5567 -chardev stdio,mux=on,id=char0 \ 5568 -mon chardev=char0,mode=readline \ 5569 -serial chardev:char0 \ 5570 -serial chardev:char0 5571 5572 You can have more than one multiplexer in a system configuration; 5573 for instance you could have a TCP port multiplexed between UART 0 5574 and UART 1, and stdio multiplexed between the QEMU monitor and a 5575 parallel port: 5576 5577 :: 5578 5579 -chardev stdio,mux=on,id=char0 \ 5580 -mon chardev=char0,mode=readline \ 5581 -parallel chardev:char0 \ 5582 -chardev tcp,...,mux=on,id=char1 \ 5583 -serial chardev:char1 \ 5584 -serial chardev:char1 5585 5586 When you're using a multiplexed character device, some escape 5587 sequences are interpreted in the input. See :ref:`mux_005fkeys`. 5588 5589 Note that some other command line options may implicitly create 5590 multiplexed character backends; for instance ``-serial mon:stdio`` 5591 creates a multiplexed stdio backend connected to the serial port and 5592 the QEMU monitor, and ``-nographic`` also multiplexes the console 5593 and the monitor to stdio. 5594 5595 There is currently no support for multiplexing in the other 5596 direction (where a single QEMU front end takes input and output from 5597 multiple chardevs). 5598 5599 Every backend supports the ``logfile`` option, which supplies the 5600 path to a file to record all data transmitted via the backend. The 5601 ``logappend`` option controls whether the log file will be truncated 5602 or appended to when opened. 5603 5604The available backends are: 5605 5606``-chardev null,id=id`` 5607 A void device. This device will not emit any data, and will drop any 5608 data it receives. The null backend does not take any options. 5609 5610``-chardev socket,id=id[,TCP options or unix options][,server][,nowait][,telnet][,websocket][,reconnect=seconds][,tls-creds=id][,tls-authz=id]`` 5611 Create a two-way stream socket, which can be either a TCP or a unix 5612 socket. A unix socket will be created if ``path`` is specified. 5613 Behaviour is undefined if TCP options are specified for a unix 5614 socket. 5615 5616 ``server`` specifies that the socket shall be a listening socket. 5617 5618 ``nowait`` specifies that QEMU should not block waiting for a client 5619 to connect to a listening socket. 5620 5621 ``telnet`` specifies that traffic on the socket should interpret 5622 telnet escape sequences. 5623 5624 ``websocket`` specifies that the socket uses WebSocket protocol for 5625 communication. 5626 5627 ``reconnect`` sets the timeout for reconnecting on non-server 5628 sockets when the remote end goes away. qemu will delay this many 5629 seconds and then attempt to reconnect. Zero disables reconnecting, 5630 and is the default. 5631 5632 ``tls-creds`` requests enablement of the TLS protocol for 5633 encryption, and specifies the id of the TLS credentials to use for 5634 the handshake. The credentials must be previously created with the 5635 ``-object tls-creds`` argument. 5636 5637 ``tls-auth`` provides the ID of the QAuthZ authorization object 5638 against which the client's x509 distinguished name will be 5639 validated. This object is only resolved at time of use, so can be 5640 deleted and recreated on the fly while the chardev server is active. 5641 If missing, it will default to denying access. 5642 5643 TCP and unix socket options are given below: 5644 5645 ``TCP options: port=port[,host=host][,to=to][,ipv4][,ipv6][,nodelay]`` 5646 ``host`` for a listening socket specifies the local address to 5647 be bound. For a connecting socket species the remote host to 5648 connect to. ``host`` is optional for listening sockets. If not 5649 specified it defaults to ``0.0.0.0``. 5650 5651 ``port`` for a listening socket specifies the local port to be 5652 bound. For a connecting socket specifies the port on the remote 5653 host to connect to. ``port`` can be given as either a port 5654 number or a service name. ``port`` is required. 5655 5656 ``to`` is only relevant to listening sockets. If it is 5657 specified, and ``port`` cannot be bound, QEMU will attempt to 5658 bind to subsequent ports up to and including ``to`` until it 5659 succeeds. ``to`` must be specified as a port number. 5660 5661 ``ipv4`` and ``ipv6`` specify that either IPv4 or IPv6 must be 5662 used. If neither is specified the socket may use either 5663 protocol. 5664 5665 ``nodelay`` disables the Nagle algorithm. 5666 5667 ``unix options: path=path`` 5668 ``path`` specifies the local path of the unix socket. ``path`` 5669 is required. 5670 5671``-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4][,ipv6]`` 5672 Sends all traffic from the guest to a remote host over UDP. 5673 5674 ``host`` specifies the remote host to connect to. If not specified 5675 it defaults to ``localhost``. 5676 5677 ``port`` specifies the port on the remote host to connect to. 5678 ``port`` is required. 5679 5680 ``localaddr`` specifies the local address to bind to. If not 5681 specified it defaults to ``0.0.0.0``. 5682 5683 ``localport`` specifies the local port to bind to. If not specified 5684 any available local port will be used. 5685 5686 ``ipv4`` and ``ipv6`` specify that either IPv4 or IPv6 must be used. 5687 If neither is specified the device may use either protocol. 5688 5689``-chardev msmouse,id=id`` 5690 Forward QEMU's emulated msmouse events to the guest. ``msmouse`` 5691 does not take any options. 5692 5693``-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]`` 5694 Connect to a QEMU text console. ``vc`` may optionally be given a 5695 specific size. 5696 5697 ``width`` and ``height`` specify the width and height respectively 5698 of the console, in pixels. 5699 5700 ``cols`` and ``rows`` specify that the console be sized to fit a 5701 text console with the given dimensions. 5702 5703``-chardev ringbuf,id=id[,size=size]`` 5704 Create a ring buffer with fixed size ``size``. size must be a power 5705 of two and defaults to ``64K``. 5706 5707``-chardev file,id=id,path=path`` 5708 Log all traffic received from the guest to a file. 5709 5710 ``path`` specifies the path of the file to be opened. This file will 5711 be created if it does not already exist, and overwritten if it does. 5712 ``path`` is required. 5713 5714``-chardev pipe,id=id,path=path`` 5715 Create a two-way connection to the guest. The behaviour differs 5716 slightly between Windows hosts and other hosts: 5717 5718 On Windows, a single duplex pipe will be created at 5719 ``\\.pipe\path``. 5720 5721 On other hosts, 2 pipes will be created called ``path.in`` and 5722 ``path.out``. Data written to ``path.in`` will be received by the 5723 guest. Data written by the guest can be read from ``path.out``. QEMU 5724 will not create these fifos, and requires them to be present. 5725 5726 ``path`` forms part of the pipe path as described above. ``path`` is 5727 required. 5728 5729``-chardev console,id=id`` 5730 Send traffic from the guest to QEMU's standard output. ``console`` 5731 does not take any options. 5732 5733 ``console`` is only available on Windows hosts. 5734 5735``-chardev serial,id=id,path=path`` 5736 Send traffic from the guest to a serial device on the host. 5737 5738 On Unix hosts serial will actually accept any tty device, not only 5739 serial lines. 5740 5741 ``path`` specifies the name of the serial device to open. 5742 5743``-chardev pty,id=id`` 5744 Create a new pseudo-terminal on the host and connect to it. ``pty`` 5745 does not take any options. 5746 5747 ``pty`` is not available on Windows hosts. 5748 5749``-chardev stdio,id=id[,signal=on|off]`` 5750 Connect to standard input and standard output of the QEMU process. 5751 5752 ``signal`` controls if signals are enabled on the terminal, that 5753 includes exiting QEMU with the key sequence Control-c. This option 5754 is enabled by default, use ``signal=off`` to disable it. 5755 5756``-chardev braille,id=id`` 5757 Connect to a local BrlAPI server. ``braille`` does not take any 5758 options. 5759 5760``-chardev tty,id=id,path=path`` 5761 ``tty`` is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD 5762 and DragonFlyBSD hosts. It is an alias for ``serial``. 5763 5764 ``path`` specifies the path to the tty. ``path`` is required. 5765 5766``-chardev parallel,id=id,path=path`` 5767 \ 5768``-chardev parport,id=id,path=path`` 5769 ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD 5770 hosts. 5771 5772 Connect to a local parallel port. 5773 5774 ``path`` specifies the path to the parallel port device. ``path`` is 5775 required. 5776 5777``-chardev spicevmc,id=id,debug=debug,name=name`` 5778 ``spicevmc`` is only available when spice support is built in. 5779 5780 ``debug`` debug level for spicevmc 5781 5782 ``name`` name of spice channel to connect to 5783 5784 Connect to a spice virtual machine channel, such as vdiport. 5785 5786``-chardev spiceport,id=id,debug=debug,name=name`` 5787 ``spiceport`` is only available when spice support is built in. 5788 5789 ``debug`` debug level for spicevmc 5790 5791 ``name`` name of spice port to connect to 5792 5793 Connect to a spice port, allowing a Spice client to handle the 5794 traffic identified by a name (preferably a fqdn). 5795ERST 5796 5797STEXI 5798@end table 5799ETEXI 5800DEFHEADING() 5801 5802#ifdef CONFIG_TPM 5803DEFHEADING(TPM device options:) 5804 5805DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 5806 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 5807 " use path to provide path to a character device; default is /dev/tpm0\n" 5808 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 5809 " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 5810 "-tpmdev emulator,id=id,chardev=dev\n" 5811 " configure the TPM device using chardev backend\n", 5812 QEMU_ARCH_ALL) 5813STEXI 5814 5815The general form of a TPM device option is: 5816@table @option 5817 5818@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 5819@findex -tpmdev 5820 5821The specific backend type will determine the applicable options. 5822The @code{-tpmdev} option creates the TPM backend and requires a 5823@code{-device} option that specifies the TPM frontend interface model. 5824 5825Use @code{-tpmdev help} to print all available TPM backend types. 5826 5827@end table 5828 5829The available backends are: 5830 5831@table @option 5832 5833@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 5834 5835(Linux-host only) Enable access to the host's TPM using the passthrough 5836driver. 5837 5838@option{path} specifies the path to the host's TPM device, i.e., on 5839a Linux host this would be @code{/dev/tpm0}. 5840@option{path} is optional and by default @code{/dev/tpm0} is used. 5841 5842@option{cancel-path} specifies the path to the host TPM device's sysfs 5843entry allowing for cancellation of an ongoing TPM command. 5844@option{cancel-path} is optional and by default QEMU will search for the 5845sysfs entry to use. 5846 5847Some notes about using the host's TPM with the passthrough driver: 5848 5849The TPM device accessed by the passthrough driver must not be 5850used by any other application on the host. 5851 5852Since the host's firmware (BIOS/UEFI) has already initialized the TPM, 5853the VM's firmware (BIOS/UEFI) will not be able to initialize the 5854TPM again and may therefore not show a TPM-specific menu that would 5855otherwise allow the user to configure the TPM, e.g., allow the user to 5856enable/disable or activate/deactivate the TPM. 5857Further, if TPM ownership is released from within a VM then the host's TPM 5858will get disabled and deactivated. To enable and activate the 5859TPM again afterwards, the host has to be rebooted and the user is 5860required to enter the firmware's menu to enable and activate the TPM. 5861If the TPM is left disabled and/or deactivated most TPM commands will fail. 5862 5863To create a passthrough TPM use the following two options: 5864@example 5865-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 5866@end example 5867Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by 5868@code{tpmdev=tpm0} in the device option. 5869 5870@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 5871 5872(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 5873chardev backend. 5874 5875@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 5876 5877To create a TPM emulator backend device with chardev socket backend: 5878@example 5879 5880-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 5881 5882@end example 5883 5884ETEXI 5885SRST 5886The general form of a TPM device option is: 5887 5888``-tpmdev backend,id=id[,options]`` 5889 The specific backend type will determine the applicable options. The 5890 ``-tpmdev`` option creates the TPM backend and requires a 5891 ``-device`` option that specifies the TPM frontend interface model. 5892 5893 Use ``-tpmdev help`` to print all available TPM backend types. 5894 5895The available backends are: 5896 5897``-tpmdev passthrough,id=id,path=path,cancel-path=cancel-path`` 5898 (Linux-host only) Enable access to the host's TPM using the 5899 passthrough driver. 5900 5901 ``path`` specifies the path to the host's TPM device, i.e., on a 5902 Linux host this would be ``/dev/tpm0``. ``path`` is optional and by 5903 default ``/dev/tpm0`` is used. 5904 5905 ``cancel-path`` specifies the path to the host TPM device's sysfs 5906 entry allowing for cancellation of an ongoing TPM command. 5907 ``cancel-path`` is optional and by default QEMU will search for the 5908 sysfs entry to use. 5909 5910 Some notes about using the host's TPM with the passthrough driver: 5911 5912 The TPM device accessed by the passthrough driver must not be used 5913 by any other application on the host. 5914 5915 Since the host's firmware (BIOS/UEFI) has already initialized the 5916 TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize 5917 the TPM again and may therefore not show a TPM-specific menu that 5918 would otherwise allow the user to configure the TPM, e.g., allow the 5919 user to enable/disable or activate/deactivate the TPM. Further, if 5920 TPM ownership is released from within a VM then the host's TPM will 5921 get disabled and deactivated. To enable and activate the TPM again 5922 afterwards, the host has to be rebooted and the user is required to 5923 enter the firmware's menu to enable and activate the TPM. If the TPM 5924 is left disabled and/or deactivated most TPM commands will fail. 5925 5926 To create a passthrough TPM use the following two options: 5927 5928 :: 5929 5930 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 5931 5932 Note that the ``-tpmdev`` id is ``tpm0`` and is referenced by 5933 ``tpmdev=tpm0`` in the device option. 5934 5935``-tpmdev emulator,id=id,chardev=dev`` 5936 (Linux-host only) Enable access to a TPM emulator using Unix domain 5937 socket based chardev backend. 5938 5939 ``chardev`` specifies the unique ID of a character device backend 5940 that provides connection to the software TPM server. 5941 5942 To create a TPM emulator backend device with chardev socket backend: 5943 5944 :: 5945 5946 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 5947ERST 5948 5949STEXI 5950@end table 5951ETEXI 5952DEFHEADING() 5953 5954#endif 5955 5956DEFHEADING(Linux/Multiboot boot specific:) 5957STEXI 5958 5959When using these options, you can use a given Linux or Multiboot 5960kernel without installing it in the disk image. It can be useful 5961for easier testing of various kernels. 5962 5963@table @option 5964ETEXI 5965SRST 5966When using these options, you can use a given Linux or Multiboot kernel 5967without installing it in the disk image. It can be useful for easier 5968testing of various kernels. 5969 5970 5971ERST 5972 5973DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 5974 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 5975STEXI 5976@item -kernel @var{bzImage} 5977@findex -kernel 5978Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel 5979or in multiboot format. 5980ETEXI 5981SRST 5982``-kernel bzImage`` 5983 Use bzImage as kernel image. The kernel can be either a Linux kernel 5984 or in multiboot format. 5985ERST 5986 5987DEF("append", HAS_ARG, QEMU_OPTION_append, \ 5988 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 5989STEXI 5990@item -append @var{cmdline} 5991@findex -append 5992Use @var{cmdline} as kernel command line 5993ETEXI 5994SRST 5995``-append cmdline`` 5996 Use cmdline as kernel command line 5997ERST 5998 5999DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 6000 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 6001STEXI 6002@item -initrd @var{file} 6003@findex -initrd 6004Use @var{file} as initial ram disk. 6005 6006@item -initrd "@var{file1} arg=foo,@var{file2}" 6007 6008This syntax is only available with multiboot. 6009 6010Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 6011first module. 6012ETEXI 6013SRST 6014``-initrd file`` 6015 Use file as initial ram disk. 6016 6017``-initrd "file1 arg=foo,file2"`` 6018 This syntax is only available with multiboot. 6019 6020 Use file1 and file2 as modules and pass arg=foo as parameter to the 6021 first module. 6022ERST 6023 6024DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 6025 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 6026STEXI 6027@item -dtb @var{file} 6028@findex -dtb 6029Use @var{file} as a device tree binary (dtb) image and pass it to the kernel 6030on boot. 6031ETEXI 6032SRST 6033``-dtb file`` 6034 Use file as a device tree binary (dtb) image and pass it to the 6035 kernel on boot. 6036ERST 6037 6038STEXI 6039@end table 6040ETEXI 6041DEFHEADING() 6042 6043DEFHEADING(Debug/Expert options:) 6044STEXI 6045@table @option 6046ETEXI 6047 6048DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 6049 "-fw_cfg [name=]<name>,file=<file>\n" 6050 " add named fw_cfg entry with contents from file\n" 6051 "-fw_cfg [name=]<name>,string=<str>\n" 6052 " add named fw_cfg entry with contents from string\n", 6053 QEMU_ARCH_ALL) 6054STEXI 6055 6056@item -fw_cfg [name=]@var{name},file=@var{file} 6057@findex -fw_cfg 6058Add named fw_cfg entry with contents from file @var{file}. 6059 6060@item -fw_cfg [name=]@var{name},string=@var{str} 6061Add named fw_cfg entry with contents from string @var{str}. 6062 6063The terminating NUL character of the contents of @var{str} will not be 6064included as part of the fw_cfg item data. To insert contents with 6065embedded NUL characters, you have to use the @var{file} parameter. 6066 6067The fw_cfg entries are passed by QEMU through to the guest. 6068 6069Example: 6070@example 6071 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 6072@end example 6073creates an fw_cfg entry named opt/com.mycompany/blob with contents 6074from ./my_blob.bin. 6075 6076ETEXI 6077SRST 6078``-fw_cfg [name=]name,file=file`` 6079 Add named fw\_cfg entry with contents from file file. 6080 6081``-fw_cfg [name=]name,string=str`` 6082 Add named fw\_cfg entry with contents from string str. 6083 6084 The terminating NUL character of the contents of str will not be 6085 included as part of the fw\_cfg item data. To insert contents with 6086 embedded NUL characters, you have to use the file parameter. 6087 6088 The fw\_cfg entries are passed by QEMU through to the guest. 6089 6090 Example: 6091 6092 :: 6093 6094 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 6095 6096 creates an fw\_cfg entry named opt/com.mycompany/blob with contents 6097 from ./my\_blob.bin. 6098ERST 6099 6100DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 6101 "-serial dev redirect the serial port to char device 'dev'\n", 6102 QEMU_ARCH_ALL) 6103STEXI 6104@item -serial @var{dev} 6105@findex -serial 6106Redirect the virtual serial port to host character device 6107@var{dev}. The default device is @code{vc} in graphical mode and 6108@code{stdio} in non graphical mode. 6109 6110This option can be used several times to simulate up to 4 serial 6111ports. 6112 6113Use @code{-serial none} to disable all serial ports. 6114 6115Available character devices are: 6116@table @option 6117@item vc[:@var{W}x@var{H}] 6118Virtual console. Optionally, a width and height can be given in pixel with 6119@example 6120vc:800x600 6121@end example 6122It is also possible to specify width or height in characters: 6123@example 6124vc:80Cx24C 6125@end example 6126@item pty 6127[Linux only] Pseudo TTY (a new PTY is automatically allocated) 6128@item none 6129No device is allocated. 6130@item null 6131void device 6132@item chardev:@var{id} 6133Use a named character device defined with the @code{-chardev} option. 6134@item /dev/XXX 6135[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 6136parameters are set according to the emulated ones. 6137@item /dev/parport@var{N} 6138[Linux only, parallel port only] Use host parallel port 6139@var{N}. Currently SPP and EPP parallel port features can be used. 6140@item file:@var{filename} 6141Write output to @var{filename}. No character can be read. 6142@item stdio 6143[Unix only] standard input/output 6144@item pipe:@var{filename} 6145name pipe @var{filename} 6146@item COM@var{n} 6147[Windows only] Use host serial port @var{n} 6148@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 6149This implements UDP Net Console. 6150When @var{remote_host} or @var{src_ip} are not specified 6151they default to @code{0.0.0.0}. 6152When not using a specified @var{src_port} a random port is automatically chosen. 6153 6154If you just want a simple readonly console you can use @code{netcat} or 6155@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 6156@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 6157will appear in the netconsole session. 6158 6159If you plan to send characters back via netconsole or you want to stop 6160and start QEMU a lot of times, you should have QEMU use the same 6161source port each time by using something like @code{-serial 6162udp::4555@@:4556} to QEMU. Another approach is to use a patched 6163version of netcat which can listen to a TCP port and send and receive 6164characters via udp. If you have a patched version of netcat which 6165activates telnet remote echo and single char transfer, then you can 6166use the following options to set up a netcat redirector to allow 6167telnet on port 5555 to access the QEMU port. 6168@table @code 6169@item QEMU Options: 6170-serial udp::4555@@:4556 6171@item netcat options: 6172-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 6173@item telnet options: 6174localhost 5555 6175@end table 6176 6177@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 6178The TCP Net Console has two modes of operation. It can send the serial 6179I/O to a location or wait for a connection from a location. By default 6180the TCP Net Console is sent to @var{host} at the @var{port}. If you use 6181the @var{server} option QEMU will wait for a client socket application 6182to connect to the port before continuing, unless the @code{nowait} 6183option was specified. The @code{nodelay} option disables the Nagle buffering 6184algorithm. The @code{reconnect} option only applies if @var{noserver} is 6185set, if the connection goes down it will attempt to reconnect at the 6186given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 6187one TCP connection at a time is accepted. You can use @code{telnet} to 6188connect to the corresponding character device. 6189@table @code 6190@item Example to send tcp console to 192.168.0.2 port 4444 6191-serial tcp:192.168.0.2:4444 6192@item Example to listen and wait on port 4444 for connection 6193-serial tcp::4444,server 6194@item Example to not wait and listen on ip 192.168.0.100 port 4444 6195-serial tcp:192.168.0.100:4444,server,nowait 6196@end table 6197 6198@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 6199The telnet protocol is used instead of raw tcp sockets. The options 6200work the same as if you had specified @code{-serial tcp}. The 6201difference is that the port acts like a telnet server or client using 6202telnet option negotiation. This will also allow you to send the 6203MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 6204sequence. Typically in unix telnet you do it with Control-] and then 6205type "send break" followed by pressing the enter key. 6206 6207@item websocket:@var{host}:@var{port},server[,nowait][,nodelay] 6208The WebSocket protocol is used instead of raw tcp socket. The port acts as 6209a WebSocket server. Client mode is not supported. 6210 6211@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 6212A unix domain socket is used instead of a tcp socket. The option works the 6213same as if you had specified @code{-serial tcp} except the unix domain socket 6214@var{path} is used for connections. 6215 6216@item mon:@var{dev_string} 6217This is a special option to allow the monitor to be multiplexed onto 6218another serial port. The monitor is accessed with key sequence of 6219@key{Control-a} and then pressing @key{c}. 6220@var{dev_string} should be any one of the serial devices specified 6221above. An example to multiplex the monitor onto a telnet server 6222listening on port 4444 would be: 6223@table @code 6224@item -serial mon:telnet::4444,server,nowait 6225@end table 6226When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 6227QEMU any more but will be passed to the guest instead. 6228 6229@item braille 6230Braille device. This will use BrlAPI to display the braille output on a real 6231or fake device. 6232 6233@item msmouse 6234Three button serial mouse. Configure the guest to use Microsoft protocol. 6235@end table 6236ETEXI 6237SRST 6238``-serial dev`` 6239 Redirect the virtual serial port to host character device dev. The 6240 default device is ``vc`` in graphical mode and ``stdio`` in non 6241 graphical mode. 6242 6243 This option can be used several times to simulate up to 4 serial 6244 ports. 6245 6246 Use ``-serial none`` to disable all serial ports. 6247 6248 Available character devices are: 6249 6250 ``vc[:WxH]`` 6251 Virtual console. Optionally, a width and height can be given in 6252 pixel with 6253 6254 :: 6255 6256 vc:800x600 6257 6258 It is also possible to specify width or height in characters: 6259 6260 :: 6261 6262 vc:80Cx24C 6263 6264 ``pty`` 6265 [Linux only] Pseudo TTY (a new PTY is automatically allocated) 6266 6267 ``none`` 6268 No device is allocated. 6269 6270 ``null`` 6271 void device 6272 6273 ``chardev:id`` 6274 Use a named character device defined with the ``-chardev`` 6275 option. 6276 6277 ``/dev/XXX`` 6278 [Linux only] Use host tty, e.g. ``/dev/ttyS0``. The host serial 6279 port parameters are set according to the emulated ones. 6280 6281 ``/dev/parportN`` 6282 [Linux only, parallel port only] Use host parallel port N. 6283 Currently SPP and EPP parallel port features can be used. 6284 6285 ``file:filename`` 6286 Write output to filename. No character can be read. 6287 6288 ``stdio`` 6289 [Unix only] standard input/output 6290 6291 ``pipe:filename`` 6292 name pipe filename 6293 6294 ``COMn`` 6295 [Windows only] Use host serial port n 6296 6297 ``udp:[remote_host]:remote_port[@[src_ip]:src_port]`` 6298 This implements UDP Net Console. When remote\_host or src\_ip 6299 are not specified they default to ``0.0.0.0``. When not using a 6300 specified src\_port a random port is automatically chosen. 6301 6302 If you just want a simple readonly console you can use 6303 ``netcat`` or ``nc``, by starting QEMU with: 6304 ``-serial udp::4555`` and nc as: ``nc -u -l -p 4555``. Any time 6305 QEMU writes something to that port it will appear in the 6306 netconsole session. 6307 6308 If you plan to send characters back via netconsole or you want 6309 to stop and start QEMU a lot of times, you should have QEMU use 6310 the same source port each time by using something like ``-serial 6311 udp::4555@:4556`` to QEMU. Another approach is to use a patched 6312 version of netcat which can listen to a TCP port and send and 6313 receive characters via udp. If you have a patched version of 6314 netcat which activates telnet remote echo and single char 6315 transfer, then you can use the following options to set up a 6316 netcat redirector to allow telnet on port 5555 to access the 6317 QEMU port. 6318 6319 ``QEMU Options:`` 6320 -serial udp::4555@:4556 6321 6322 ``netcat options:`` 6323 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 6324 6325 ``telnet options:`` 6326 localhost 5555 6327 6328 ``tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]`` 6329 The TCP Net Console has two modes of operation. It can send the 6330 serial I/O to a location or wait for a connection from a 6331 location. By default the TCP Net Console is sent to host at the 6332 port. If you use the server option QEMU will wait for a client 6333 socket application to connect to the port before continuing, 6334 unless the ``nowait`` option was specified. The ``nodelay`` 6335 option disables the Nagle buffering algorithm. The ``reconnect`` 6336 option only applies if noserver is set, if the connection goes 6337 down it will attempt to reconnect at the given interval. If host 6338 is omitted, 0.0.0.0 is assumed. Only one TCP connection at a 6339 time is accepted. You can use ``telnet`` to connect to the 6340 corresponding character device. 6341 6342 ``Example to send tcp console to 192.168.0.2 port 4444`` 6343 -serial tcp:192.168.0.2:4444 6344 6345 ``Example to listen and wait on port 4444 for connection`` 6346 -serial tcp::4444,server 6347 6348 ``Example to not wait and listen on ip 192.168.0.100 port 4444`` 6349 -serial tcp:192.168.0.100:4444,server,nowait 6350 6351 ``telnet:host:port[,server][,nowait][,nodelay]`` 6352 The telnet protocol is used instead of raw tcp sockets. The 6353 options work the same as if you had specified ``-serial tcp``. 6354 The difference is that the port acts like a telnet server or 6355 client using telnet option negotiation. This will also allow you 6356 to send the MAGIC\_SYSRQ sequence if you use a telnet that 6357 supports sending the break sequence. Typically in unix telnet 6358 you do it with Control-] and then type "send break" followed by 6359 pressing the enter key. 6360 6361 ``websocket:host:port,server[,nowait][,nodelay]`` 6362 The WebSocket protocol is used instead of raw tcp socket. The 6363 port acts as a WebSocket server. Client mode is not supported. 6364 6365 ``unix:path[,server][,nowait][,reconnect=seconds]`` 6366 A unix domain socket is used instead of a tcp socket. The option 6367 works the same as if you had specified ``-serial tcp`` except 6368 the unix domain socket path is used for connections. 6369 6370 ``mon:dev_string`` 6371 This is a special option to allow the monitor to be multiplexed 6372 onto another serial port. The monitor is accessed with key 6373 sequence of Control-a and then pressing c. dev\_string should be 6374 any one of the serial devices specified above. An example to 6375 multiplex the monitor onto a telnet server listening on port 6376 4444 would be: 6377 6378 ``-serial mon:telnet::4444,server,nowait`` 6379 6380 When the monitor is multiplexed to stdio in this way, Ctrl+C 6381 will not terminate QEMU any more but will be passed to the guest 6382 instead. 6383 6384 ``braille`` 6385 Braille device. This will use BrlAPI to display the braille 6386 output on a real or fake device. 6387 6388 ``msmouse`` 6389 Three button serial mouse. Configure the guest to use Microsoft 6390 protocol. 6391ERST 6392 6393DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 6394 "-parallel dev redirect the parallel port to char device 'dev'\n", 6395 QEMU_ARCH_ALL) 6396STEXI 6397@item -parallel @var{dev} 6398@findex -parallel 6399Redirect the virtual parallel port to host device @var{dev} (same 6400devices as the serial port). On Linux hosts, @file{/dev/parportN} can 6401be used to use hardware devices connected on the corresponding host 6402parallel port. 6403 6404This option can be used several times to simulate up to 3 parallel 6405ports. 6406 6407Use @code{-parallel none} to disable all parallel ports. 6408ETEXI 6409SRST 6410``-parallel dev`` 6411 Redirect the virtual parallel port to host device dev (same devices 6412 as the serial port). On Linux hosts, ``/dev/parportN`` can be used 6413 to use hardware devices connected on the corresponding host parallel 6414 port. 6415 6416 This option can be used several times to simulate up to 3 parallel 6417 ports. 6418 6419 Use ``-parallel none`` to disable all parallel ports. 6420ERST 6421 6422DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 6423 "-monitor dev redirect the monitor to char device 'dev'\n", 6424 QEMU_ARCH_ALL) 6425STEXI 6426@item -monitor @var{dev} 6427@findex -monitor 6428Redirect the monitor to host device @var{dev} (same devices as the 6429serial port). 6430The default device is @code{vc} in graphical mode and @code{stdio} in 6431non graphical mode. 6432Use @code{-monitor none} to disable the default monitor. 6433ETEXI 6434SRST 6435``-monitor dev`` 6436 Redirect the monitor to host device dev (same devices as the serial 6437 port). The default device is ``vc`` in graphical mode and ``stdio`` 6438 in non graphical mode. Use ``-monitor none`` to disable the default 6439 monitor. 6440ERST 6441DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 6442 "-qmp dev like -monitor but opens in 'control' mode\n", 6443 QEMU_ARCH_ALL) 6444STEXI 6445@item -qmp @var{dev} 6446@findex -qmp 6447Like -monitor but opens in 'control' mode. 6448ETEXI 6449SRST 6450``-qmp dev`` 6451 Like -monitor but opens in 'control' mode. 6452ERST 6453DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 6454 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 6455 QEMU_ARCH_ALL) 6456STEXI 6457@item -qmp-pretty @var{dev} 6458@findex -qmp-pretty 6459Like -qmp but uses pretty JSON formatting. 6460ETEXI 6461SRST 6462``-qmp-pretty dev`` 6463 Like -qmp but uses pretty JSON formatting. 6464ERST 6465 6466DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 6467 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 6468STEXI 6469@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 6470@findex -mon 6471Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 6472easing human reading and debugging. 6473ETEXI 6474SRST 6475``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]`` 6476 Setup monitor on chardev name. ``pretty`` turns on JSON pretty 6477 printing easing human reading and debugging. 6478ERST 6479 6480DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 6481 "-debugcon dev redirect the debug console to char device 'dev'\n", 6482 QEMU_ARCH_ALL) 6483STEXI 6484@item -debugcon @var{dev} 6485@findex -debugcon 6486Redirect the debug console to host device @var{dev} (same devices as the 6487serial port). The debug console is an I/O port which is typically port 64880xe9; writing to that I/O port sends output to this device. 6489The default device is @code{vc} in graphical mode and @code{stdio} in 6490non graphical mode. 6491ETEXI 6492SRST 6493``-debugcon dev`` 6494 Redirect the debug console to host device dev (same devices as the 6495 serial port). The debug console is an I/O port which is typically 6496 port 0xe9; writing to that I/O port sends output to this device. The 6497 default device is ``vc`` in graphical mode and ``stdio`` in non 6498 graphical mode. 6499ERST 6500 6501DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 6502 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 6503STEXI 6504@item -pidfile @var{file} 6505@findex -pidfile 6506Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 6507from a script. 6508ETEXI 6509SRST 6510``-pidfile file`` 6511 Store the QEMU process PID in file. It is useful if you launch QEMU 6512 from a script. 6513ERST 6514 6515DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 6516 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 6517STEXI 6518@item -singlestep 6519@findex -singlestep 6520Run the emulation in single step mode. 6521ETEXI 6522SRST 6523``-singlestep`` 6524 Run the emulation in single step mode. 6525ERST 6526 6527DEF("preconfig", 0, QEMU_OPTION_preconfig, \ 6528 "--preconfig pause QEMU before machine is initialized (experimental)\n", 6529 QEMU_ARCH_ALL) 6530STEXI 6531@item --preconfig 6532@findex --preconfig 6533Pause QEMU for interactive configuration before the machine is created, 6534which allows querying and configuring properties that will affect 6535machine initialization. Use QMP command 'x-exit-preconfig' to exit 6536the preconfig state and move to the next state (i.e. run guest if -S 6537isn't used or pause the second time if -S is used). This option is 6538experimental. 6539ETEXI 6540SRST 6541``--preconfig`` 6542 Pause QEMU for interactive configuration before the machine is 6543 created, which allows querying and configuring properties that will 6544 affect machine initialization. Use QMP command 'x-exit-preconfig' to 6545 exit the preconfig state and move to the next state (i.e. run guest 6546 if -S isn't used or pause the second time if -S is used). This 6547 option is experimental. 6548ERST 6549 6550DEF("S", 0, QEMU_OPTION_S, \ 6551 "-S freeze CPU at startup (use 'c' to start execution)\n", 6552 QEMU_ARCH_ALL) 6553STEXI 6554@item -S 6555@findex -S 6556Do not start CPU at startup (you must type 'c' in the monitor). 6557ETEXI 6558SRST 6559``-S`` 6560 Do not start CPU at startup (you must type 'c' in the monitor). 6561ERST 6562 6563DEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 6564 "-realtime [mlock=on|off]\n" 6565 " run qemu with realtime features\n" 6566 " mlock=on|off controls mlock support (default: on)\n", 6567 QEMU_ARCH_ALL) 6568STEXI 6569@item -realtime mlock=on|off 6570@findex -realtime 6571Run qemu with realtime features. 6572mlocking qemu and guest memory can be enabled via @option{mlock=on} 6573(enabled by default). 6574ETEXI 6575SRST 6576``-realtime mlock=on|off`` 6577 Run qemu with realtime features. mlocking qemu and guest memory can 6578 be enabled via ``mlock=on`` (enabled by default). 6579ERST 6580 6581DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, 6582 "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" 6583 " run qemu with overcommit hints\n" 6584 " mem-lock=on|off controls memory lock support (default: off)\n" 6585 " cpu-pm=on|off controls cpu power management (default: off)\n", 6586 QEMU_ARCH_ALL) 6587STEXI 6588@item -overcommit mem-lock=on|off 6589@item -overcommit cpu-pm=on|off 6590@findex -overcommit 6591Run qemu with hints about host resource overcommit. The default is 6592to assume that host overcommits all resources. 6593 6594Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled 6595by default). This works when host memory is not overcommitted and reduces the 6596worst-case latency for guest. This is equivalent to @option{realtime}. 6597 6598Guest ability to manage power state of host cpus (increasing latency for other 6599processes on the same host cpu, but decreasing latency for guest) can be 6600enabled via @option{cpu-pm=on} (disabled by default). This works best when 6601host CPU is not overcommitted. When used, host estimates of CPU cycle and power 6602utilization will be incorrect, not taking into account guest idle time. 6603ETEXI 6604SRST 6605``-overcommit mem-lock=on|off`` 6606 \ 6607``-overcommit cpu-pm=on|off`` 6608 Run qemu with hints about host resource overcommit. The default is 6609 to assume that host overcommits all resources. 6610 6611 Locking qemu and guest memory can be enabled via ``mem-lock=on`` 6612 (disabled by default). This works when host memory is not 6613 overcommitted and reduces the worst-case latency for guest. This is 6614 equivalent to ``realtime``. 6615 6616 Guest ability to manage power state of host cpus (increasing latency 6617 for other processes on the same host cpu, but decreasing latency for 6618 guest) can be enabled via ``cpu-pm=on`` (disabled by default). This 6619 works best when host CPU is not overcommitted. When used, host 6620 estimates of CPU cycle and power utilization will be incorrect, not 6621 taking into account guest idle time. 6622ERST 6623 6624DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 6625 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 6626STEXI 6627@item -gdb @var{dev} 6628@findex -gdb 6629Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 6630connections will likely be TCP-based, but also UDP, pseudo TTY, or even 6631stdio are reasonable use case. The latter is allowing to start QEMU from 6632within gdb and establish the connection via a pipe: 6633@example 6634(gdb) target remote | exec @value{qemu_system} -gdb stdio ... 6635@end example 6636ETEXI 6637SRST 6638``-gdb dev`` 6639 Wait for gdb connection on device dev (see 6640 :ref:`gdb_005fusage`). Typical connections will likely be 6641 TCP-based, but also UDP, pseudo TTY, or even stdio are reasonable 6642 use case. The latter is allowing to start QEMU from within gdb and 6643 establish the connection via a pipe: 6644 6645 .. parsed-literal:: 6646 6647 (gdb) target remote | exec |qemu_system| -gdb stdio ... 6648ERST 6649 6650DEF("s", 0, QEMU_OPTION_s, \ 6651 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 6652 QEMU_ARCH_ALL) 6653STEXI 6654@item -s 6655@findex -s 6656Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 6657(@pxref{gdb_usage}). 6658ETEXI 6659SRST 6660``-s`` 6661 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 6662 (see :ref:`gdb_005fusage`). 6663ERST 6664 6665DEF("d", HAS_ARG, QEMU_OPTION_d, \ 6666 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 6667 QEMU_ARCH_ALL) 6668STEXI 6669@item -d @var{item1}[,...] 6670@findex -d 6671Enable logging of specified items. Use '-d help' for a list of log items. 6672ETEXI 6673SRST 6674``-d item1[,...]`` 6675 Enable logging of specified items. Use '-d help' for a list of log 6676 items. 6677ERST 6678 6679DEF("D", HAS_ARG, QEMU_OPTION_D, \ 6680 "-D logfile output log to logfile (default stderr)\n", 6681 QEMU_ARCH_ALL) 6682STEXI 6683@item -D @var{logfile} 6684@findex -D 6685Output log in @var{logfile} instead of to stderr 6686ETEXI 6687SRST 6688``-D logfile`` 6689 Output log in logfile instead of to stderr 6690ERST 6691 6692DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 6693 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 6694 QEMU_ARCH_ALL) 6695STEXI 6696@item -dfilter @var{range1}[,...] 6697@findex -dfilter 6698Filter debug output to that relevant to a range of target addresses. The filter 6699spec can be either @var{start}+@var{size}, @var{start}-@var{size} or 6700@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 6701addresses and sizes required. For example: 6702@example 6703 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 6704@end example 6705Will dump output for any code in the 0x1000 sized block starting at 0x8000 and 6706the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 6707block starting at 0xffffffc00005f000. 6708ETEXI 6709SRST 6710``-dfilter range1[,...]`` 6711 Filter debug output to that relevant to a range of target addresses. 6712 The filter spec can be either start+size, start-size or start..end 6713 where start end and size are the addresses and sizes required. For 6714 example: 6715 6716 :: 6717 6718 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 6719 6720 Will dump output for any code in the 0x1000 sized block starting at 6721 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and 6722 another 0x1000 sized block starting at 0xffffffc00005f000. 6723ERST 6724 6725DEF("seed", HAS_ARG, QEMU_OPTION_seed, \ 6726 "-seed number seed the pseudo-random number generator\n", 6727 QEMU_ARCH_ALL) 6728STEXI 6729@item -seed @var{number} 6730@findex -seed 6731Force the guest to use a deterministic pseudo-random number generator, seeded 6732with @var{number}. This does not affect crypto routines within the host. 6733ETEXI 6734SRST 6735``-seed number`` 6736 Force the guest to use a deterministic pseudo-random number 6737 generator, seeded with number. This does not affect crypto routines 6738 within the host. 6739ERST 6740 6741DEF("L", HAS_ARG, QEMU_OPTION_L, \ 6742 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 6743 QEMU_ARCH_ALL) 6744STEXI 6745@item -L @var{path} 6746@findex -L 6747Set the directory for the BIOS, VGA BIOS and keymaps. 6748 6749To list all the data directories, use @code{-L help}. 6750ETEXI 6751SRST 6752``-L path`` 6753 Set the directory for the BIOS, VGA BIOS and keymaps. 6754 6755 To list all the data directories, use ``-L help``. 6756ERST 6757 6758DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 6759 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 6760STEXI 6761@item -bios @var{file} 6762@findex -bios 6763Set the filename for the BIOS. 6764ETEXI 6765SRST 6766``-bios file`` 6767 Set the filename for the BIOS. 6768ERST 6769 6770DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 6771 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 6772STEXI 6773@item -enable-kvm 6774@findex -enable-kvm 6775Enable KVM full virtualization support. This option is only available 6776if KVM support is enabled when compiling. 6777ETEXI 6778SRST 6779``-enable-kvm`` 6780 Enable KVM full virtualization support. This option is only 6781 available if KVM support is enabled when compiling. 6782ERST 6783 6784DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 6785 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 6786DEF("xen-attach", 0, QEMU_OPTION_xen_attach, 6787 "-xen-attach attach to existing xen domain\n" 6788 " libxl will use this when starting QEMU\n", 6789 QEMU_ARCH_ALL) 6790DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 6791 "-xen-domid-restrict restrict set of available xen operations\n" 6792 " to specified domain id. (Does not affect\n" 6793 " xenpv machine type).\n", 6794 QEMU_ARCH_ALL) 6795STEXI 6796@item -xen-domid @var{id} 6797@findex -xen-domid 6798Specify xen guest domain @var{id} (XEN only). 6799@item -xen-attach 6800@findex -xen-attach 6801Attach to existing xen domain. 6802libxl will use this when starting QEMU (XEN only). 6803@findex -xen-domid-restrict 6804Restrict set of available xen operations to specified domain id (XEN only). 6805ETEXI 6806SRST 6807``-xen-domid id`` 6808 Specify xen guest domain id (XEN only). 6809 6810``-xen-attach`` 6811 Attach to existing xen domain. libxl will use this when starting 6812 QEMU (XEN only). Restrict set of available xen operations to 6813 specified domain id (XEN only). 6814ERST 6815 6816DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 6817 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 6818STEXI 6819@item -no-reboot 6820@findex -no-reboot 6821Exit instead of rebooting. 6822ETEXI 6823SRST 6824``-no-reboot`` 6825 Exit instead of rebooting. 6826ERST 6827 6828DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 6829 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 6830STEXI 6831@item -no-shutdown 6832@findex -no-shutdown 6833Don't exit QEMU on guest shutdown, but instead only stop the emulation. 6834This allows for instance switching to monitor to commit changes to the 6835disk image. 6836ETEXI 6837SRST 6838``-no-shutdown`` 6839 Don't exit QEMU on guest shutdown, but instead only stop the 6840 emulation. This allows for instance switching to monitor to commit 6841 changes to the disk image. 6842ERST 6843 6844DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 6845 "-loadvm [tag|id]\n" \ 6846 " start right away with a saved state (loadvm in monitor)\n", 6847 QEMU_ARCH_ALL) 6848STEXI 6849@item -loadvm @var{file} 6850@findex -loadvm 6851Start right away with a saved state (@code{loadvm} in monitor) 6852ETEXI 6853SRST 6854``-loadvm file`` 6855 Start right away with a saved state (``loadvm`` in monitor) 6856ERST 6857 6858#ifndef _WIN32 6859DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 6860 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 6861#endif 6862STEXI 6863@item -daemonize 6864@findex -daemonize 6865Daemonize the QEMU process after initialization. QEMU will not detach from 6866standard IO until it is ready to receive connections on any of its devices. 6867This option is a useful way for external programs to launch QEMU without having 6868to cope with initialization race conditions. 6869ETEXI 6870SRST 6871``-daemonize`` 6872 Daemonize the QEMU process after initialization. QEMU will not 6873 detach from standard IO until it is ready to receive connections on 6874 any of its devices. This option is a useful way for external 6875 programs to launch QEMU without having to cope with initialization 6876 race conditions. 6877ERST 6878 6879DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 6880 "-option-rom rom load a file, rom, into the option ROM space\n", 6881 QEMU_ARCH_ALL) 6882STEXI 6883@item -option-rom @var{file} 6884@findex -option-rom 6885Load the contents of @var{file} as an option ROM. 6886This option is useful to load things like EtherBoot. 6887ETEXI 6888SRST 6889``-option-rom file`` 6890 Load the contents of file as an option ROM. This option is useful to 6891 load things like EtherBoot. 6892ERST 6893 6894DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 6895 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 6896 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 6897 QEMU_ARCH_ALL) 6898 6899STEXI 6900 6901@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew] 6902@findex -rtc 6903Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 6904UTC or local time, respectively. @code{localtime} is required for correct date in 6905MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the 6906format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 6907 6908By default the RTC is driven by the host system time. This allows using of the 6909RTC as accurate reference clock inside the guest, specifically if the host 6910time is smoothly following an accurate external reference clock, e.g. via NTP. 6911If you want to isolate the guest time from the host, you can set @option{clock} 6912to @code{rt} instead, which provides a host monotonic clock if host support it. 6913To even prevent the RTC from progressing during suspension, you can set @option{clock} 6914to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in 6915icount mode in order to preserve determinism; however, note that in icount mode 6916the speed of the virtual clock is variable and can in general differ from the 6917host clock. 6918 6919Enable @option{driftfix} (i386 targets only) if you experience time drift problems, 6920specifically with Windows' ACPI HAL. This option will try to figure out how 6921many timer interrupts were not processed by the Windows guest and will 6922re-inject them. 6923ETEXI 6924SRST 6925``-rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]`` 6926 Specify ``base`` as ``utc`` or ``localtime`` to let the RTC start at 6927 the current UTC or local time, respectively. ``localtime`` is 6928 required for correct date in MS-DOS or Windows. To start at a 6929 specific point in time, provide datetime in the format 6930 ``2006-06-17T16:01:21`` or ``2006-06-17``. The default base is UTC. 6931 6932 By default the RTC is driven by the host system time. This allows 6933 using of the RTC as accurate reference clock inside the guest, 6934 specifically if the host time is smoothly following an accurate 6935 external reference clock, e.g. via NTP. If you want to isolate the 6936 guest time from the host, you can set ``clock`` to ``rt`` instead, 6937 which provides a host monotonic clock if host support it. To even 6938 prevent the RTC from progressing during suspension, you can set 6939 ``clock`` to ``vm`` (virtual clock). '\ ``clock=vm``\ ' is 6940 recommended especially in icount mode in order to preserve 6941 determinism; however, note that in icount mode the speed of the 6942 virtual clock is variable and can in general differ from the host 6943 clock. 6944 6945 Enable ``driftfix`` (i386 targets only) if you experience time drift 6946 problems, specifically with Windows' ACPI HAL. This option will try 6947 to figure out how many timer interrupts were not processed by the 6948 Windows guest and will re-inject them. 6949ERST 6950 6951DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 6952 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 6953 " enable virtual instruction counter with 2^N clock ticks per\n" \ 6954 " instruction, enable aligning the host and virtual clocks\n" \ 6955 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 6956STEXI 6957@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 6958@findex -icount 6959Enable virtual instruction counter. The virtual cpu will execute one 6960instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 6961then the virtual cpu speed will be automatically adjusted to keep virtual 6962time within a few seconds of real time. 6963 6964When the virtual cpu is sleeping, the virtual time will advance at default 6965speed unless @option{sleep=on|off} is specified. 6966With @option{sleep=on|off}, the virtual time will jump to the next timer deadline 6967instantly whenever the virtual cpu goes to sleep mode and will not advance 6968if no timer is enabled. This behavior give deterministic execution times from 6969the guest point of view. 6970 6971Note that while this option can give deterministic behavior, it does not 6972provide cycle accurate emulation. Modern CPUs contain superscalar out of 6973order cores with complex cache hierarchies. The number of instructions 6974executed often has little or no correlation with actual performance. 6975 6976@option{align=on} will activate the delay algorithm which will try 6977to synchronise the host clock and the virtual clock. The goal is to 6978have a guest running at the real frequency imposed by the shift option. 6979Whenever the guest clock is behind the host clock and if 6980@option{align=on} is specified then we print a message to the user 6981to inform about the delay. 6982Currently this option does not work when @option{shift} is @code{auto}. 6983Note: The sync algorithm will work for those shift values for which 6984the guest clock runs ahead of the host clock. Typically this happens 6985when the shift value is high (how high depends on the host machine). 6986 6987When @option{rr} option is specified deterministic record/replay is enabled. 6988Replay log is written into @var{filename} file in record mode and 6989read from this file in replay mode. 6990 6991Option rrsnapshot is used to create new vm snapshot named @var{snapshot} 6992at the start of execution recording. In replay mode this option is used 6993to load the initial VM state. 6994ETEXI 6995SRST 6996``-icount [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]`` 6997 Enable virtual instruction counter. The virtual cpu will execute one 6998 instruction every 2^N ns of virtual time. If ``auto`` is specified 6999 then the virtual cpu speed will be automatically adjusted to keep 7000 virtual time within a few seconds of real time. 7001 7002 When the virtual cpu is sleeping, the virtual time will advance at 7003 default speed unless ``sleep=on|off`` is specified. With 7004 ``sleep=on|off``, the virtual time will jump to the next timer 7005 deadline instantly whenever the virtual cpu goes to sleep mode and 7006 will not advance if no timer is enabled. This behavior give 7007 deterministic execution times from the guest point of view. 7008 7009 Note that while this option can give deterministic behavior, it does 7010 not provide cycle accurate emulation. Modern CPUs contain 7011 superscalar out of order cores with complex cache hierarchies. The 7012 number of instructions executed often has little or no correlation 7013 with actual performance. 7014 7015 ``align=on`` will activate the delay algorithm which will try to 7016 synchronise the host clock and the virtual clock. The goal is to 7017 have a guest running at the real frequency imposed by the shift 7018 option. Whenever the guest clock is behind the host clock and if 7019 ``align=on`` is specified then we print a message to the user to 7020 inform about the delay. Currently this option does not work when 7021 ``shift`` is ``auto``. Note: The sync algorithm will work for those 7022 shift values for which the guest clock runs ahead of the host clock. 7023 Typically this happens when the shift value is high (how high 7024 depends on the host machine). 7025 7026 When ``rr`` option is specified deterministic record/replay is 7027 enabled. Replay log is written into filename file in record mode and 7028 read from this file in replay mode. 7029 7030 Option rrsnapshot is used to create new vm snapshot named snapshot 7031 at the start of execution recording. In replay mode this option is 7032 used to load the initial VM state. 7033ERST 7034 7035DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 7036 "-watchdog model\n" \ 7037 " enable virtual hardware watchdog [default=none]\n", 7038 QEMU_ARCH_ALL) 7039STEXI 7040@item -watchdog @var{model} 7041@findex -watchdog 7042Create a virtual hardware watchdog device. Once enabled (by a guest 7043action), the watchdog must be periodically polled by an agent inside 7044the guest or else the guest will be restarted. Choose a model for 7045which your guest has drivers. 7046 7047The @var{model} is the model of hardware watchdog to emulate. Use 7048@code{-watchdog help} to list available hardware models. Only one 7049watchdog can be enabled for a guest. 7050 7051The following models may be available: 7052@table @option 7053@item ib700 7054iBASE 700 is a very simple ISA watchdog with a single timer. 7055@item i6300esb 7056Intel 6300ESB I/O controller hub is a much more featureful PCI-based 7057dual-timer watchdog. 7058@item diag288 7059A virtual watchdog for s390x backed by the diagnose 288 hypercall 7060(currently KVM only). 7061@end table 7062ETEXI 7063SRST 7064``-watchdog model`` 7065 Create a virtual hardware watchdog device. Once enabled (by a guest 7066 action), the watchdog must be periodically polled by an agent inside 7067 the guest or else the guest will be restarted. Choose a model for 7068 which your guest has drivers. 7069 7070 The model is the model of hardware watchdog to emulate. Use 7071 ``-watchdog help`` to list available hardware models. Only one 7072 watchdog can be enabled for a guest. 7073 7074 The following models may be available: 7075 7076 ``ib700`` 7077 iBASE 700 is a very simple ISA watchdog with a single timer. 7078 7079 ``i6300esb`` 7080 Intel 6300ESB I/O controller hub is a much more featureful 7081 PCI-based dual-timer watchdog. 7082 7083 ``diag288`` 7084 A virtual watchdog for s390x backed by the diagnose 288 7085 hypercall (currently KVM only). 7086ERST 7087 7088DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 7089 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 7090 " action when watchdog fires [default=reset]\n", 7091 QEMU_ARCH_ALL) 7092STEXI 7093@item -watchdog-action @var{action} 7094@findex -watchdog-action 7095 7096The @var{action} controls what QEMU will do when the watchdog timer 7097expires. 7098The default is 7099@code{reset} (forcefully reset the guest). 7100Other possible actions are: 7101@code{shutdown} (attempt to gracefully shutdown the guest), 7102@code{poweroff} (forcefully poweroff the guest), 7103@code{inject-nmi} (inject a NMI into the guest), 7104@code{pause} (pause the guest), 7105@code{debug} (print a debug message and continue), or 7106@code{none} (do nothing). 7107 7108Note that the @code{shutdown} action requires that the guest responds 7109to ACPI signals, which it may not be able to do in the sort of 7110situations where the watchdog would have expired, and thus 7111@code{-watchdog-action shutdown} is not recommended for production use. 7112 7113Examples: 7114 7115@table @code 7116@item -watchdog i6300esb -watchdog-action pause 7117@itemx -watchdog ib700 7118@end table 7119ETEXI 7120SRST 7121``-watchdog-action action`` 7122 The action controls what QEMU will do when the watchdog timer 7123 expires. The default is ``reset`` (forcefully reset the guest). 7124 Other possible actions are: ``shutdown`` (attempt to gracefully 7125 shutdown the guest), ``poweroff`` (forcefully poweroff the guest), 7126 ``inject-nmi`` (inject a NMI into the guest), ``pause`` (pause the 7127 guest), ``debug`` (print a debug message and continue), or ``none`` 7128 (do nothing). 7129 7130 Note that the ``shutdown`` action requires that the guest responds 7131 to ACPI signals, which it may not be able to do in the sort of 7132 situations where the watchdog would have expired, and thus 7133 ``-watchdog-action shutdown`` is not recommended for production use. 7134 7135 Examples: 7136 7137 ``-watchdog i6300esb -watchdog-action pause``; \ ``-watchdog ib700`` 7138 7139ERST 7140 7141DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 7142 "-echr chr set terminal escape character instead of ctrl-a\n", 7143 QEMU_ARCH_ALL) 7144STEXI 7145 7146@item -echr @var{numeric_ascii_value} 7147@findex -echr 7148Change the escape character used for switching to the monitor when using 7149monitor and serial sharing. The default is @code{0x01} when using the 7150@code{-nographic} option. @code{0x01} is equal to pressing 7151@code{Control-a}. You can select a different character from the ascii 7152control keys where 1 through 26 map to Control-a through Control-z. For 7153instance you could use the either of the following to change the escape 7154character to Control-t. 7155@table @code 7156@item -echr 0x14 7157@itemx -echr 20 7158@end table 7159ETEXI 7160SRST 7161``-echr numeric_ascii_value`` 7162 Change the escape character used for switching to the monitor when 7163 using monitor and serial sharing. The default is ``0x01`` when using 7164 the ``-nographic`` option. ``0x01`` is equal to pressing 7165 ``Control-a``. You can select a different character from the ascii 7166 control keys where 1 through 26 map to Control-a through Control-z. 7167 For instance you could use the either of the following to change the 7168 escape character to Control-t. 7169 7170 ``-echr 0x14``; \ ``-echr 20`` 7171 7172ERST 7173 7174DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 7175 "-show-cursor show cursor\n", QEMU_ARCH_ALL) 7176STEXI 7177@item -show-cursor 7178@findex -show-cursor 7179Show cursor. 7180ETEXI 7181SRST 7182``-show-cursor`` 7183 Show cursor. 7184ERST 7185 7186DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 7187 "-tb-size n set TB size\n", QEMU_ARCH_ALL) 7188STEXI 7189@item -tb-size @var{n} 7190@findex -tb-size 7191Set TCG translation block cache size. Deprecated, use @samp{-accel tcg,tb-size=@var{n}} 7192instead. 7193ETEXI 7194SRST 7195``-tb-size n`` 7196 Set TCG translation block cache size. Deprecated, use 7197 '\ ``-accel tcg,tb-size=n``\ ' instead. 7198ERST 7199 7200DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 7201 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 7202 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 7203 "-incoming unix:socketpath\n" \ 7204 " prepare for incoming migration, listen on\n" \ 7205 " specified protocol and socket address\n" \ 7206 "-incoming fd:fd\n" \ 7207 "-incoming exec:cmdline\n" \ 7208 " accept incoming migration on given file descriptor\n" \ 7209 " or from given external command\n" \ 7210 "-incoming defer\n" \ 7211 " wait for the URI to be specified via migrate_incoming\n", 7212 QEMU_ARCH_ALL) 7213STEXI 7214@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 7215@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 7216@findex -incoming 7217Prepare for incoming migration, listen on a given tcp port. 7218 7219@item -incoming unix:@var{socketpath} 7220Prepare for incoming migration, listen on a given unix socket. 7221 7222@item -incoming fd:@var{fd} 7223Accept incoming migration from a given filedescriptor. 7224 7225@item -incoming exec:@var{cmdline} 7226Accept incoming migration as an output from specified external command. 7227 7228@item -incoming defer 7229Wait for the URI to be specified via migrate_incoming. The monitor can 7230be used to change settings (such as migration parameters) prior to issuing 7231the migrate_incoming to allow the migration to begin. 7232ETEXI 7233SRST 7234``-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]`` 7235 \ 7236``-incoming rdma:host:port[,ipv4][,ipv6]`` 7237 Prepare for incoming migration, listen on a given tcp port. 7238 7239``-incoming unix:socketpath`` 7240 Prepare for incoming migration, listen on a given unix socket. 7241 7242``-incoming fd:fd`` 7243 Accept incoming migration from a given filedescriptor. 7244 7245``-incoming exec:cmdline`` 7246 Accept incoming migration as an output from specified external 7247 command. 7248 7249``-incoming defer`` 7250 Wait for the URI to be specified via migrate\_incoming. The monitor 7251 can be used to change settings (such as migration parameters) prior 7252 to issuing the migrate\_incoming to allow the migration to begin. 7253ERST 7254 7255DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 7256 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 7257STEXI 7258@item -only-migratable 7259@findex -only-migratable 7260Only allow migratable devices. Devices will not be allowed to enter an 7261unmigratable state. 7262ETEXI 7263SRST 7264``-only-migratable`` 7265 Only allow migratable devices. Devices will not be allowed to enter 7266 an unmigratable state. 7267ERST 7268 7269DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 7270 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 7271STEXI 7272@item -nodefaults 7273@findex -nodefaults 7274Don't create default devices. Normally, QEMU sets the default devices like serial 7275port, parallel port, virtual console, monitor device, VGA adapter, floppy and 7276CD-ROM drive and others. The @code{-nodefaults} option will disable all those 7277default devices. 7278ETEXI 7279SRST 7280``-nodefaults`` 7281 Don't create default devices. Normally, QEMU sets the default 7282 devices like serial port, parallel port, virtual console, monitor 7283 device, VGA adapter, floppy and CD-ROM drive and others. The 7284 ``-nodefaults`` option will disable all those default devices. 7285ERST 7286 7287#ifndef _WIN32 7288DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 7289 "-chroot dir chroot to dir just before starting the VM\n", 7290 QEMU_ARCH_ALL) 7291#endif 7292STEXI 7293@item -chroot @var{dir} 7294@findex -chroot 7295Immediately before starting guest execution, chroot to the specified 7296directory. Especially useful in combination with -runas. 7297ETEXI 7298SRST 7299``-chroot dir`` 7300 Immediately before starting guest execution, chroot to the specified 7301 directory. Especially useful in combination with -runas. 7302ERST 7303 7304#ifndef _WIN32 7305DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 7306 "-runas user change to user id user just before starting the VM\n" \ 7307 " user can be numeric uid:gid instead\n", 7308 QEMU_ARCH_ALL) 7309#endif 7310STEXI 7311@item -runas @var{user} 7312@findex -runas 7313Immediately before starting guest execution, drop root privileges, switching 7314to the specified user. 7315ETEXI 7316SRST 7317``-runas user`` 7318 Immediately before starting guest execution, drop root privileges, 7319 switching to the specified user. 7320ERST 7321 7322DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 7323 "-prom-env variable=value\n" 7324 " set OpenBIOS nvram variables\n", 7325 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 7326STEXI 7327@item -prom-env @var{variable}=@var{value} 7328@findex -prom-env 7329Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 7330 7331@example 7332qemu-system-sparc -prom-env 'auto-boot?=false' \ 7333 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single' 7334@end example 7335 7336@example 7337qemu-system-ppc -prom-env 'auto-boot?=false' \ 7338 -prom-env 'boot-device=hd:2,\yaboot' \ 7339 -prom-env 'boot-args=conf=hd:2,\yaboot.conf' 7340@end example 7341 7342ETEXI 7343SRST 7344``-prom-env variable=value`` 7345 Set OpenBIOS nvram variable to given value (PPC, SPARC only). 7346 7347 :: 7348 7349 qemu-system-sparc -prom-env 'auto-boot?=false' \ 7350 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single' 7351 7352 :: 7353 7354 qemu-system-ppc -prom-env 'auto-boot?=false' \ 7355 -prom-env 'boot-device=hd:2,\yaboot' \ 7356 -prom-env 'boot-args=conf=hd:2,\yaboot.conf' 7357ERST 7358DEF("semihosting", 0, QEMU_OPTION_semihosting, 7359 "-semihosting semihosting mode\n", 7360 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 7361 QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 7362STEXI 7363@item -semihosting 7364@findex -semihosting 7365Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only). 7366 7367Note that this allows guest direct access to the host filesystem, so 7368should only be used with a trusted guest OS. 7369 7370See the -semihosting-config option documentation for further information 7371about the facilities this enables. 7372ETEXI 7373SRST 7374``-semihosting`` 7375 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only). 7376 7377 Note that this allows guest direct access to the host filesystem, so 7378 should only be used with a trusted guest OS. 7379 7380 See the -semihosting-config option documentation for further 7381 information about the facilities this enables. 7382ERST 7383DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 7384 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \ 7385 " semihosting configuration\n", 7386QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 7387QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 7388STEXI 7389@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]] 7390@findex -semihosting-config 7391Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only). 7392 7393Note that this allows guest direct access to the host filesystem, so 7394should only be used with a trusted guest OS. 7395 7396On Arm this implements the standard semihosting API, version 2.0. 7397 7398On M68K this implements the "ColdFire GDB" interface used by libgloss. 7399 7400Xtensa semihosting provides basic file IO calls, such as 7401open/read/write/seek/select. Tensilica baremetal libc for ISS and 7402linux platform "sim" use this interface. 7403 7404@table @option 7405@item target=@code{native|gdb|auto} 7406Defines where the semihosting calls will be addressed, to QEMU (@code{native}) 7407or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 7408during debug sessions and @code{native} otherwise. 7409@item chardev=@var{str1} 7410Send the output to a chardev backend output for native or auto output when not in gdb 7411@item arg=@var{str1},arg=@var{str2},... 7412Allows the user to pass input arguments, and can be used multiple times to build 7413up a list. The old-style @code{-kernel}/@code{-append} method of passing a 7414command line is still supported for backward compatibility. If both the 7415@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 7416specified, the former is passed to semihosting as it always takes precedence. 7417@end table 7418ETEXI 7419SRST 7420``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]`` 7421 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II 7422 only). 7423 7424 Note that this allows guest direct access to the host filesystem, so 7425 should only be used with a trusted guest OS. 7426 7427 On Arm this implements the standard semihosting API, version 2.0. 7428 7429 On M68K this implements the "ColdFire GDB" interface used by 7430 libgloss. 7431 7432 Xtensa semihosting provides basic file IO calls, such as 7433 open/read/write/seek/select. Tensilica baremetal libc for ISS and 7434 linux platform "sim" use this interface. 7435 7436 ``target=native|gdb|auto`` 7437 Defines where the semihosting calls will be addressed, to QEMU 7438 (``native``) or to GDB (``gdb``). The default is ``auto``, which 7439 means ``gdb`` during debug sessions and ``native`` otherwise. 7440 7441 ``chardev=str1`` 7442 Send the output to a chardev backend output for native or auto 7443 output when not in gdb 7444 7445 ``arg=str1,arg=str2,...`` 7446 Allows the user to pass input arguments, and can be used 7447 multiple times to build up a list. The old-style 7448 ``-kernel``/``-append`` method of passing a command line is 7449 still supported for backward compatibility. If both the 7450 ``--semihosting-config arg`` and the ``-kernel``/``-append`` are 7451 specified, the former is passed to semihosting as it always 7452 takes precedence. 7453ERST 7454DEF("old-param", 0, QEMU_OPTION_old_param, 7455 "-old-param old param mode\n", QEMU_ARCH_ARM) 7456STEXI 7457@item -old-param 7458@findex -old-param (ARM) 7459Old param mode (ARM only). 7460ETEXI 7461SRST 7462``-old-param`` 7463 Old param mode (ARM only). 7464ERST 7465 7466DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 7467 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 7468 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 7469 " Enable seccomp mode 2 system call filter (default 'off').\n" \ 7470 " use 'obsolete' to allow obsolete system calls that are provided\n" \ 7471 " by the kernel, but typically no longer used by modern\n" \ 7472 " C library implementations.\n" \ 7473 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 7474 " its privileges by blacklisting all set*uid|gid system calls.\n" \ 7475 " The value 'children' will deny set*uid|gid system calls for\n" \ 7476 " main QEMU process but will allow forks and execves to run unprivileged\n" \ 7477 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 7478 " blacklisting *fork and execve\n" \ 7479 " use 'resourcecontrol' to disable process affinity and schedular priority\n", 7480 QEMU_ARCH_ALL) 7481STEXI 7482@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 7483@findex -sandbox 7484Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 7485disable it. The default is 'off'. 7486@table @option 7487@item obsolete=@var{string} 7488Enable Obsolete system calls 7489@item elevateprivileges=@var{string} 7490Disable set*uid|gid system calls 7491@item spawn=@var{string} 7492Disable *fork and execve 7493@item resourcecontrol=@var{string} 7494Disable process affinity and schedular priority 7495@end table 7496ETEXI 7497SRST 7498``-sandbox arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]`` 7499 Enable Seccomp mode 2 system call filter. 'on' will enable syscall 7500 filtering and 'off' will disable it. The default is 'off'. 7501 7502 ``obsolete=string`` 7503 Enable Obsolete system calls 7504 7505 ``elevateprivileges=string`` 7506 Disable set\*uid\|gid system calls 7507 7508 ``spawn=string`` 7509 Disable \*fork and execve 7510 7511 ``resourcecontrol=string`` 7512 Disable process affinity and schedular priority 7513ERST 7514 7515DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 7516 "-readconfig <file>\n", QEMU_ARCH_ALL) 7517STEXI 7518@item -readconfig @var{file} 7519@findex -readconfig 7520Read device configuration from @var{file}. This approach is useful when you want to spawn 7521QEMU process with many command line options but you don't want to exceed the command line 7522character limit. 7523ETEXI 7524SRST 7525``-readconfig file`` 7526 Read device configuration from file. This approach is useful when 7527 you want to spawn QEMU process with many command line options but 7528 you don't want to exceed the command line character limit. 7529ERST 7530DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 7531 "-writeconfig <file>\n" 7532 " read/write config file\n", QEMU_ARCH_ALL) 7533STEXI 7534@item -writeconfig @var{file} 7535@findex -writeconfig 7536Write device configuration to @var{file}. The @var{file} can be either filename to save 7537command line and device configuration into file or dash @code{-}) character to print the 7538output to stdout. This can be later used as input file for @code{-readconfig} option. 7539ETEXI 7540SRST 7541``-writeconfig file`` 7542 Write device configuration to file. The file can be either filename 7543 to save command line and device configuration into file or dash 7544 ``-``) character to print the output to stdout. This can be later 7545 used as input file for ``-readconfig`` option. 7546ERST 7547 7548DEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 7549 "-no-user-config\n" 7550 " do not load default user-provided config files at startup\n", 7551 QEMU_ARCH_ALL) 7552STEXI 7553@item -no-user-config 7554@findex -no-user-config 7555The @code{-no-user-config} option makes QEMU not load any of the user-provided 7556config files on @var{sysconfdir}. 7557ETEXI 7558SRST 7559``-no-user-config`` 7560 The ``-no-user-config`` option makes QEMU not load any of the 7561 user-provided config files on sysconfdir. 7562ERST 7563 7564DEF("trace", HAS_ARG, QEMU_OPTION_trace, 7565 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 7566 " specify tracing options\n", 7567 QEMU_ARCH_ALL) 7568STEXI 7569HXCOMM This line is not accurate, as some sub-options are backend-specific but 7570HXCOMM HX does not support conditional compilation of text. 7571@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 7572@findex -trace 7573@include docs/system/qemu-option-trace.texi 7574ETEXI 7575SRST 7576``-trace [[enable=]pattern][,events=file][,file=file]`` 7577 .. include:: ../qemu-option-trace.rst.inc 7578 7579ERST 7580DEF("plugin", HAS_ARG, QEMU_OPTION_plugin, 7581 "-plugin [file=]<file>[,arg=<string>]\n" 7582 " load a plugin\n", 7583 QEMU_ARCH_ALL) 7584STEXI 7585@item -plugin file=@var{file}[,arg=@var{string}] 7586@findex -plugin 7587 7588Load a plugin. 7589 7590@table @option 7591@item file=@var{file} 7592Load the given plugin from a shared library file. 7593@item arg=@var{string} 7594Argument string passed to the plugin. (Can be given multiple times.) 7595@end table 7596ETEXI 7597SRST 7598``-plugin file=file[,arg=string]`` 7599 Load a plugin. 7600 7601 ``file=file`` 7602 Load the given plugin from a shared library file. 7603 7604 ``arg=string`` 7605 Argument string passed to the plugin. (Can be given multiple 7606 times.) 7607ERST 7608 7609HXCOMM Internal use 7610DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 7611DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 7612 7613#ifdef __linux__ 7614DEF("enable-fips", 0, QEMU_OPTION_enablefips, 7615 "-enable-fips enable FIPS 140-2 compliance\n", 7616 QEMU_ARCH_ALL) 7617#endif 7618STEXI 7619@item -enable-fips 7620@findex -enable-fips 7621Enable FIPS 140-2 compliance mode. 7622ETEXI 7623SRST 7624``-enable-fips`` 7625 Enable FIPS 140-2 compliance mode. 7626ERST 7627 7628HXCOMM Deprecated by -accel tcg 7629DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 7630 7631DEF("msg", HAS_ARG, QEMU_OPTION_msg, 7632 "-msg timestamp[=on|off]\n" 7633 " control error message format\n" 7634 " timestamp=on enables timestamps (default: off)\n", 7635 QEMU_ARCH_ALL) 7636STEXI 7637@item -msg timestamp[=on|off] 7638@findex -msg 7639Control error message format. 7640@table @option 7641@item timestamp=on|off 7642Prefix messages with a timestamp. Default is off. 7643@end table 7644ETEXI 7645SRST 7646``-msg timestamp[=on|off]`` 7647 Control error message format. 7648 7649 ``timestamp=on|off`` 7650 Prefix messages with a timestamp. Default is off. 7651ERST 7652 7653DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 7654 "-dump-vmstate <file>\n" 7655 " Output vmstate information in JSON format to file.\n" 7656 " Use the scripts/vmstate-static-checker.py file to\n" 7657 " check for possible regressions in migration code\n" 7658 " by comparing two such vmstate dumps.\n", 7659 QEMU_ARCH_ALL) 7660STEXI 7661@item -dump-vmstate @var{file} 7662@findex -dump-vmstate 7663Dump json-encoded vmstate information for current machine type to file 7664in @var{file} 7665ETEXI 7666SRST 7667``-dump-vmstate file`` 7668 Dump json-encoded vmstate information for current machine type to 7669 file in file 7670ERST 7671 7672DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, 7673 "-enable-sync-profile\n" 7674 " enable synchronization profiling\n", 7675 QEMU_ARCH_ALL) 7676STEXI 7677@item -enable-sync-profile 7678@findex -enable-sync-profile 7679Enable synchronization profiling. 7680ETEXI 7681SRST 7682``-enable-sync-profile`` 7683 Enable synchronization profiling. 7684ERST 7685 7686STEXI 7687@end table 7688ETEXI 7689DEFHEADING() 7690 7691DEFHEADING(Generic object creation:) 7692STEXI 7693@table @option 7694ETEXI 7695 7696DEF("object", HAS_ARG, QEMU_OPTION_object, 7697 "-object TYPENAME[,PROP1=VALUE1,...]\n" 7698 " create a new object of type TYPENAME setting properties\n" 7699 " in the order they are specified. Note that the 'id'\n" 7700 " property must be set. These objects are placed in the\n" 7701 " '/objects' path.\n", 7702 QEMU_ARCH_ALL) 7703STEXI 7704@item -object @var{typename}[,@var{prop1}=@var{value1},...] 7705@findex -object 7706Create a new object of type @var{typename} setting properties 7707in the order they are specified. Note that the 'id' 7708property must be set. These objects are placed in the 7709'/objects' path. 7710 7711@table @option 7712 7713@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},align=@var{align} 7714 7715Creates a memory file backend object, which can be used to back 7716the guest RAM with huge pages. 7717 7718The @option{id} parameter is a unique ID that will be used to reference this 7719memory region when configuring the @option{-numa} argument. 7720 7721The @option{size} option provides the size of the memory region, and accepts 7722common suffixes, eg @option{500M}. 7723 7724The @option{mem-path} provides the path to either a shared memory or huge page 7725filesystem mount. 7726 7727The @option{share} boolean option determines whether the memory 7728region is marked as private to QEMU, or shared. The latter allows 7729a co-operating external process to access the QEMU memory region. 7730 7731The @option{share} is also required for pvrdma devices due to 7732limitations in the RDMA API provided by Linux. 7733 7734Setting share=on might affect the ability to configure NUMA 7735bindings for the memory backend under some circumstances, see 7736Documentation/vm/numa_memory_policy.txt on the Linux kernel 7737source tree for additional details. 7738 7739Setting the @option{discard-data} boolean option to @var{on} 7740indicates that file contents can be destroyed when QEMU exits, 7741to avoid unnecessarily flushing data to the backing file. Note 7742that @option{discard-data} is only an optimization, and QEMU 7743might not discard file contents if it aborts unexpectedly or is 7744terminated using SIGKILL. 7745 7746The @option{merge} boolean option enables memory merge, also known as 7747MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 7748memory deduplication. 7749 7750Setting the @option{dump} boolean option to @var{off} excludes the memory from 7751core dumps. This feature is also known as MADV_DONTDUMP. 7752 7753The @option{prealloc} boolean option enables memory preallocation. 7754 7755The @option{host-nodes} option binds the memory range to a list of NUMA host 7756nodes. 7757 7758The @option{policy} option sets the NUMA policy to one of the following values: 7759 7760@table @option 7761@item @var{default} 7762default host policy 7763 7764@item @var{preferred} 7765prefer the given host node list for allocation 7766 7767@item @var{bind} 7768restrict memory allocation to the given host node list 7769 7770@item @var{interleave} 7771interleave memory allocations across the given host node list 7772@end table 7773 7774The @option{align} option specifies the base address alignment when 7775QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 7776@option{2M}. Some backend store specified by @option{mem-path} 7777requires an alignment different than the default one used by QEMU, eg 7778the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 7779such cases, users can specify the required alignment via this option. 7780 7781The @option{pmem} option specifies whether the backing file specified 7782by @option{mem-path} is in host persistent memory that can be accessed 7783using the SNIA NVM programming model (e.g. Intel NVDIMM). 7784If @option{pmem} is set to 'on', QEMU will take necessary operations to 7785guarantee the persistence of its own writes to @option{mem-path} 7786(e.g. in vNVDIMM label emulation and live migration). 7787Also, we will map the backend-file with MAP_SYNC flag, which ensures the 7788file metadata is in sync for @option{mem-path} in case of host crash 7789or a power failure. MAP_SYNC requires support from both the host kernel 7790(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted 7791with DAX option. 7792 7793@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave} 7794 7795Creates a memory backend object, which can be used to back the guest RAM. 7796Memory backend objects offer more control than the @option{-m} option that is 7797traditionally used to define guest RAM. Please refer to 7798@option{memory-backend-file} for a description of the options. 7799 7800@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size} 7801 7802Creates an anonymous memory file backend object, which allows QEMU to 7803share the memory with an external process (e.g. when using 7804vhost-user). The memory is allocated with memfd and optional 7805sealing. (Linux only) 7806 7807The @option{seal} option creates a sealed-file, that will block 7808further resizing the memory ('on' by default). 7809 7810The @option{hugetlb} option specify the file to be created resides in 7811the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 7812the @option{hugetlb} option, the @option{hugetlbsize} option specify 7813the hugetlb page size on systems that support multiple hugetlb page 7814sizes (it must be a power of 2 value supported by the system). 7815 7816In some versions of Linux, the @option{hugetlb} option is incompatible 7817with the @option{seal} option (requires at least Linux 4.16). 7818 7819Please refer to @option{memory-backend-file} for a description of the 7820other options. 7821 7822The @option{share} boolean option is @var{on} by default with memfd. 7823 7824@item -object rng-builtin,id=@var{id} 7825 7826Creates a random number generator backend which obtains entropy from 7827QEMU builtin functions. The @option{id} parameter is a unique ID that 7828will be used to reference this entropy backend from the @option{virtio-rng} 7829device. By default, the @option{virtio-rng} device uses this RNG backend. 7830 7831@item -object rng-random,id=@var{id},filename=@var{/dev/random} 7832 7833Creates a random number generator backend which obtains entropy from 7834a device on the host. The @option{id} parameter is a unique ID that 7835will be used to reference this entropy backend from the @option{virtio-rng} 7836device. The @option{filename} parameter specifies which file to obtain 7837entropy from and if omitted defaults to @option{/dev/urandom}. 7838 7839@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 7840 7841Creates a random number generator backend which obtains entropy from 7842an external daemon running on the host. The @option{id} parameter is 7843a unique ID that will be used to reference this entropy backend from 7844the @option{virtio-rng} device. The @option{chardev} parameter is 7845the unique ID of a character device backend that provides the connection 7846to the RNG daemon. 7847 7848@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 7849 7850Creates a TLS anonymous credentials object, which can be used to provide 7851TLS support on network backends. The @option{id} parameter is a unique 7852ID which network backends will use to access the credentials. The 7853@option{endpoint} is either @option{server} or @option{client} depending 7854on whether the QEMU network backend that uses the credentials will be 7855acting as a client or as a server. If @option{verify-peer} is enabled 7856(the default) then once the handshake is completed, the peer credentials 7857will be verified, though this is a no-op for anonymous credentials. 7858 7859The @var{dir} parameter tells QEMU where to find the credential 7860files. For server endpoints, this directory may contain a file 7861@var{dh-params.pem} providing diffie-hellman parameters to use 7862for the TLS server. If the file is missing, QEMU will generate 7863a set of DH parameters at startup. This is a computationally 7864expensive operation that consumes random pool entropy, so it is 7865recommended that a persistent set of parameters be generated 7866upfront and saved. 7867 7868@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}] 7869 7870Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide 7871TLS support on network backends. The @option{id} parameter is a unique 7872ID which network backends will use to access the credentials. The 7873@option{endpoint} is either @option{server} or @option{client} depending 7874on whether the QEMU network backend that uses the credentials will be 7875acting as a client or as a server. For clients only, @option{username} 7876is the username which will be sent to the server. If omitted 7877it defaults to ``qemu''. 7878 7879The @var{dir} parameter tells QEMU where to find the keys file. 7880It is called ``@var{dir}/keys.psk'' and contains ``username:key'' 7881pairs. This file can most easily be created using the GnuTLS 7882@code{psktool} program. 7883 7884For server endpoints, @var{dir} may also contain a file 7885@var{dh-params.pem} providing diffie-hellman parameters to use 7886for the TLS server. If the file is missing, QEMU will generate 7887a set of DH parameters at startup. This is a computationally 7888expensive operation that consumes random pool entropy, so it is 7889recommended that a persistent set of parameters be generated 7890up front and saved. 7891 7892@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id} 7893 7894Creates a TLS anonymous credentials object, which can be used to provide 7895TLS support on network backends. The @option{id} parameter is a unique 7896ID which network backends will use to access the credentials. The 7897@option{endpoint} is either @option{server} or @option{client} depending 7898on whether the QEMU network backend that uses the credentials will be 7899acting as a client or as a server. If @option{verify-peer} is enabled 7900(the default) then once the handshake is completed, the peer credentials 7901will be verified. With x509 certificates, this implies that the clients 7902must be provided with valid client certificates too. 7903 7904The @var{dir} parameter tells QEMU where to find the credential 7905files. For server endpoints, this directory may contain a file 7906@var{dh-params.pem} providing diffie-hellman parameters to use 7907for the TLS server. If the file is missing, QEMU will generate 7908a set of DH parameters at startup. This is a computationally 7909expensive operation that consumes random pool entropy, so it is 7910recommended that a persistent set of parameters be generated 7911upfront and saved. 7912 7913For x509 certificate credentials the directory will contain further files 7914providing the x509 certificates. The certificates must be stored 7915in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 7916@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 7917@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 7918 7919For the @var{server-key.pem} and @var{client-key.pem} files which 7920contain sensitive private keys, it is possible to use an encrypted 7921version by providing the @var{passwordid} parameter. This provides 7922the ID of a previously created @code{secret} object containing the 7923password for decryption. 7924 7925The @var{priority} parameter allows to override the global default 7926priority used by gnutls. This can be useful if the system administrator 7927needs to use a weaker set of crypto priorities for QEMU without 7928potentially forcing the weakness onto all applications. Or conversely 7929if one wants wants a stronger default for QEMU than for all other 7930applications, they can do this through this parameter. Its format is 7931a gnutls priority string as described at 7932@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 7933 7934@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}][,position=@var{head|tail|id=<id>}][,insert=@var{behind|before}] 7935 7936Interval @var{t} can't be 0, this filter batches the packet delivery: all 7937packets arriving in a given interval on netdev @var{netdevid} are delayed 7938until the end of the interval. Interval is in microseconds. 7939@option{status} is optional that indicate whether the netfilter is 7940on (enabled) or off (disabled), the default status for netfilter will be 'on'. 7941 7942queue @var{all|rx|tx} is an option that can be applied to any netfilter. 7943 7944@option{all}: the filter is attached both to the receive and the transmit 7945 queue of the netdev (default). 7946 7947@option{rx}: the filter is attached to the receive queue of the netdev, 7948 where it will receive packets sent to the netdev. 7949 7950@option{tx}: the filter is attached to the transmit queue of the netdev, 7951 where it will receive packets sent by the netdev. 7952 7953position @var{head|tail|id=<id>} is an option to specify where the 7954filter should be inserted in the filter list. It can be applied to any 7955netfilter. 7956 7957@option{head}: the filter is inserted at the head of the filter 7958 list, before any existing filters. 7959 7960@option{tail}: the filter is inserted at the tail of the filter 7961 list, behind any existing filters (default). 7962 7963@option{id=<id>}: the filter is inserted before or behind the filter 7964 specified by <id>, see the insert option below. 7965 7966insert @var{behind|before} is an option to specify where to insert the 7967new filter relative to the one specified with position=id=<id>. It can 7968be applied to any netfilter. 7969 7970@option{before}: insert before the specified filter. 7971 7972@option{behind}: insert behind the specified filter (default). 7973 7974@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support][,position=@var{head|tail|id=<id>}][,insert=@var{behind|before}] 7975 7976filter-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. 7977 7978@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support][,position=@var{head|tail|id=<id>}][,insert=@var{behind|before}] 7979 7980filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 7981@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 7982filter-redirector will redirect packet with vnet_hdr_len. 7983Create a filter-redirector we need to differ outdev id from indev id, id can not 7984be the same. we can just use indev or outdev, but at least one of indev or outdev 7985need to be specified. 7986 7987@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support][,position=@var{head|tail|id=<id>}][,insert=@var{behind|before}] 7988 7989Filter-rewriter is a part of COLO project.It will rewrite tcp packet to 7990secondary from primary to keep secondary tcp connection,and rewrite 7991tcp packet to primary from secondary make tcp packet can be handled by 7992client.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 7993 7994usage: 7995colo secondary: 7996-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 7997-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 7998-object filter-rewriter,id=rew0,netdev=hn0,queue=all 7999 8000@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}][,position=@var{head|tail|id=<id>}][,insert=@var{behind|before}] 8001 8002Dump the network traffic on netdev @var{dev} to the file specified by 8003@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 8004The file format is libpcap, so it can be analyzed with tools such as tcpdump 8005or Wireshark. 8006 8007@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid},iothread=@var{id}[,vnet_hdr_support][,notify_dev=@var{id}] 8008 8009Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 8010secondary packet. If the packets are same, we will output primary 8011packet to outdev@var{chardevid}, else we will notify colo-frame 8012do checkpoint and send primary packet to outdev@var{chardevid}. 8013In order to improve efficiency, we need to put the task of comparison 8014in another thread. If it has the vnet_hdr_support flag, colo compare 8015will send/recv packet with vnet_hdr_len. 8016If you want to use Xen COLO, will need the notify_dev to notify Xen 8017colo-frame to do checkpoint. 8018 8019we must use it with the help of filter-mirror and filter-redirector. 8020 8021@example 8022 8023KVM COLO 8024 8025primary: 8026-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 8027-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 8028-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 8029-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 8030-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 8031-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 8032-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 8033-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 8034-object iothread,id=iothread1 8035-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 8036-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 8037-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 8038-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 8039 8040secondary: 8041-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 8042-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 8043-chardev socket,id=red0,host=3.3.3.3,port=9003 8044-chardev socket,id=red1,host=3.3.3.3,port=9004 8045-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 8046-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 8047 8048 8049Xen COLO 8050 8051primary: 8052-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 8053-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 8054-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 8055-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 8056-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 8057-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 8058-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 8059-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 8060-chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait 8061-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 8062-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 8063-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 8064-object iothread,id=iothread1 8065-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 8066 8067secondary: 8068-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 8069-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 8070-chardev socket,id=red0,host=3.3.3.3,port=9003 8071-chardev socket,id=red1,host=3.3.3.3,port=9004 8072-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 8073-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 8074 8075@end example 8076 8077If you want to know the detail of above command line, you can read 8078the colo-compare git log. 8079 8080@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 8081 8082Creates a cryptodev backend which executes crypto opreation from 8083the QEMU cipher APIS. The @var{id} parameter is 8084a unique ID that will be used to reference this cryptodev backend from 8085the @option{virtio-crypto} device. The @var{queues} parameter is optional, 8086which specify the queue number of cryptodev backend, the default of 8087@var{queues} is 1. 8088 8089@example 8090 8091 # @value{qemu_system} \ 8092 [...] \ 8093 -object cryptodev-backend-builtin,id=cryptodev0 \ 8094 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 8095 [...] 8096@end example 8097 8098@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 8099 8100Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 8101The @var{id} parameter is a unique ID that will be used to reference this 8102cryptodev backend from the @option{virtio-crypto} device. 8103The chardev should be a unix domain socket backed one. The vhost-user uses 8104a specifically defined protocol to pass vhost ioctl replacement messages 8105to an application on the other end of the socket. 8106The @var{queues} parameter is optional, which specify the queue number 8107of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 8108 8109@example 8110 8111 # @value{qemu_system} \ 8112 [...] \ 8113 -chardev socket,id=chardev0,path=/path/to/socket \ 8114 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 8115 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 8116 [...] 8117@end example 8118 8119@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 8120@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 8121 8122Defines a secret to store a password, encryption key, or some other sensitive 8123data. The sensitive data can either be passed directly via the @var{data} 8124parameter, or indirectly via the @var{file} parameter. Using the @var{data} 8125parameter is insecure unless the sensitive data is encrypted. 8126 8127The sensitive data can be provided in raw format (the default), or base64. 8128When encoded as JSON, the raw format only supports valid UTF-8 characters, 8129so base64 is recommended for sending binary data. QEMU will convert from 8130which ever format is provided to the format it needs internally. eg, an 8131RBD password can be provided in raw format, even though it will be base64 8132encoded when passed onto the RBD sever. 8133 8134For added protection, it is possible to encrypt the data associated with 8135a secret using the AES-256-CBC cipher. Use of encryption is indicated 8136by providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 8137parameter provides the ID of a previously defined secret that contains 8138the AES-256 decryption key. This key should be 32-bytes long and be 8139base64 encoded. The @var{iv} parameter provides the random initialization 8140vector used for encryption of this particular secret and should be a 8141base64 encrypted string of the 16-byte IV. 8142 8143The simplest (insecure) usage is to provide the secret inline 8144 8145@example 8146 8147 # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw 8148 8149@end example 8150 8151The simplest secure usage is to provide the secret via a file 8152 8153 # printf "letmein" > mypasswd.txt 8154 # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw 8155 8156For greater security, AES-256-CBC should be used. To illustrate usage, 8157consider the openssl command line tool which can encrypt the data. Note 8158that when encrypting, the plaintext must be padded to the cipher block 8159size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 8160 8161First a master key needs to be created in base64 encoding: 8162 8163@example 8164 # openssl rand -base64 32 > key.b64 8165 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 8166@end example 8167 8168Each secret to be encrypted needs to have a random initialization vector 8169generated. These do not need to be kept secret 8170 8171@example 8172 # openssl rand -base64 16 > iv.b64 8173 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 8174@end example 8175 8176The secret to be defined can now be encrypted, in this case we're 8177telling openssl to base64 encode the result, but it could be left 8178as raw bytes if desired. 8179 8180@example 8181 # SECRET=$(printf "letmein" | 8182 openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 8183@end example 8184 8185When launching QEMU, create a master secret pointing to @code{key.b64} 8186and specify that to be used to decrypt the user password. Pass the 8187contents of @code{iv.b64} to the second secret 8188 8189@example 8190 # @value{qemu_system} \ 8191 -object secret,id=secmaster0,format=base64,file=key.b64 \ 8192 -object secret,id=sec0,keyid=secmaster0,format=base64,\ 8193 data=$SECRET,iv=$(<iv.b64) 8194@end example 8195 8196@item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}] 8197 8198Create a Secure Encrypted Virtualization (SEV) guest object, which can be used 8199to provide the guest memory encryption support on AMD processors. 8200 8201When memory encryption is enabled, one of the physical address bit (aka the 8202C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 8203is used to provide the C-bit position. The C-bit position is Host family dependent 8204hence user must provide this value. On EPYC, the value should be 47. 8205 8206When memory encryption is enabled, we loose certain bits in physical address space. 8207The @option{reduced-phys-bits} is used to provide the number of bits we loose in 8208physical address space. Similar to C-bit, the value is Host family dependent. 8209On EPYC, the value should be 5. 8210 8211The @option{sev-device} provides the device file to use for communicating with 8212the SEV firmware running inside AMD Secure Processor. The default device is 8213'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 8214created by CCP driver. 8215 8216The @option{policy} provides the guest policy to be enforced by the SEV firmware 8217and restrict what configuration and operational commands can be performed on this 8218guest by the hypervisor. The policy should be provided by the guest owner and is 8219bound to the guest and cannot be changed throughout the lifetime of the guest. 8220The default is 0. 8221 8222If guest @option{policy} allows sharing the key with another SEV guest then 8223@option{handle} can be use to provide handle of the guest from which to share 8224the key. 8225 8226The @option{dh-cert-file} and @option{session-file} provides the guest owner's 8227Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters 8228are used for establishing a cryptographic session with the guest owner to 8229negotiate keys used for attestation. The file must be encoded in base64. 8230 8231e.g to launch a SEV guest 8232@example 8233 # @value{qemu_system_x86} \ 8234 ...... 8235 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 8236 -machine ...,memory-encryption=sev0 8237 ..... 8238 8239@end example 8240 8241 8242@item -object authz-simple,id=@var{id},identity=@var{string} 8243 8244Create an authorization object that will control access to network services. 8245 8246The @option{identity} parameter is identifies the user and its format 8247depends on the network service that authorization object is associated 8248with. For authorizing based on TLS x509 certificates, the identity must 8249be the x509 distinguished name. Note that care must be taken to escape 8250any commas in the distinguished name. 8251 8252An example authorization object to validate a x509 distinguished name 8253would look like: 8254@example 8255 # @value{qemu_system} \ 8256 ... 8257 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \ 8258 ... 8259@end example 8260 8261Note the use of quotes due to the x509 distinguished name containing 8262whitespace, and escaping of ','. 8263 8264@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no} 8265 8266Create an authorization object that will control access to network services. 8267 8268The @option{filename} parameter is the fully qualified path to a file 8269containing the access control list rules in JSON format. 8270 8271An example set of rules that match against SASL usernames might look 8272like: 8273 8274@example 8275 @{ 8276 "rules": [ 8277 @{ "match": "fred", "policy": "allow", "format": "exact" @}, 8278 @{ "match": "bob", "policy": "allow", "format": "exact" @}, 8279 @{ "match": "danb", "policy": "deny", "format": "glob" @}, 8280 @{ "match": "dan*", "policy": "allow", "format": "exact" @}, 8281 ], 8282 "policy": "deny" 8283 @} 8284@end example 8285 8286When checking access the object will iterate over all the rules and 8287the first rule to match will have its @option{policy} value returned 8288as the result. If no rules match, then the default @option{policy} 8289value is returned. 8290 8291The rules can either be an exact string match, or they can use the 8292simple UNIX glob pattern matching to allow wildcards to be used. 8293 8294If @option{refresh} is set to true the file will be monitored 8295and automatically reloaded whenever its content changes. 8296 8297As with the @code{authz-simple} object, the format of the identity 8298strings being matched depends on the network service, but is usually 8299a TLS x509 distinguished name, or a SASL username. 8300 8301An example authorization object to validate a SASL username 8302would look like: 8303@example 8304 # @value{qemu_system} \ 8305 ... 8306 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes 8307 ... 8308@end example 8309 8310@item -object authz-pam,id=@var{id},service=@var{string} 8311 8312Create an authorization object that will control access to network services. 8313 8314The @option{service} parameter provides the name of a PAM service to use 8315for authorization. It requires that a file @code{/etc/pam.d/@var{service}} 8316exist to provide the configuration for the @code{account} subsystem. 8317 8318An example authorization object to validate a TLS x509 distinguished 8319name would look like: 8320 8321@example 8322 # @value{qemu_system} \ 8323 ... 8324 -object authz-pam,id=auth0,service=qemu-vnc 8325 ... 8326@end example 8327 8328There would then be a corresponding config file for PAM at 8329@code{/etc/pam.d/qemu-vnc} that contains: 8330 8331@example 8332account requisite pam_listfile.so item=user sense=allow \ 8333 file=/etc/qemu/vnc.allow 8334@end example 8335 8336Finally the @code{/etc/qemu/vnc.allow} file would contain 8337the list of x509 distingished names that are permitted 8338access 8339 8340@example 8341CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB 8342@end example 8343 8344@item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink} 8345 8346Creates a dedicated event loop thread that devices can be assigned to. This is 8347known as an IOThread. By default device emulation happens in vCPU threads or 8348the main event loop thread. This can become a scalability bottleneck. 8349IOThreads allow device emulation and I/O to run on other host CPUs. 8350 8351The @option{id} parameter is a unique ID that will be used to reference this 8352IOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be 8353assigned to an IOThread. Note that not all devices support an 8354@option{iothread} parameter. 8355 8356The @code{query-iothreads} QMP command lists IOThreads and reports their thread 8357IDs so that the user can configure host CPU pinning/affinity. 8358 8359IOThreads use an adaptive polling algorithm to reduce event loop latency. 8360Instead of entering a blocking system call to monitor file descriptors and then 8361pay the cost of being woken up when an event occurs, the polling algorithm 8362spins waiting for events for a short time. The algorithm's default parameters 8363are suitable for many cases but can be adjusted based on knowledge of the 8364workload and/or host device latency. 8365 8366The @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy 8367wait for events. Polling can be disabled by setting this value to 0. 8368 8369The @option{poll-grow} parameter is the multiplier used to increase the polling 8370time when the algorithm detects it is missing events due to not polling long 8371enough. 8372 8373The @option{poll-shrink} parameter is the divisor used to decrease the polling 8374time when the algorithm detects it is spending too long polling without 8375encountering events. 8376 8377The polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}): 8378 8379@example 8380(qemu) qom-set /objects/iothread1 poll-max-ns 100000 8381@end example 8382 8383@end table 8384 8385ETEXI 8386SRST 8387``-object typename[,prop1=value1,...]`` 8388 Create a new object of type typename setting properties in the order 8389 they are specified. Note that the 'id' property must be set. These 8390 objects are placed in the '/objects' path. 8391 8392 ``-object memory-backend-file,id=id,size=size,mem-path=dir,share=on|off,discard-data=on|off,merge=on|off,dump=on|off,prealloc=on|off,host-nodes=host-nodes,policy=default|preferred|bind|interleave,align=align`` 8393 Creates a memory file backend object, which can be used to back 8394 the guest RAM with huge pages. 8395 8396 The ``id`` parameter is a unique ID that will be used to 8397 reference this memory region when configuring the ``-numa`` 8398 argument. 8399 8400 The ``size`` option provides the size of the memory region, and 8401 accepts common suffixes, eg ``500M``. 8402 8403 The ``mem-path`` provides the path to either a shared memory or 8404 huge page filesystem mount. 8405 8406 The ``share`` boolean option determines whether the memory 8407 region is marked as private to QEMU, or shared. The latter 8408 allows a co-operating external process to access the QEMU memory 8409 region. 8410 8411 The ``share`` is also required for pvrdma devices due to 8412 limitations in the RDMA API provided by Linux. 8413 8414 Setting share=on might affect the ability to configure NUMA 8415 bindings for the memory backend under some circumstances, see 8416 Documentation/vm/numa\_memory\_policy.txt on the Linux kernel 8417 source tree for additional details. 8418 8419 Setting the ``discard-data`` boolean option to on indicates that 8420 file contents can be destroyed when QEMU exits, to avoid 8421 unnecessarily flushing data to the backing file. Note that 8422 ``discard-data`` is only an optimization, and QEMU might not 8423 discard file contents if it aborts unexpectedly or is terminated 8424 using SIGKILL. 8425 8426 The ``merge`` boolean option enables memory merge, also known as 8427 MADV\_MERGEABLE, so that Kernel Samepage Merging will consider 8428 the pages for memory deduplication. 8429 8430 Setting the ``dump`` boolean option to off excludes the memory 8431 from core dumps. This feature is also known as MADV\_DONTDUMP. 8432 8433 The ``prealloc`` boolean option enables memory preallocation. 8434 8435 The ``host-nodes`` option binds the memory range to a list of 8436 NUMA host nodes. 8437 8438 The ``policy`` option sets the NUMA policy to one of the 8439 following values: 8440 8441 ``default`` 8442 default host policy 8443 8444 ``preferred`` 8445 prefer the given host node list for allocation 8446 8447 ``bind`` 8448 restrict memory allocation to the given host node list 8449 8450 ``interleave`` 8451 interleave memory allocations across the given host node 8452 list 8453 8454 The ``align`` option specifies the base address alignment when 8455 QEMU mmap(2) ``mem-path``, and accepts common suffixes, eg 8456 ``2M``. Some backend store specified by ``mem-path`` requires an 8457 alignment different than the default one used by QEMU, eg the 8458 device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 8459 such cases, users can specify the required alignment via this 8460 option. 8461 8462 The ``pmem`` option specifies whether the backing file specified 8463 by ``mem-path`` is in host persistent memory that can be 8464 accessed using the SNIA NVM programming model (e.g. Intel 8465 NVDIMM). If ``pmem`` is set to 'on', QEMU will take necessary 8466 operations to guarantee the persistence of its own writes to 8467 ``mem-path`` (e.g. in vNVDIMM label emulation and live 8468 migration). Also, we will map the backend-file with MAP\_SYNC 8469 flag, which ensures the file metadata is in sync for 8470 ``mem-path`` in case of host crash or a power failure. MAP\_SYNC 8471 requires support from both the host kernel (since Linux kernel 8472 4.15) and the filesystem of ``mem-path`` mounted with DAX 8473 option. 8474 8475 ``-object memory-backend-ram,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-nodes,policy=default|preferred|bind|interleave`` 8476 Creates a memory backend object, which can be used to back the 8477 guest RAM. Memory backend objects offer more control than the 8478 ``-m`` option that is traditionally used to define guest RAM. 8479 Please refer to ``memory-backend-file`` for a description of the 8480 options. 8481 8482 ``-object memory-backend-memfd,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-nodes,policy=default|preferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlbsize=size`` 8483 Creates an anonymous memory file backend object, which allows 8484 QEMU to share the memory with an external process (e.g. when 8485 using vhost-user). The memory is allocated with memfd and 8486 optional sealing. (Linux only) 8487 8488 The ``seal`` option creates a sealed-file, that will block 8489 further resizing the memory ('on' by default). 8490 8491 The ``hugetlb`` option specify the file to be created resides in 8492 the hugetlbfs filesystem (since Linux 4.14). Used in conjunction 8493 with the ``hugetlb`` option, the ``hugetlbsize`` option specify 8494 the hugetlb page size on systems that support multiple hugetlb 8495 page sizes (it must be a power of 2 value supported by the 8496 system). 8497 8498 In some versions of Linux, the ``hugetlb`` option is 8499 incompatible with the ``seal`` option (requires at least Linux 8500 4.16). 8501 8502 Please refer to ``memory-backend-file`` for a description of the 8503 other options. 8504 8505 The ``share`` boolean option is on by default with memfd. 8506 8507 ``-object rng-builtin,id=id`` 8508 Creates a random number generator backend which obtains entropy 8509 from QEMU builtin functions. The ``id`` parameter is a unique ID 8510 that will be used to reference this entropy backend from the 8511 ``virtio-rng`` device. By default, the ``virtio-rng`` device 8512 uses this RNG backend. 8513 8514 ``-object rng-random,id=id,filename=/dev/random`` 8515 Creates a random number generator backend which obtains entropy 8516 from a device on the host. The ``id`` parameter is a unique ID 8517 that will be used to reference this entropy backend from the 8518 ``virtio-rng`` device. The ``filename`` parameter specifies 8519 which file to obtain entropy from and if omitted defaults to 8520 ``/dev/urandom``. 8521 8522 ``-object rng-egd,id=id,chardev=chardevid`` 8523 Creates a random number generator backend which obtains entropy 8524 from an external daemon running on the host. The ``id`` 8525 parameter is a unique ID that will be used to reference this 8526 entropy backend from the ``virtio-rng`` device. The ``chardev`` 8527 parameter is the unique ID of a character device backend that 8528 provides the connection to the RNG daemon. 8529 8530 ``-object tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off`` 8531 Creates a TLS anonymous credentials object, which can be used to 8532 provide TLS support on network backends. The ``id`` parameter is 8533 a unique ID which network backends will use to access the 8534 credentials. The ``endpoint`` is either ``server`` or ``client`` 8535 depending on whether the QEMU network backend that uses the 8536 credentials will be acting as a client or as a server. If 8537 ``verify-peer`` is enabled (the default) then once the handshake 8538 is completed, the peer credentials will be verified, though this 8539 is a no-op for anonymous credentials. 8540 8541 The dir parameter tells QEMU where to find the credential files. 8542 For server endpoints, this directory may contain a file 8543 dh-params.pem providing diffie-hellman parameters to use for the 8544 TLS server. If the file is missing, QEMU will generate a set of 8545 DH parameters at startup. This is a computationally expensive 8546 operation that consumes random pool entropy, so it is 8547 recommended that a persistent set of parameters be generated 8548 upfront and saved. 8549 8550 ``-object tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]`` 8551 Creates a TLS Pre-Shared Keys (PSK) credentials object, which 8552 can be used to provide TLS support on network backends. The 8553 ``id`` parameter is a unique ID which network backends will use 8554 to access the credentials. The ``endpoint`` is either ``server`` 8555 or ``client`` depending on whether the QEMU network backend that 8556 uses the credentials will be acting as a client or as a server. 8557 For clients only, ``username`` is the username which will be 8558 sent to the server. If omitted it defaults to "qemu". 8559 8560 The dir parameter tells QEMU where to find the keys file. It is 8561 called "dir/keys.psk" and contains "username:key" pairs. This 8562 file can most easily be created using the GnuTLS ``psktool`` 8563 program. 8564 8565 For server endpoints, dir may also contain a file dh-params.pem 8566 providing diffie-hellman parameters to use for the TLS server. 8567 If the file is missing, QEMU will generate a set of DH 8568 parameters at startup. This is a computationally expensive 8569 operation that consumes random pool entropy, so it is 8570 recommended that a persistent set of parameters be generated up 8571 front and saved. 8572 8573 ``-object tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id`` 8574 Creates a TLS anonymous credentials object, which can be used to 8575 provide TLS support on network backends. The ``id`` parameter is 8576 a unique ID which network backends will use to access the 8577 credentials. The ``endpoint`` is either ``server`` or ``client`` 8578 depending on whether the QEMU network backend that uses the 8579 credentials will be acting as a client or as a server. If 8580 ``verify-peer`` is enabled (the default) then once the handshake 8581 is completed, the peer credentials will be verified. With x509 8582 certificates, this implies that the clients must be provided 8583 with valid client certificates too. 8584 8585 The dir parameter tells QEMU where to find the credential files. 8586 For server endpoints, this directory may contain a file 8587 dh-params.pem providing diffie-hellman parameters to use for the 8588 TLS server. If the file is missing, QEMU will generate a set of 8589 DH parameters at startup. This is a computationally expensive 8590 operation that consumes random pool entropy, so it is 8591 recommended that a persistent set of parameters be generated 8592 upfront and saved. 8593 8594 For x509 certificate credentials the directory will contain 8595 further files providing the x509 certificates. The certificates 8596 must be stored in PEM format, in filenames ca-cert.pem, 8597 ca-crl.pem (optional), server-cert.pem (only servers), 8598 server-key.pem (only servers), client-cert.pem (only clients), 8599 and client-key.pem (only clients). 8600 8601 For the server-key.pem and client-key.pem files which contain 8602 sensitive private keys, it is possible to use an encrypted 8603 version by providing the passwordid parameter. This provides the 8604 ID of a previously created ``secret`` object containing the 8605 password for decryption. 8606 8607 The priority parameter allows to override the global default 8608 priority used by gnutls. This can be useful if the system 8609 administrator needs to use a weaker set of crypto priorities for 8610 QEMU without potentially forcing the weakness onto all 8611 applications. Or conversely if one wants wants a stronger 8612 default for QEMU than for all other applications, they can do 8613 this through this parameter. Its format is a gnutls priority 8614 string as described at 8615 https://gnutls.org/manual/html_node/Priority-Strings.html. 8616 8617 ``-object filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off][,position=head|tail|id=<id>][,insert=behind|before]`` 8618 Interval t can't be 0, this filter batches the packet delivery: 8619 all packets arriving in a given interval on netdev netdevid are 8620 delayed until the end of the interval. Interval is in 8621 microseconds. ``status`` is optional that indicate whether the 8622 netfilter is on (enabled) or off (disabled), the default status 8623 for netfilter will be 'on'. 8624 8625 queue all\|rx\|tx is an option that can be applied to any 8626 netfilter. 8627 8628 ``all``: the filter is attached both to the receive and the 8629 transmit queue of the netdev (default). 8630 8631 ``rx``: the filter is attached to the receive queue of the 8632 netdev, where it will receive packets sent to the netdev. 8633 8634 ``tx``: the filter is attached to the transmit queue of the 8635 netdev, where it will receive packets sent by the netdev. 8636 8637 position head\|tail\|id=<id> is an option to specify where the 8638 filter should be inserted in the filter list. It can be applied 8639 to any netfilter. 8640 8641 ``head``: the filter is inserted at the head of the filter list, 8642 before any existing filters. 8643 8644 ``tail``: the filter is inserted at the tail of the filter list, 8645 behind any existing filters (default). 8646 8647 ``id=<id>``: the filter is inserted before or behind the filter 8648 specified by <id>, see the insert option below. 8649 8650 insert behind\|before is an option to specify where to insert 8651 the new filter relative to the one specified with 8652 position=id=<id>. It can be applied to any netfilter. 8653 8654 ``before``: insert before the specified filter. 8655 8656 ``behind``: insert behind the specified filter (default). 8657 8658 ``-object filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]`` 8659 filter-mirror on netdev netdevid,mirror net packet to 8660 chardevchardevid, if it has the vnet\_hdr\_support flag, 8661 filter-mirror will mirror packet with vnet\_hdr\_len. 8662 8663 ``-object filter-redirector,id=id,netdev=netdevid,indev=chardevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]`` 8664 filter-redirector on netdev netdevid,redirect filter's net 8665 packet to chardev chardevid,and redirect indev's packet to 8666 filter.if it has the vnet\_hdr\_support flag, filter-redirector 8667 will redirect packet with vnet\_hdr\_len. Create a 8668 filter-redirector we need to differ outdev id from indev id, id 8669 can not be the same. we can just use indev or outdev, but at 8670 least one of indev or outdev need to be specified. 8671 8672 ``-object filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]`` 8673 Filter-rewriter is a part of COLO project.It will rewrite tcp 8674 packet to secondary from primary to keep secondary tcp 8675 connection,and rewrite tcp packet to primary from secondary make 8676 tcp packet can be handled by client.if it has the 8677 vnet\_hdr\_support flag, we can parse packet with vnet header. 8678 8679 usage: colo secondary: -object 8680 filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object 8681 filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object 8682 filter-rewriter,id=rew0,netdev=hn0,queue=all 8683 8684 ``-object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len][,position=head|tail|id=<id>][,insert=behind|before]`` 8685 Dump the network traffic on netdev dev to the file specified by 8686 filename. At most len bytes (64k by default) per packet are 8687 stored. The file format is libpcap, so it can be analyzed with 8688 tools such as tcpdump or Wireshark. 8689 8690 ``-object colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id]`` 8691 Colo-compare gets packet from primary\_inchardevid and 8692 secondary\_inchardevid, than compare primary packet with 8693 secondary packet. If the packets are same, we will output 8694 primary packet to outdevchardevid, else we will notify 8695 colo-frame do checkpoint and send primary packet to 8696 outdevchardevid. In order to improve efficiency, we need to put 8697 the task of comparison in another thread. If it has the 8698 vnet\_hdr\_support flag, colo compare will send/recv packet with 8699 vnet\_hdr\_len. If you want to use Xen COLO, will need the 8700 notify\_dev to notify Xen colo-frame to do checkpoint. 8701 8702 we must use it with the help of filter-mirror and 8703 filter-redirector. 8704 8705 :: 8706 8707 KVM COLO 8708 8709 primary: 8710 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 8711 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 8712 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 8713 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 8714 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 8715 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001 8716 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 8717 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005 8718 -object iothread,id=iothread1 8719 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 8720 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 8721 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 8722 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 8723 8724 secondary: 8725 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 8726 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66 8727 -chardev socket,id=red0,host=3.3.3.3,port=9003 8728 -chardev socket,id=red1,host=3.3.3.3,port=9004 8729 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 8730 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 8731 8732 8733 Xen COLO 8734 8735 primary: 8736 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 8737 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 8738 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 8739 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 8740 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 8741 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001 8742 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 8743 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005 8744 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait 8745 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 8746 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 8747 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 8748 -object iothread,id=iothread1 8749 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 8750 8751 secondary: 8752 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 8753 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66 8754 -chardev socket,id=red0,host=3.3.3.3,port=9003 8755 -chardev socket,id=red1,host=3.3.3.3,port=9004 8756 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 8757 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 8758 8759 If you want to know the detail of above command line, you can 8760 read the colo-compare git log. 8761 8762 ``-object cryptodev-backend-builtin,id=id[,queues=queues]`` 8763 Creates a cryptodev backend which executes crypto opreation from 8764 the QEMU cipher APIS. The id parameter is a unique ID that will 8765 be used to reference this cryptodev backend from the 8766 ``virtio-crypto`` device. The queues parameter is optional, 8767 which specify the queue number of cryptodev backend, the default 8768 of queues is 1. 8769 8770 .. parsed-literal:: 8771 8772 # |qemu_system| \ 8773 [...] \ 8774 -object cryptodev-backend-builtin,id=cryptodev0 \ 8775 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 8776 [...] 8777 8778 ``-object cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]`` 8779 Creates a vhost-user cryptodev backend, backed by a chardev 8780 chardevid. The id parameter is a unique ID that will be used to 8781 reference this cryptodev backend from the ``virtio-crypto`` 8782 device. The chardev should be a unix domain socket backed one. 8783 The vhost-user uses a specifically defined protocol to pass 8784 vhost ioctl replacement messages to an application on the other 8785 end of the socket. The queues parameter is optional, which 8786 specify the queue number of cryptodev backend for multiqueue 8787 vhost-user, the default of queues is 1. 8788 8789 .. parsed-literal:: 8790 8791 # |qemu_system| \ 8792 [...] \ 8793 -chardev socket,id=chardev0,path=/path/to/socket \ 8794 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 8795 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 8796 [...] 8797 8798 ``-object secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]`` 8799 \ 8800 ``-object secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]`` 8801 Defines a secret to store a password, encryption key, or some 8802 other sensitive data. The sensitive data can either be passed 8803 directly via the data parameter, or indirectly via the file 8804 parameter. Using the data parameter is insecure unless the 8805 sensitive data is encrypted. 8806 8807 The sensitive data can be provided in raw format (the default), 8808 or base64. When encoded as JSON, the raw format only supports 8809 valid UTF-8 characters, so base64 is recommended for sending 8810 binary data. QEMU will convert from which ever format is 8811 provided to the format it needs internally. eg, an RBD password 8812 can be provided in raw format, even though it will be base64 8813 encoded when passed onto the RBD sever. 8814 8815 For added protection, it is possible to encrypt the data 8816 associated with a secret using the AES-256-CBC cipher. Use of 8817 encryption is indicated by providing the keyid and iv 8818 parameters. The keyid parameter provides the ID of a previously 8819 defined secret that contains the AES-256 decryption key. This 8820 key should be 32-bytes long and be base64 encoded. The iv 8821 parameter provides the random initialization vector used for 8822 encryption of this particular secret and should be a base64 8823 encrypted string of the 16-byte IV. 8824 8825 The simplest (insecure) usage is to provide the secret inline 8826 8827 .. parsed-literal:: 8828 8829 # |qemu_system| -object secret,id=sec0,data=letmein,format=raw 8830 8831 The simplest secure usage is to provide the secret via a file 8832 8833 # printf "letmein" > mypasswd.txt # QEMU\_SYSTEM\_MACRO -object 8834 secret,id=sec0,file=mypasswd.txt,format=raw 8835 8836 For greater security, AES-256-CBC should be used. To illustrate 8837 usage, consider the openssl command line tool which can encrypt 8838 the data. Note that when encrypting, the plaintext must be 8839 padded to the cipher block size (32 bytes) using the standard 8840 PKCS#5/6 compatible padding algorithm. 8841 8842 First a master key needs to be created in base64 encoding: 8843 8844 :: 8845 8846 # openssl rand -base64 32 > key.b64 8847 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 8848 8849 Each secret to be encrypted needs to have a random 8850 initialization vector generated. These do not need to be kept 8851 secret 8852 8853 :: 8854 8855 # openssl rand -base64 16 > iv.b64 8856 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 8857 8858 The secret to be defined can now be encrypted, in this case 8859 we're telling openssl to base64 encode the result, but it could 8860 be left as raw bytes if desired. 8861 8862 :: 8863 8864 # SECRET=$(printf "letmein" | 8865 openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 8866 8867 When launching QEMU, create a master secret pointing to 8868 ``key.b64`` and specify that to be used to decrypt the user 8869 password. Pass the contents of ``iv.b64`` to the second secret 8870 8871 .. parsed-literal:: 8872 8873 # |qemu_system| \ 8874 -object secret,id=secmaster0,format=base64,file=key.b64 \ 8875 -object secret,id=sec0,keyid=secmaster0,format=base64,\ 8876 data=$SECRET,iv=$(<iv.b64) 8877 8878 ``-object sev-guest,id=id,cbitpos=cbitpos,reduced-phys-bits=val,[sev-device=string,policy=policy,handle=handle,dh-cert-file=file,session-file=file]`` 8879 Create a Secure Encrypted Virtualization (SEV) guest object, 8880 which can be used to provide the guest memory encryption support 8881 on AMD processors. 8882 8883 When memory encryption is enabled, one of the physical address 8884 bit (aka the C-bit) is utilized to mark if a memory page is 8885 protected. The ``cbitpos`` is used to provide the C-bit 8886 position. The C-bit position is Host family dependent hence user 8887 must provide this value. On EPYC, the value should be 47. 8888 8889 When memory encryption is enabled, we loose certain bits in 8890 physical address space. The ``reduced-phys-bits`` is used to 8891 provide the number of bits we loose in physical address space. 8892 Similar to C-bit, the value is Host family dependent. On EPYC, 8893 the value should be 5. 8894 8895 The ``sev-device`` provides the device file to use for 8896 communicating with the SEV firmware running inside AMD Secure 8897 Processor. The default device is '/dev/sev'. If hardware 8898 supports memory encryption then /dev/sev devices are created by 8899 CCP driver. 8900 8901 The ``policy`` provides the guest policy to be enforced by the 8902 SEV firmware and restrict what configuration and operational 8903 commands can be performed on this guest by the hypervisor. The 8904 policy should be provided by the guest owner and is bound to the 8905 guest and cannot be changed throughout the lifetime of the 8906 guest. The default is 0. 8907 8908 If guest ``policy`` allows sharing the key with another SEV 8909 guest then ``handle`` can be use to provide handle of the guest 8910 from which to share the key. 8911 8912 The ``dh-cert-file`` and ``session-file`` provides the guest 8913 owner's Public Diffie-Hillman key defined in SEV spec. The PDH 8914 and session parameters are used for establishing a cryptographic 8915 session with the guest owner to negotiate keys used for 8916 attestation. The file must be encoded in base64. 8917 8918 e.g to launch a SEV guest 8919 8920 .. parsed-literal:: 8921 8922 # |qemu_system_x86| \ 8923 ...... 8924 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 8925 -machine ...,memory-encryption=sev0 8926 ..... 8927 8928 ``-object authz-simple,id=id,identity=string`` 8929 Create an authorization object that will control access to 8930 network services. 8931 8932 The ``identity`` parameter is identifies the user and its format 8933 depends on the network service that authorization object is 8934 associated with. For authorizing based on TLS x509 certificates, 8935 the identity must be the x509 distinguished name. Note that care 8936 must be taken to escape any commas in the distinguished name. 8937 8938 An example authorization object to validate a x509 distinguished 8939 name would look like: 8940 8941 .. parsed-literal:: 8942 8943 # |qemu_system| \ 8944 ... 8945 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \ 8946 ... 8947 8948 Note the use of quotes due to the x509 distinguished name 8949 containing whitespace, and escaping of ','. 8950 8951 ``-object authz-listfile,id=id,filename=path,refresh=yes|no`` 8952 Create an authorization object that will control access to 8953 network services. 8954 8955 The ``filename`` parameter is the fully qualified path to a file 8956 containing the access control list rules in JSON format. 8957 8958 An example set of rules that match against SASL usernames might 8959 look like: 8960 8961 :: 8962 8963 { 8964 "rules": [ 8965 { "match": "fred", "policy": "allow", "format": "exact" }, 8966 { "match": "bob", "policy": "allow", "format": "exact" }, 8967 { "match": "danb", "policy": "deny", "format": "glob" }, 8968 { "match": "dan*", "policy": "allow", "format": "exact" }, 8969 ], 8970 "policy": "deny" 8971 } 8972 8973 When checking access the object will iterate over all the rules 8974 and the first rule to match will have its ``policy`` value 8975 returned as the result. If no rules match, then the default 8976 ``policy`` value is returned. 8977 8978 The rules can either be an exact string match, or they can use 8979 the simple UNIX glob pattern matching to allow wildcards to be 8980 used. 8981 8982 If ``refresh`` is set to true the file will be monitored and 8983 automatically reloaded whenever its content changes. 8984 8985 As with the ``authz-simple`` object, the format of the identity 8986 strings being matched depends on the network service, but is 8987 usually a TLS x509 distinguished name, or a SASL username. 8988 8989 An example authorization object to validate a SASL username 8990 would look like: 8991 8992 .. parsed-literal:: 8993 8994 # |qemu_system| \ 8995 ... 8996 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes 8997 ... 8998 8999 ``-object authz-pam,id=id,service=string`` 9000 Create an authorization object that will control access to 9001 network services. 9002 9003 The ``service`` parameter provides the name of a PAM service to 9004 use for authorization. It requires that a file 9005 ``/etc/pam.d/service`` exist to provide the configuration for 9006 the ``account`` subsystem. 9007 9008 An example authorization object to validate a TLS x509 9009 distinguished name would look like: 9010 9011 .. parsed-literal:: 9012 9013 # |qemu_system| \ 9014 ... 9015 -object authz-pam,id=auth0,service=qemu-vnc 9016 ... 9017 9018 There would then be a corresponding config file for PAM at 9019 ``/etc/pam.d/qemu-vnc`` that contains: 9020 9021 :: 9022 9023 account requisite pam_listfile.so item=user sense=allow \ 9024 file=/etc/qemu/vnc.allow 9025 9026 Finally the ``/etc/qemu/vnc.allow`` file would contain the list 9027 of x509 distingished names that are permitted access 9028 9029 :: 9030 9031 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB 9032 9033 ``-object iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink`` 9034 Creates a dedicated event loop thread that devices can be 9035 assigned to. This is known as an IOThread. By default device 9036 emulation happens in vCPU threads or the main event loop thread. 9037 This can become a scalability bottleneck. IOThreads allow device 9038 emulation and I/O to run on other host CPUs. 9039 9040 The ``id`` parameter is a unique ID that will be used to 9041 reference this IOThread from ``-device ...,iothread=id``. 9042 Multiple devices can be assigned to an IOThread. Note that not 9043 all devices support an ``iothread`` parameter. 9044 9045 The ``query-iothreads`` QMP command lists IOThreads and reports 9046 their thread IDs so that the user can configure host CPU 9047 pinning/affinity. 9048 9049 IOThreads use an adaptive polling algorithm to reduce event loop 9050 latency. Instead of entering a blocking system call to monitor 9051 file descriptors and then pay the cost of being woken up when an 9052 event occurs, the polling algorithm spins waiting for events for 9053 a short time. The algorithm's default parameters are suitable 9054 for many cases but can be adjusted based on knowledge of the 9055 workload and/or host device latency. 9056 9057 The ``poll-max-ns`` parameter is the maximum number of 9058 nanoseconds to busy wait for events. Polling can be disabled by 9059 setting this value to 0. 9060 9061 The ``poll-grow`` parameter is the multiplier used to increase 9062 the polling time when the algorithm detects it is missing events 9063 due to not polling long enough. 9064 9065 The ``poll-shrink`` parameter is the divisor used to decrease 9066 the polling time when the algorithm detects it is spending too 9067 long polling without encountering events. 9068 9069 The polling parameters can be modified at run-time using the 9070 ``qom-set`` command (where ``iothread1`` is the IOThread's 9071 ``id``): 9072 9073 :: 9074 9075 (qemu) qom-set /objects/iothread1 poll-max-ns 100000 9076ERST 9077 9078 9079HXCOMM This is the last statement. Insert new options before this line! 9080STEXI 9081@end table 9082ETEXI 9083
