xref: /openbmc/qemu/qemu-options.hx (revision bac4711b)
1HXCOMM Use DEFHEADING() to define headings in both help text and rST.
2HXCOMM Text between SRST and ERST is copied to the rST 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 rST and C.
8
9DEFHEADING(Standard options:)
10
11DEF("help", 0, QEMU_OPTION_h,
12    "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
13SRST
14``-h``
15    Display help and exit
16ERST
17
18DEF("version", 0, QEMU_OPTION_version,
19    "-version        display version information and exit\n", QEMU_ARCH_ALL)
20SRST
21``-version``
22    Display version information and exit
23ERST
24
25DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
26    "-machine [type=]name[,prop[=value][,...]]\n"
27    "                selects emulated machine ('-machine help' for list)\n"
28    "                property accel=accel1[:accel2[:...]] selects accelerator\n"
29    "                supported accelerators are kvm, xen, hax, hvf, nvmm, whpx or tcg (default: tcg)\n"
30    "                vmport=on|off|auto controls emulation of vmport (default: auto)\n"
31    "                dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
32    "                mem-merge=on|off controls memory merge support (default: on)\n"
33    "                aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
34    "                dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
35    "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
36    "                nvdimm=on|off controls NVDIMM support (default=off)\n"
37    "                memory-encryption=@var{} memory encryption object to use (default=none)\n"
38    "                hmat=on|off controls ACPI HMAT support (default=off)\n"
39    "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
40    "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n",
41    QEMU_ARCH_ALL)
42SRST
43``-machine [type=]name[,prop=value[,...]]``
44    Select the emulated machine by name. Use ``-machine help`` to list
45    available machines.
46
47    For architectures which aim to support live migration compatibility
48    across releases, each release will introduce a new versioned machine
49    type. For example, the 2.8.0 release introduced machine types
50    "pc-i440fx-2.8" and "pc-q35-2.8" for the x86\_64/i686 architectures.
51
52    To allow live migration of guests from QEMU version 2.8.0, to QEMU
53    version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8"
54    and "pc-q35-2.8" machines too. To allow users live migrating VMs to
55    skip multiple intermediate releases when upgrading, new releases of
56    QEMU will support machine types from many previous versions.
57
58    Supported machine properties are:
59
60    ``accel=accels1[:accels2[:...]]``
61        This is used to enable an accelerator. Depending on the target
62        architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be available.
63        By default, tcg is used. If there is more than one accelerator
64        specified, the next one is used if the previous one fails to
65        initialize.
66
67    ``vmport=on|off|auto``
68        Enables emulation of VMWare IO port, for vmmouse etc. auto says
69        to select the value based on accel. For accel=xen the default is
70        off otherwise the default is on.
71
72    ``dump-guest-core=on|off``
73        Include guest memory in a core dump. The default is on.
74
75    ``mem-merge=on|off``
76        Enables or disables memory merge support. This feature, when
77        supported by the host, de-duplicates identical memory pages
78        among VMs instances (enabled by default).
79
80    ``aes-key-wrap=on|off``
81        Enables or disables AES key wrapping support on s390-ccw hosts.
82        This feature controls whether AES wrapping keys will be created
83        to allow execution of AES cryptographic functions. The default
84        is on.
85
86    ``dea-key-wrap=on|off``
87        Enables or disables DEA key wrapping support on s390-ccw hosts.
88        This feature controls whether DEA wrapping keys will be created
89        to allow execution of DEA cryptographic functions. The default
90        is on.
91
92    ``nvdimm=on|off``
93        Enables or disables NVDIMM support. The default is off.
94
95    ``memory-encryption=``
96        Memory encryption object to use. The default is none.
97
98    ``hmat=on|off``
99        Enables or disables ACPI Heterogeneous Memory Attribute Table
100        (HMAT) support. The default is off.
101
102    ``memory-backend='id'``
103        An alternative to legacy ``-mem-path`` and ``mem-prealloc`` options.
104        Allows to use a memory backend as main RAM.
105
106        For example:
107        ::
108
109            -object memory-backend-file,id=pc.ram,size=512M,mem-path=/hugetlbfs,prealloc=on,share=on
110            -machine memory-backend=pc.ram
111            -m 512M
112
113        Migration compatibility note:
114
115        * as backend id one shall use value of 'default-ram-id', advertised by
116          machine type (available via ``query-machines`` QMP command), if migration
117          to/from old QEMU (<5.0) is expected.
118        * for machine types 4.0 and older, user shall
119          use ``x-use-canonical-path-for-ramblock-id=off`` backend option
120          if migration to/from old QEMU (<5.0) is expected.
121
122        For example:
123        ::
124
125            -object memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-ramblock-id=off
126            -machine memory-backend=pc.ram
127            -m 512M
128
129    ``cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]``
130        Define a CXL Fixed Memory Window (CFMW).
131
132        Described in the CXL 2.0 ECN: CEDT CFMWS & QTG _DSM.
133
134        They are regions of Host Physical Addresses (HPA) on a system which
135        may be interleaved across one or more CXL host bridges.  The system
136        software will assign particular devices into these windows and
137        configure the downstream Host-managed Device Memory (HDM) decoders
138        in root ports, switch ports and devices appropriately to meet the
139        interleave requirements before enabling the memory devices.
140
141        ``targets.X=target`` provides the mapping to CXL host bridges
142        which may be identified by the id provided in the -device entry.
143        Multiple entries are needed to specify all the targets when
144        the fixed memory window represents interleaved memory. X is the
145        target index from 0.
146
147        ``size=size`` sets the size of the CFMW. This must be a multiple of
148        256MiB. The region will be aligned to 256MiB but the location is
149        platform and configuration dependent.
150
151        ``interleave-granularity=granularity`` sets the granularity of
152        interleave. Default 256KiB. Only 256KiB, 512KiB, 1024KiB, 2048KiB
153        4096KiB, 8192KiB and 16384KiB granularities supported.
154
155        Example:
156
157        ::
158
159            -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512k
160ERST
161
162DEF("M", HAS_ARG, QEMU_OPTION_M,
163    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
164    QEMU_ARCH_ALL)
165
166SRST
167``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
168    Define an SGX EPC section.
169ERST
170
171DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
172    "-cpu cpu        select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
173SRST
174``-cpu model``
175    Select CPU model (``-cpu help`` for list and additional feature
176    selection)
177ERST
178
179DEF("accel", HAS_ARG, QEMU_OPTION_accel,
180    "-accel [accel=]accelerator[,prop[=value][,...]]\n"
181    "                select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)\n"
182    "                igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
183    "                kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
184    "                kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
185    "                one-insn-per-tb=on|off (one guest instruction per TCG translation block)\n"
186    "                split-wx=on|off (enable TCG split w^x mapping)\n"
187    "                tb-size=n (TCG translation block cache size)\n"
188    "                dirty-ring-size=n (KVM dirty ring GFN count, default 0)\n"
189    "                notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)\n"
190    "                thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
191SRST
192``-accel name[,prop=value[,...]]``
193    This is used to enable an accelerator. Depending on the target
194    architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be available. By
195    default, tcg is used. If there is more than one accelerator
196    specified, the next one is used if the previous one fails to
197    initialize.
198
199    ``igd-passthru=on|off``
200        When Xen is in use, this option controls whether Intel
201        integrated graphics devices can be passed through to the guest
202        (default=off)
203
204    ``kernel-irqchip=on|off|split``
205        Controls KVM in-kernel irqchip support. The default is full
206        acceleration of the interrupt controllers. On x86, split irqchip
207        reduces the kernel attack surface, at a performance cost for
208        non-MSI interrupts. Disabling the in-kernel irqchip completely
209        is not recommended except for debugging purposes.
210
211    ``kvm-shadow-mem=size``
212        Defines the size of the KVM shadow MMU.
213
214    ``one-insn-per-tb=on|off``
215        Makes the TCG accelerator put only one guest instruction into
216        each translation block. This slows down emulation a lot, but
217        can be useful in some situations, such as when trying to analyse
218        the logs produced by the ``-d`` option.
219
220    ``split-wx=on|off``
221        Controls the use of split w^x mapping for the TCG code generation
222        buffer. Some operating systems require this to be enabled, and in
223        such a case this will default on. On other operating systems, this
224        will default off, but one may enable this for testing or debugging.
225
226    ``tb-size=n``
227        Controls the size (in MiB) of the TCG translation block cache.
228
229    ``thread=single|multi``
230        Controls number of TCG threads. When the TCG is multi-threaded
231        there will be one thread per vCPU therefore taking advantage of
232        additional host cores. The default is to enable multi-threading
233        where both the back-end and front-ends support it and no
234        incompatible TCG features have been enabled (e.g.
235        icount/replay).
236
237    ``dirty-ring-size=n``
238        When the KVM accelerator is used, it controls the size of the per-vCPU
239        dirty page ring buffer (number of entries for each vCPU). It should
240        be a value that is power of two, and it should be 1024 or bigger (but
241        still less than the maximum value that the kernel supports).  4096
242        could be a good initial value if you have no idea which is the best.
243        Set this value to 0 to disable the feature.  By default, this feature
244        is disabled (dirty-ring-size=0).  When enabled, KVM will instead
245        record dirty pages in a bitmap.
246
247    ``notify-vmexit=run|internal-error|disable,notify-window=n``
248        Enables or disables notify VM exit support on x86 host and specify
249        the corresponding notify window to trigger the VM exit if enabled.
250        ``run`` option enables the feature. It does nothing and continue
251        if the exit happens. ``internal-error`` option enables the feature.
252        It raises a internal error. ``disable`` option doesn't enable the feature.
253        This feature can mitigate the CPU stuck issue due to event windows don't
254        open up for a specified of time (i.e. notify-window).
255        Default: notify-vmexit=run,notify-window=0.
256
257ERST
258
259DEF("smp", HAS_ARG, QEMU_OPTION_smp,
260    "-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]\n"
261    "                set the number of initial CPUs to 'n' [default=1]\n"
262    "                maxcpus= maximum number of total CPUs, including\n"
263    "                offline CPUs for hotplug, etc\n"
264    "                sockets= number of sockets on the machine board\n"
265    "                dies= number of dies in one socket\n"
266    "                clusters= number of clusters in one die\n"
267    "                cores= number of cores in one cluster\n"
268    "                threads= number of threads in one core\n"
269    "Note: Different machines may have different subsets of the CPU topology\n"
270    "      parameters supported, so the actual meaning of the supported parameters\n"
271    "      will vary accordingly. For example, for a machine type that supports a\n"
272    "      three-level CPU hierarchy of sockets/cores/threads, the parameters will\n"
273    "      sequentially mean as below:\n"
274    "                sockets means the number of sockets on the machine board\n"
275    "                cores means the number of cores in one socket\n"
276    "                threads means the number of threads in one core\n"
277    "      For a particular machine type board, an expected CPU topology hierarchy\n"
278    "      can be defined through the supported sub-option. Unsupported parameters\n"
279    "      can also be provided in addition to the sub-option, but their values\n"
280    "      must be set as 1 in the purpose of correct parsing.\n",
281    QEMU_ARCH_ALL)
282SRST
283``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]``
284    Simulate a SMP system with '\ ``n``\ ' CPUs initially present on
285    the machine type board. On boards supporting CPU hotplug, the optional
286    '\ ``maxcpus``\ ' parameter can be set to enable further CPUs to be
287    added at runtime. When both parameters are omitted, the maximum number
288    of CPUs will be calculated from the provided topology members and the
289    initial CPU count will match the maximum number. When only one of them
290    is given then the omitted one will be set to its counterpart's value.
291    Both parameters may be specified, but the maximum number of CPUs must
292    be equal to or greater than the initial CPU count. Product of the
293    CPU topology hierarchy must be equal to the maximum number of CPUs.
294    Both parameters are subject to an upper limit that is determined by
295    the specific machine type chosen.
296
297    To control reporting of CPU topology information, values of the topology
298    parameters can be specified. Machines may only support a subset of the
299    parameters and different machines may have different subsets supported
300    which vary depending on capacity of the corresponding CPU targets. So
301    for a particular machine type board, an expected topology hierarchy can
302    be defined through the supported sub-option. Unsupported parameters can
303    also be provided in addition to the sub-option, but their values must be
304    set as 1 in the purpose of correct parsing.
305
306    Either the initial CPU count, or at least one of the topology parameters
307    must be specified. The specified parameters must be greater than zero,
308    explicit configuration like "cpus=0" is not allowed. Values for any
309    omitted parameters will be computed from those which are given.
310
311    For example, the following sub-option defines a CPU topology hierarchy
312    (2 sockets totally on the machine, 2 cores per socket, 2 threads per
313    core) for a machine that only supports sockets/cores/threads.
314    Some members of the option can be omitted but their values will be
315    automatically computed:
316
317    ::
318
319        -smp 8,sockets=2,cores=2,threads=2,maxcpus=8
320
321    The following sub-option defines a CPU topology hierarchy (2 sockets
322    totally on the machine, 2 dies per socket, 2 cores per die, 2 threads
323    per core) for PC machines which support sockets/dies/cores/threads.
324    Some members of the option can be omitted but their values will be
325    automatically computed:
326
327    ::
328
329        -smp 16,sockets=2,dies=2,cores=2,threads=2,maxcpus=16
330
331    The following sub-option defines a CPU topology hierarchy (2 sockets
332    totally on the machine, 2 clusters per socket, 2 cores per cluster,
333    2 threads per core) for ARM virt machines which support sockets/clusters
334    /cores/threads. Some members of the option can be omitted but their values
335    will be automatically computed:
336
337    ::
338
339        -smp 16,sockets=2,clusters=2,cores=2,threads=2,maxcpus=16
340
341    Historically preference was given to the coarsest topology parameters
342    when computing missing values (ie sockets preferred over cores, which
343    were preferred over threads), however, this behaviour is considered
344    liable to change. Prior to 6.2 the preference was sockets over cores
345    over threads. Since 6.2 the preference is cores over sockets over threads.
346
347    For example, the following option defines a machine board with 2 sockets
348    of 1 core before 6.2 and 1 socket of 2 cores after 6.2:
349
350    ::
351
352        -smp 2
353
354    Note: The cluster topology will only be generated in ACPI and exposed
355    to guest if it's explicitly specified in -smp.
356ERST
357
358DEF("numa", HAS_ARG, QEMU_OPTION_numa,
359    "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
360    "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
361    "-numa dist,src=source,dst=destination,val=distance\n"
362    "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
363    "-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"
364    "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
365    QEMU_ARCH_ALL)
366SRST
367``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
368  \
369``-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
370  \
371``-numa dist,src=source,dst=destination,val=distance``
372  \
373``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``
374  \
375``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=type[,latency=lat][,bandwidth=bw]``
376  \
377``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
378    Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
379    distance from a source node to a destination node. Set the ACPI
380    Heterogeneous Memory Attributes for the given nodes.
381
382    Legacy VCPU assignment uses '\ ``cpus``\ ' option where firstcpu and
383    lastcpu are CPU indexes. Each '\ ``cpus``\ ' option represent a
384    contiguous range of CPU indexes (or a single VCPU if lastcpu is
385    omitted). A non-contiguous set of VCPUs can be represented by
386    providing multiple '\ ``cpus``\ ' options. If '\ ``cpus``\ ' is
387    omitted on all nodes, VCPUs are automatically split between them.
388
389    For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
390    NUMA node:
391
392    ::
393
394        -numa node,cpus=0-2,cpus=5
395
396    '\ ``cpu``\ ' option is a new alternative to '\ ``cpus``\ ' option
397    which uses '\ ``socket-id|core-id|thread-id``\ ' properties to
398    assign CPU objects to a node using topology layout properties of
399    CPU. The set of properties is machine specific, and depends on used
400    machine type/'\ ``smp``\ ' options. It could be queried with
401    '\ ``hotpluggable-cpus``\ ' monitor command. '\ ``node-id``\ '
402    property specifies node to which CPU object will be assigned, it's
403    required for node to be declared with '\ ``node``\ ' option before
404    it's used with '\ ``cpu``\ ' option.
405
406    For example:
407
408    ::
409
410        -M pc \
411        -smp 1,sockets=2,maxcpus=2 \
412        -numa node,nodeid=0 -numa node,nodeid=1 \
413        -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
414
415    '\ ``memdev``\ ' option assigns RAM from a given memory backend
416    device to a node. It is recommended to use '\ ``memdev``\ ' option
417    over legacy '\ ``mem``\ ' option. This is because '\ ``memdev``\ '
418    option provides better performance and more control over the
419    backend's RAM (e.g. '\ ``prealloc``\ ' parameter of
420    '\ ``-memory-backend-ram``\ ' allows memory preallocation).
421
422    For compatibility reasons, legacy '\ ``mem``\ ' option is
423    supported in 5.0 and older machine types. Note that '\ ``mem``\ '
424    and '\ ``memdev``\ ' are mutually exclusive. If one node uses
425    '\ ``memdev``\ ', the rest nodes have to use '\ ``memdev``\ '
426    option, and vice versa.
427
428    Users must specify memory for all NUMA nodes by '\ ``memdev``\ '
429    (or legacy '\ ``mem``\ ' if available). In QEMU 5.2, the support
430    for '\ ``-numa node``\ ' without memory specified was removed.
431
432    '\ ``initiator``\ ' is an additional option that points to an
433    initiator NUMA node that has best performance (the lowest latency or
434    largest bandwidth) to this NUMA node. Note that this option can be
435    set only when the machine property 'hmat' is set to 'on'.
436
437    Following example creates a machine with 2 NUMA nodes, node 0 has
438    CPU. node 1 has only memory, and its initiator is node 0. Note that
439    because node 0 has CPU, by default the initiator of node 0 is itself
440    and must be itself.
441
442    ::
443
444        -machine hmat=on \
445        -m 2G,slots=2,maxmem=4G \
446        -object memory-backend-ram,size=1G,id=m0 \
447        -object memory-backend-ram,size=1G,id=m1 \
448        -numa node,nodeid=0,memdev=m0 \
449        -numa node,nodeid=1,memdev=m1,initiator=0 \
450        -smp 2,sockets=2,maxcpus=2  \
451        -numa cpu,node-id=0,socket-id=0 \
452        -numa cpu,node-id=0,socket-id=1
453
454    source and destination are NUMA node IDs. distance is the NUMA
455    distance from source to destination. The distance from a node to
456    itself is always 10. If any pair of nodes is given a distance, then
457    all pairs must be given distances. Although, when distances are only
458    given in one direction for each pair of nodes, then the distances in
459    the opposite directions are assumed to be the same. If, however, an
460    asymmetrical pair of distances is given for even one node pair, then
461    all node pairs must be provided distance values for both directions,
462    even when they are symmetrical. When a node is unreachable from
463    another node, set the pair's distance to 255.
464
465    Note that the -``numa`` option doesn't allocate any of the specified
466    resources, it just assigns existing resources to NUMA nodes. This
467    means that one still has to use the ``-m``, ``-smp`` options to
468    allocate RAM and VCPUs respectively.
469
470    Use '\ ``hmat-lb``\ ' to set System Locality Latency and Bandwidth
471    Information between initiator and target NUMA nodes in ACPI
472    Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can
473    create memory requests, usually it has one or more processors.
474    Target NUMA node contains addressable memory.
475
476    In '\ ``hmat-lb``\ ' option, node are NUMA node IDs. hierarchy is
477    the memory hierarchy of the target NUMA node: if hierarchy is
478    'memory', the structure represents the memory performance; if
479    hierarchy is 'first-level\|second-level\|third-level', this
480    structure represents aggregated performance of memory side caches
481    for each domain. type of 'data-type' is type of data represented by
482    this structure instance: if 'hierarchy' is 'memory', 'data-type' is
483    'access\|read\|write' latency or 'access\|read\|write' bandwidth of
484    the target memory; if 'hierarchy' is
485    'first-level\|second-level\|third-level', 'data-type' is
486    'access\|read\|write' hit latency or 'access\|read\|write' hit
487    bandwidth of the target memory side cache.
488
489    lat is latency value in nanoseconds. bw is bandwidth value, the
490    possible value and units are NUM[M\|G\|T], mean that the bandwidth
491    value are NUM byte per second (or MB/s, GB/s or TB/s depending on
492    used suffix). Note that if latency or bandwidth value is 0, means
493    the corresponding latency or bandwidth information is not provided.
494
495    In '\ ``hmat-cache``\ ' option, node-id is the NUMA-id of the memory
496    belongs. size is the size of memory side cache in bytes. level is
497    the cache level described in this structure, note that the cache
498    level 0 should not be used with '\ ``hmat-cache``\ ' option.
499    associativity is the cache associativity, the possible value is
500    'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
501    is the write policy. line is the cache Line size in bytes.
502
503    For example, the following options describe 2 NUMA nodes. Node 0 has
504    2 cpus and a ram, node 1 has only a ram. The processors in node 0
505    access memory in node 0 with access-latency 5 nanoseconds,
506    access-bandwidth is 200 MB/s; The processors in NUMA node 0 access
507    memory in NUMA node 1 with access-latency 10 nanoseconds,
508    access-bandwidth is 100 MB/s. And for memory side cache information,
509    NUMA node 0 and 1 both have 1 level memory cache, size is 10KB,
510    policy is write-back, the cache Line size is 8 bytes:
511
512    ::
513
514        -machine hmat=on \
515        -m 2G \
516        -object memory-backend-ram,size=1G,id=m0 \
517        -object memory-backend-ram,size=1G,id=m1 \
518        -smp 2,sockets=2,maxcpus=2 \
519        -numa node,nodeid=0,memdev=m0 \
520        -numa node,nodeid=1,memdev=m1,initiator=0 \
521        -numa cpu,node-id=0,socket-id=0 \
522        -numa cpu,node-id=0,socket-id=1 \
523        -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
524        -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
525        -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
526        -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
527        -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
528        -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
529ERST
530
531DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
532    "-add-fd fd=fd,set=set[,opaque=opaque]\n"
533    "                Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
534SRST
535``-add-fd fd=fd,set=set[,opaque=opaque]``
536    Add a file descriptor to an fd set. Valid options are:
537
538    ``fd=fd``
539        This option defines the file descriptor of which a duplicate is
540        added to fd set. The file descriptor cannot be stdin, stdout, or
541        stderr.
542
543    ``set=set``
544        This option defines the ID of the fd set to add the file
545        descriptor to.
546
547    ``opaque=opaque``
548        This option defines a free-form string that can be used to
549        describe fd.
550
551    You can open an image using pre-opened file descriptors from an fd
552    set:
553
554    .. parsed-literal::
555
556        |qemu_system| \\
557         -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \\
558         -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \\
559         -drive file=/dev/fdset/2,index=0,media=disk
560ERST
561
562DEF("set", HAS_ARG, QEMU_OPTION_set,
563    "-set group.id.arg=value\n"
564    "                set <arg> parameter for item <id> of type <group>\n"
565    "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
566SRST
567``-set group.id.arg=value``
568    Set parameter arg for item id of type group
569ERST
570
571DEF("global", HAS_ARG, QEMU_OPTION_global,
572    "-global driver.property=value\n"
573    "-global driver=driver,property=property,value=value\n"
574    "                set a global default for a driver property\n",
575    QEMU_ARCH_ALL)
576SRST
577``-global driver.prop=value``
578  \
579``-global driver=driver,property=property,value=value``
580    Set default value of driver's property prop to value, e.g.:
581
582    .. parsed-literal::
583
584        |qemu_system_x86| -global ide-hd.physical_block_size=4096 disk-image.img
585
586    In particular, you can use this to set driver properties for devices
587    which are created automatically by the machine model. To create a
588    device which is not created automatically and set properties on it,
589    use -``device``.
590
591    -global driver.prop=value is shorthand for -global
592    driver=driver,property=prop,value=value. The longhand syntax works
593    even when driver contains a dot.
594ERST
595
596DEF("boot", HAS_ARG, QEMU_OPTION_boot,
597    "-boot [order=drives][,once=drives][,menu=on|off]\n"
598    "      [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
599    "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
600    "                'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
601    "                'sp_time': the period that splash picture last if menu=on, unit is ms\n"
602    "                'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
603    QEMU_ARCH_ALL)
604SRST
605``-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]``
606    Specify boot order drives as a string of drive letters. Valid drive
607    letters depend on the target architecture. The x86 PC uses: a, b
608    (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
609    (Etherboot from network adapter 1-4), hard disk boot is the default.
610    To apply a particular boot order only on the first startup, specify
611    it via ``once``. Note that the ``order`` or ``once`` parameter
612    should not be used together with the ``bootindex`` property of
613    devices, since the firmware implementations normally do not support
614    both at the same time.
615
616    Interactive boot menus/prompts can be enabled via ``menu=on`` as far
617    as firmware/BIOS supports them. The default is non-interactive boot.
618
619    A splash picture could be passed to bios, enabling user to show it
620    as logo, when option splash=sp\_name is given and menu=on, If
621    firmware/BIOS supports them. Currently Seabios for X86 system
622    support it. limitation: The splash file could be a jpeg file or a
623    BMP file in 24 BPP format(true color). The resolution should be
624    supported by the SVGA mode, so the recommended is 320x240, 640x480,
625    800x640.
626
627    A timeout could be passed to bios, guest will pause for rb\_timeout
628    ms when boot failed, then reboot. If rb\_timeout is '-1', guest will
629    not reboot, qemu passes '-1' to bios by default. Currently Seabios
630    for X86 system support it.
631
632    Do strict boot via ``strict=on`` as far as firmware/BIOS supports
633    it. This only effects when boot priority is changed by bootindex
634    options. The default is non-strict boot.
635
636    .. parsed-literal::
637
638        # try to boot from network first, then from hard disk
639        |qemu_system_x86| -boot order=nc
640        # boot from CD-ROM first, switch back to default order after reboot
641        |qemu_system_x86| -boot once=d
642        # boot with a splash picture for 5 seconds.
643        |qemu_system_x86| -boot menu=on,splash=/root/boot.bmp,splash-time=5000
644
645    Note: The legacy format '-boot drives' is still supported but its
646    use is discouraged as it may be removed from future versions.
647ERST
648
649DEF("m", HAS_ARG, QEMU_OPTION_m,
650    "-m [size=]megs[,slots=n,maxmem=size]\n"
651    "                configure guest RAM\n"
652    "                size: initial amount of guest memory\n"
653    "                slots: number of hotplug slots (default: none)\n"
654    "                maxmem: maximum amount of guest memory (default: none)\n"
655    "                Note: Some architectures might enforce a specific granularity\n",
656    QEMU_ARCH_ALL)
657SRST
658``-m [size=]megs[,slots=n,maxmem=size]``
659    Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
660    Optionally, a suffix of "M" or "G" can be used to signify a value in
661    megabytes or gigabytes respectively. Optional pair slots, maxmem
662    could be used to set amount of hotpluggable memory slots and maximum
663    amount of memory. Note that maxmem must be aligned to the page size.
664
665    For example, the following command-line sets the guest startup RAM
666    size to 1GB, creates 3 slots to hotplug additional memory and sets
667    the maximum memory the guest can reach to 4GB:
668
669    .. parsed-literal::
670
671        |qemu_system| -m 1G,slots=3,maxmem=4G
672
673    If slots and maxmem are not specified, memory hotplug won't be
674    enabled and the guest startup RAM will never increase.
675ERST
676
677DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
678    "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
679SRST
680``-mem-path path``
681    Allocate guest RAM from a temporarily created file in path.
682ERST
683
684DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
685    "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
686    QEMU_ARCH_ALL)
687SRST
688``-mem-prealloc``
689    Preallocate memory when using -mem-path.
690ERST
691
692DEF("k", HAS_ARG, QEMU_OPTION_k,
693    "-k language     use keyboard layout (for example 'fr' for French)\n",
694    QEMU_ARCH_ALL)
695SRST
696``-k language``
697    Use keyboard layout language (for example ``fr`` for French). This
698    option is only needed where it is not easy to get raw PC keycodes
699    (e.g. on Macs, with some X11 servers or with a VNC or curses
700    display). You don't normally need to use it on PC/Linux or
701    PC/Windows hosts.
702
703    The available layouts are:
704
705    ::
706
707        ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
708        da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
709        de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
710
711    The default is ``en-us``.
712ERST
713
714
715HXCOMM Deprecated by -audiodev
716DEF("audio-help", 0, QEMU_OPTION_audio_help,
717    "-audio-help     show -audiodev equivalent of the currently specified audio settings\n",
718    QEMU_ARCH_ALL)
719SRST
720``-audio-help``
721    Will show the -audiodev equivalent of the currently specified
722    (deprecated) environment variables.
723ERST
724
725DEF("audio", HAS_ARG, QEMU_OPTION_audio,
726    "-audio [driver=]driver,model=value[,prop[=value][,...]]\n"
727    "                specifies the audio backend and device to use;\n"
728    "                apart from 'model', options are the same as for -audiodev.\n"
729    "                use '-audio model=help' to show possible devices.\n",
730    QEMU_ARCH_ALL)
731SRST
732``-audio [driver=]driver,model=value[,prop[=value][,...]]``
733    This option is a shortcut for configuring both the guest audio
734    hardware and the host audio backend in one go.
735    The driver option is the same as with the corresponding ``-audiodev`` option below.
736    The guest hardware model can be set with ``model=modelname``.
737
738    Use ``driver=help`` to list the available drivers,
739    and ``model=help`` to list the available device types.
740
741    The following two example do exactly the same, to show how ``-audio``
742    can be used to shorten the command line length:
743
744    .. parsed-literal::
745
746        |qemu_system| -audiodev pa,id=pa -device sb16,audiodev=pa
747        |qemu_system| -audio pa,model=sb16
748ERST
749
750DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
751    "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
752    "                specifies the audio backend to use\n"
753    "                Use ``-audiodev help`` to list the available drivers\n"
754    "                id= identifier of the backend\n"
755    "                timer-period= timer period in microseconds\n"
756    "                in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
757    "                in|out.fixed-settings= use fixed settings for host audio\n"
758    "                in|out.frequency= frequency to use with fixed settings\n"
759    "                in|out.channels= number of channels to use with fixed settings\n"
760    "                in|out.format= sample format to use with fixed settings\n"
761    "                valid values: s8, s16, s32, u8, u16, u32, f32\n"
762    "                in|out.voices= number of voices to use\n"
763    "                in|out.buffer-length= length of buffer in microseconds\n"
764    "-audiodev none,id=id,[,prop[=value][,...]]\n"
765    "                dummy driver that discards all output\n"
766#ifdef CONFIG_AUDIO_ALSA
767    "-audiodev alsa,id=id[,prop[=value][,...]]\n"
768    "                in|out.dev= name of the audio device to use\n"
769    "                in|out.period-length= length of period in microseconds\n"
770    "                in|out.try-poll= attempt to use poll mode\n"
771    "                threshold= threshold (in microseconds) when playback starts\n"
772#endif
773#ifdef CONFIG_AUDIO_COREAUDIO
774    "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
775    "                in|out.buffer-count= number of buffers\n"
776#endif
777#ifdef CONFIG_AUDIO_DSOUND
778    "-audiodev dsound,id=id[,prop[=value][,...]]\n"
779    "                latency= add extra latency to playback in microseconds\n"
780#endif
781#ifdef CONFIG_AUDIO_OSS
782    "-audiodev oss,id=id[,prop[=value][,...]]\n"
783    "                in|out.dev= path of the audio device to use\n"
784    "                in|out.buffer-count= number of buffers\n"
785    "                in|out.try-poll= attempt to use poll mode\n"
786    "                try-mmap= try using memory mapped access\n"
787    "                exclusive= open device in exclusive mode\n"
788    "                dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
789#endif
790#ifdef CONFIG_AUDIO_PA
791    "-audiodev pa,id=id[,prop[=value][,...]]\n"
792    "                server= PulseAudio server address\n"
793    "                in|out.name= source/sink device name\n"
794    "                in|out.latency= desired latency in microseconds\n"
795#endif
796#ifdef CONFIG_AUDIO_PIPEWIRE
797    "-audiodev pipewire,id=id[,prop[=value][,...]]\n"
798    "                in|out.name= source/sink device name\n"
799    "                in|out.stream-name= name of pipewire stream\n"
800    "                in|out.latency= desired latency in microseconds\n"
801#endif
802#ifdef CONFIG_AUDIO_SDL
803    "-audiodev sdl,id=id[,prop[=value][,...]]\n"
804    "                in|out.buffer-count= number of buffers\n"
805#endif
806#ifdef CONFIG_AUDIO_SNDIO
807    "-audiodev sndio,id=id[,prop[=value][,...]]\n"
808#endif
809#ifdef CONFIG_SPICE
810    "-audiodev spice,id=id[,prop[=value][,...]]\n"
811#endif
812#ifdef CONFIG_DBUS_DISPLAY
813    "-audiodev dbus,id=id[,prop[=value][,...]]\n"
814#endif
815    "-audiodev wav,id=id[,prop[=value][,...]]\n"
816    "                path= path of wav file to record\n",
817    QEMU_ARCH_ALL)
818SRST
819``-audiodev [driver=]driver,id=id[,prop[=value][,...]]``
820    Adds a new audio backend driver identified by id. There are global
821    and driver specific properties. Some values can be set differently
822    for input and output, they're marked with ``in|out.``. You can set
823    the input's property with ``in.prop`` and the output's property with
824    ``out.prop``. For example:
825
826    ::
827
828        -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
829        -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
830
831    NOTE: parameter validation is known to be incomplete, in many cases
832    specifying an invalid option causes QEMU to print an error message
833    and continue emulation without sound.
834
835    Valid global options are:
836
837    ``id=identifier``
838        Identifies the audio backend.
839
840    ``timer-period=period``
841        Sets the timer period used by the audio subsystem in
842        microseconds. Default is 10000 (10 ms).
843
844    ``in|out.mixing-engine=on|off``
845        Use QEMU's mixing engine to mix all streams inside QEMU and
846        convert audio formats when not supported by the backend. When
847        off, fixed-settings must be off too. Note that disabling this
848        option means that the selected backend must support multiple
849        streams and the audio formats used by the virtual cards,
850        otherwise you'll get no sound. It's not recommended to disable
851        this option unless you want to use 5.1 or 7.1 audio, as mixing
852        engine only supports mono and stereo audio. Default is on.
853
854    ``in|out.fixed-settings=on|off``
855        Use fixed settings for host audio. When off, it will change
856        based on how the guest opens the sound card. In this case you
857        must not specify frequency, channels or format. Default is on.
858
859    ``in|out.frequency=frequency``
860        Specify the frequency to use when using fixed-settings. Default
861        is 44100Hz.
862
863    ``in|out.channels=channels``
864        Specify the number of channels to use when using fixed-settings.
865        Default is 2 (stereo).
866
867    ``in|out.format=format``
868        Specify the sample format to use when using fixed-settings.
869        Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``,
870        ``u32``, ``f32``. Default is ``s16``.
871
872    ``in|out.voices=voices``
873        Specify the number of voices to use. Default is 1.
874
875    ``in|out.buffer-length=usecs``
876        Sets the size of the buffer in microseconds.
877
878``-audiodev none,id=id[,prop[=value][,...]]``
879    Creates a dummy backend that discards all outputs. This backend has
880    no backend specific properties.
881
882``-audiodev alsa,id=id[,prop[=value][,...]]``
883    Creates backend using the ALSA. This backend is only available on
884    Linux.
885
886    ALSA specific options are:
887
888    ``in|out.dev=device``
889        Specify the ALSA device to use for input and/or output. Default
890        is ``default``.
891
892    ``in|out.period-length=usecs``
893        Sets the period length in microseconds.
894
895    ``in|out.try-poll=on|off``
896        Attempt to use poll mode with the device. Default is on.
897
898    ``threshold=threshold``
899        Threshold (in microseconds) when playback starts. Default is 0.
900
901``-audiodev coreaudio,id=id[,prop[=value][,...]]``
902    Creates a backend using Apple's Core Audio. This backend is only
903    available on Mac OS and only supports playback.
904
905    Core Audio specific options are:
906
907    ``in|out.buffer-count=count``
908        Sets the count of the buffers.
909
910``-audiodev dsound,id=id[,prop[=value][,...]]``
911    Creates a backend using Microsoft's DirectSound. This backend is
912    only available on Windows and only supports playback.
913
914    DirectSound specific options are:
915
916    ``latency=usecs``
917        Add extra usecs microseconds latency to playback. Default is
918        10000 (10 ms).
919
920``-audiodev oss,id=id[,prop[=value][,...]]``
921    Creates a backend using OSS. This backend is available on most
922    Unix-like systems.
923
924    OSS specific options are:
925
926    ``in|out.dev=device``
927        Specify the file name of the OSS device to use. Default is
928        ``/dev/dsp``.
929
930    ``in|out.buffer-count=count``
931        Sets the count of the buffers.
932
933    ``in|out.try-poll=on|of``
934        Attempt to use poll mode with the device. Default is on.
935
936    ``try-mmap=on|off``
937        Try using memory mapped device access. Default is off.
938
939    ``exclusive=on|off``
940        Open the device in exclusive mode (vmix won't work in this
941        case). Default is off.
942
943    ``dsp-policy=policy``
944        Sets the timing policy (between 0 and 10, where smaller number
945        means smaller latency but higher CPU usage). Use -1 to use
946        buffer sizes specified by ``buffer`` and ``buffer-count``. This
947        option is ignored if you do not have OSS 4. Default is 5.
948
949``-audiodev pa,id=id[,prop[=value][,...]]``
950    Creates a backend using PulseAudio. This backend is available on
951    most systems.
952
953    PulseAudio specific options are:
954
955    ``server=server``
956        Sets the PulseAudio server to connect to.
957
958    ``in|out.name=sink``
959        Use the specified source/sink for recording/playback.
960
961    ``in|out.latency=usecs``
962        Desired latency in microseconds. The PulseAudio server will try
963        to honor this value but actual latencies may be lower or higher.
964
965``-audiodev pipewire,id=id[,prop[=value][,...]]``
966    Creates a backend using Pipewire. This backend is available on
967    most systems.
968
969    Pipewire specific options are:
970
971    ``in|out.latency=usecs``
972        Desired latency in microseconds.
973
974    ``in|out.name=sink``
975        Use the specified source/sink for recording/playback.
976
977    ``in|out.stream-name``
978        Specify the name of pipewire stream.
979
980``-audiodev sdl,id=id[,prop[=value][,...]]``
981    Creates a backend using SDL. This backend is available on most
982    systems, but you should use your platform's native backend if
983    possible.
984
985    SDL specific options are:
986
987    ``in|out.buffer-count=count``
988        Sets the count of the buffers.
989
990``-audiodev sndio,id=id[,prop[=value][,...]]``
991    Creates a backend using SNDIO. This backend is available on
992    OpenBSD and most other Unix-like systems.
993
994    Sndio specific options are:
995
996    ``in|out.dev=device``
997        Specify the sndio device to use for input and/or output. Default
998        is ``default``.
999
1000    ``in|out.latency=usecs``
1001        Sets the desired period length in microseconds.
1002
1003``-audiodev spice,id=id[,prop[=value][,...]]``
1004    Creates a backend that sends audio through SPICE. This backend
1005    requires ``-spice`` and automatically selected in that case, so
1006    usually you can ignore this option. This backend has no backend
1007    specific properties.
1008
1009``-audiodev wav,id=id[,prop[=value][,...]]``
1010    Creates a backend that writes audio to a WAV file.
1011
1012    Backend specific options are:
1013
1014    ``path=path``
1015        Write recorded audio into the specified file. Default is
1016        ``qemu.wav``.
1017ERST
1018
1019DEF("device", HAS_ARG, QEMU_OPTION_device,
1020    "-device driver[,prop[=value][,...]]\n"
1021    "                add device (based on driver)\n"
1022    "                prop=value,... sets driver properties\n"
1023    "                use '-device help' to print all possible drivers\n"
1024    "                use '-device driver,help' to print all possible properties\n",
1025    QEMU_ARCH_ALL)
1026SRST
1027``-device driver[,prop[=value][,...]]``
1028    Add device driver. prop=value sets driver properties. Valid
1029    properties depend on the driver. To get help on possible drivers and
1030    properties, use ``-device help`` and ``-device driver,help``.
1031
1032    Some drivers are:
1033
1034``-device ipmi-bmc-sim,id=id[,prop[=value][,...]]``
1035    Add an IPMI BMC. This is a simulation of a hardware management
1036    interface processor that normally sits on a system. It provides a
1037    watchdog and the ability to reset and power control the system. You
1038    need to connect this to an IPMI interface to make it useful
1039
1040    The IPMI slave address to use for the BMC. The default is 0x20. This
1041    address is the BMC's address on the I2C network of management
1042    controllers. If you don't know what this means, it is safe to ignore
1043    it.
1044
1045    ``id=id``
1046        The BMC id for interfaces to use this device.
1047
1048    ``slave_addr=val``
1049        Define slave address to use for the BMC. The default is 0x20.
1050
1051    ``sdrfile=file``
1052        file containing raw Sensor Data Records (SDR) data. The default
1053        is none.
1054
1055    ``fruareasize=val``
1056        size of a Field Replaceable Unit (FRU) area. The default is
1057        1024.
1058
1059    ``frudatafile=file``
1060        file containing raw Field Replaceable Unit (FRU) inventory data.
1061        The default is none.
1062
1063    ``guid=uuid``
1064        value for the GUID for the BMC, in standard UUID format. If this
1065        is set, get "Get GUID" command to the BMC will return it.
1066        Otherwise "Get GUID" will return an error.
1067
1068``-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]``
1069    Add a connection to an external IPMI BMC simulator. Instead of
1070    locally emulating the BMC like the above item, instead connect to an
1071    external entity that provides the IPMI services.
1072
1073    A connection is made to an external BMC simulator. If you do this,
1074    it is strongly recommended that you use the "reconnect=" chardev
1075    option to reconnect to the simulator if the connection is lost. Note
1076    that if this is not used carefully, it can be a security issue, as
1077    the interface has the ability to send resets, NMIs, and power off
1078    the VM. It's best if QEMU makes a connection to an external
1079    simulator running on a secure port on localhost, so neither the
1080    simulator nor QEMU is exposed to any outside network.
1081
1082    See the "lanserv/README.vm" file in the OpenIPMI library for more
1083    details on the external interface.
1084
1085``-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]``
1086    Add a KCS IPMI interface on the ISA bus. This also adds a
1087    corresponding ACPI and SMBIOS entries, if appropriate.
1088
1089    ``bmc=id``
1090        The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
1091        above.
1092
1093    ``ioport=val``
1094        Define the I/O address of the interface. The default is 0xca0
1095        for KCS.
1096
1097    ``irq=val``
1098        Define the interrupt to use. The default is 5. To disable
1099        interrupts, set this to 0.
1100
1101``-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]``
1102    Like the KCS interface, but defines a BT interface. The default port
1103    is 0xe4 and the default interrupt is 5.
1104
1105``-device pci-ipmi-kcs,bmc=id``
1106    Add a KCS IPMI interface on the PCI bus.
1107
1108    ``bmc=id``
1109        The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
1110
1111``-device pci-ipmi-bt,bmc=id``
1112    Like the KCS interface, but defines a BT interface on the PCI bus.
1113
1114``-device intel-iommu[,option=...]``
1115    This is only supported by ``-machine q35``, which will enable Intel VT-d
1116    emulation within the guest.  It supports below options:
1117
1118    ``intremap=on|off`` (default: auto)
1119        This enables interrupt remapping feature.  It's required to enable
1120        complete x2apic.  Currently it only supports kvm kernel-irqchip modes
1121        ``off`` or ``split``, while full kernel-irqchip is not yet supported.
1122        The default value is "auto", which will be decided by the mode of
1123        kernel-irqchip.
1124
1125    ``caching-mode=on|off`` (default: off)
1126        This enables caching mode for the VT-d emulated device.  When
1127        caching-mode is enabled, each guest DMA buffer mapping will generate an
1128        IOTLB invalidation from the guest IOMMU driver to the vIOMMU device in
1129        a synchronous way.  It is required for ``-device vfio-pci`` to work
1130        with the VT-d device, because host assigned devices requires to setup
1131        the DMA mapping on the host before guest DMA starts.
1132
1133    ``device-iotlb=on|off`` (default: off)
1134        This enables device-iotlb capability for the emulated VT-d device.  So
1135        far virtio/vhost should be the only real user for this parameter,
1136        paired with ats=on configured for the device.
1137
1138    ``aw-bits=39|48`` (default: 39)
1139        This decides the address width of IOVA address space.  The address
1140        space has 39 bits width for 3-level IOMMU page tables, and 48 bits for
1141        4-level IOMMU page tables.
1142
1143    Please also refer to the wiki page for general scenarios of VT-d
1144    emulation in QEMU: https://wiki.qemu.org/Features/VT-d.
1145
1146ERST
1147
1148DEF("name", HAS_ARG, QEMU_OPTION_name,
1149    "-name string1[,process=string2][,debug-threads=on|off]\n"
1150    "                set the name of the guest\n"
1151    "                string1 sets the window title and string2 the process name\n"
1152    "                When debug-threads is enabled, individual threads are given a separate name\n"
1153    "                NOTE: The thread names are for debugging and not a stable API.\n",
1154    QEMU_ARCH_ALL)
1155SRST
1156``-name name``
1157    Sets the name of the guest. This name will be displayed in the SDL
1158    window caption. The name will also be used for the VNC server. Also
1159    optionally set the top visible process name in Linux. Naming of
1160    individual threads can also be enabled on Linux to aid debugging.
1161ERST
1162
1163DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
1164    "-uuid %08x-%04x-%04x-%04x-%012x\n"
1165    "                specify machine UUID\n", QEMU_ARCH_ALL)
1166SRST
1167``-uuid uuid``
1168    Set system UUID.
1169ERST
1170
1171DEFHEADING()
1172
1173DEFHEADING(Block device options:)
1174
1175SRST
1176The QEMU block device handling options have a long history and
1177have gone through several iterations as the feature set and complexity
1178of the block layer have grown. Many online guides to QEMU often
1179reference older and deprecated options, which can lead to confusion.
1180
1181The most explicit way to describe disks is to use a combination of
1182``-device`` to specify the hardware device and ``-blockdev`` to
1183describe the backend. The device defines what the guest sees and the
1184backend describes how QEMU handles the data. It is the only guaranteed
1185stable interface for describing block devices and as such is
1186recommended for management tools and scripting.
1187
1188The ``-drive`` option combines the device and backend into a single
1189command line option which is a more human friendly. There is however no
1190interface stability guarantee although some older board models still
1191need updating to work with the modern blockdev forms.
1192
1193Older options like ``-hda`` are essentially macros which expand into
1194``-drive`` options for various drive interfaces. The original forms
1195bake in a lot of assumptions from the days when QEMU was emulating a
1196legacy PC, they are not recommended for modern configurations.
1197
1198ERST
1199
1200DEF("fda", HAS_ARG, QEMU_OPTION_fda,
1201    "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
1202DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
1203SRST
1204``-fda file``
1205  \
1206``-fdb file``
1207    Use file as floppy disk 0/1 image (see the :ref:`disk images` chapter in
1208    the System Emulation Users Guide).
1209ERST
1210
1211DEF("hda", HAS_ARG, QEMU_OPTION_hda,
1212    "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
1213DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
1214DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
1215    "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
1216DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
1217SRST
1218``-hda file``
1219  \
1220``-hdb file``
1221  \
1222``-hdc file``
1223  \
1224``-hdd file``
1225    Use file as hard disk 0, 1, 2 or 3 image (see the :ref:`disk images`
1226    chapter in the System Emulation Users Guide).
1227ERST
1228
1229DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
1230    "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
1231    QEMU_ARCH_ALL)
1232SRST
1233``-cdrom file``
1234    Use file as CD-ROM image (you cannot use ``-hdc`` and ``-cdrom`` at
1235    the same time). You can use the host CD-ROM by using ``/dev/cdrom``
1236    as filename.
1237ERST
1238
1239DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
1240    "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
1241    "          [,cache.direct=on|off][,cache.no-flush=on|off]\n"
1242    "          [,read-only=on|off][,auto-read-only=on|off]\n"
1243    "          [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
1244    "          [,driver specific parameters...]\n"
1245    "                configure a block backend\n", QEMU_ARCH_ALL)
1246SRST
1247``-blockdev option[,option[,option[,...]]]``
1248    Define a new block driver node. Some of the options apply to all
1249    block drivers, other options are only accepted for a specific block
1250    driver. See below for a list of generic options and options for the
1251    most common block drivers.
1252
1253    Options that expect a reference to another node (e.g. ``file``) can
1254    be given in two ways. Either you specify the node name of an already
1255    existing node (file=node-name), or you define a new node inline,
1256    adding options for the referenced node after a dot
1257    (file.filename=path,file.aio=native).
1258
1259    A block driver node created with ``-blockdev`` can be used for a
1260    guest device by specifying its node name for the ``drive`` property
1261    in a ``-device`` argument that defines a block device.
1262
1263    ``Valid options for any block driver node:``
1264        ``driver``
1265            Specifies the block driver to use for the given node.
1266
1267        ``node-name``
1268            This defines the name of the block driver node by which it
1269            will be referenced later. The name must be unique, i.e. it
1270            must not match the name of a different block driver node, or
1271            (if you use ``-drive`` as well) the ID of a drive.
1272
1273            If no node name is specified, it is automatically generated.
1274            The generated node name is not intended to be predictable
1275            and changes between QEMU invocations. For the top level, an
1276            explicit node name must be specified.
1277
1278        ``read-only``
1279            Open the node read-only. Guest write attempts will fail.
1280
1281            Note that some block drivers support only read-only access,
1282            either generally or in certain configurations. In this case,
1283            the default value ``read-only=off`` does not work and the
1284            option must be specified explicitly.
1285
1286        ``auto-read-only``
1287            If ``auto-read-only=on`` is set, QEMU may fall back to
1288            read-only usage even when ``read-only=off`` is requested, or
1289            even switch between modes as needed, e.g. depending on
1290            whether the image file is writable or whether a writing user
1291            is attached to the node.
1292
1293        ``force-share``
1294            Override the image locking system of QEMU by forcing the
1295            node to utilize weaker shared access for permissions where
1296            it would normally request exclusive access. When there is
1297            the potential for multiple instances to have the same file
1298            open (whether this invocation of QEMU is the first or the
1299            second instance), both instances must permit shared access
1300            for the second instance to succeed at opening the file.
1301
1302            Enabling ``force-share=on`` requires ``read-only=on``.
1303
1304        ``cache.direct``
1305            The host page cache can be avoided with ``cache.direct=on``.
1306            This will attempt to do disk IO directly to the guest's
1307            memory. QEMU may still perform an internal copy of the data.
1308
1309        ``cache.no-flush``
1310            In case you don't care about data integrity over host
1311            failures, you can use ``cache.no-flush=on``. This option
1312            tells QEMU that it never needs to write any data to the disk
1313            but can instead keep things in cache. If anything goes
1314            wrong, like your host losing power, the disk storage getting
1315            disconnected accidentally, etc. your image will most
1316            probably be rendered unusable.
1317
1318        ``discard=discard``
1319            discard is one of "ignore" (or "off") or "unmap" (or "on")
1320            and controls whether ``discard`` (also known as ``trim`` or
1321            ``unmap``) requests are ignored or passed to the filesystem.
1322            Some machine types may not support discard requests.
1323
1324        ``detect-zeroes=detect-zeroes``
1325            detect-zeroes is "off", "on" or "unmap" and enables the
1326            automatic conversion of plain zero writes by the OS to
1327            driver specific optimized zero write commands. You may even
1328            choose "unmap" if discard is set to "unmap" to allow a zero
1329            write to be converted to an ``unmap`` operation.
1330
1331    ``Driver-specific options for file``
1332        This is the protocol-level block driver for accessing regular
1333        files.
1334
1335        ``filename``
1336            The path to the image file in the local filesystem
1337
1338        ``aio``
1339            Specifies the AIO backend (threads/native/io_uring,
1340            default: threads)
1341
1342        ``locking``
1343            Specifies whether the image file is protected with Linux OFD
1344            / POSIX locks. The default is to use the Linux Open File
1345            Descriptor API if available, otherwise no lock is applied.
1346            (auto/on/off, default: auto)
1347
1348        Example:
1349
1350        ::
1351
1352            -blockdev driver=file,node-name=disk,filename=disk.img
1353
1354    ``Driver-specific options for raw``
1355        This is the image format block driver for raw images. It is
1356        usually stacked on top of a protocol level block driver such as
1357        ``file``.
1358
1359        ``file``
1360            Reference to or definition of the data source block driver
1361            node (e.g. a ``file`` driver node)
1362
1363        Example 1:
1364
1365        ::
1366
1367            -blockdev driver=file,node-name=disk_file,filename=disk.img
1368            -blockdev driver=raw,node-name=disk,file=disk_file
1369
1370        Example 2:
1371
1372        ::
1373
1374            -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
1375
1376    ``Driver-specific options for qcow2``
1377        This is the image format block driver for qcow2 images. It is
1378        usually stacked on top of a protocol level block driver such as
1379        ``file``.
1380
1381        ``file``
1382            Reference to or definition of the data source block driver
1383            node (e.g. a ``file`` driver node)
1384
1385        ``backing``
1386            Reference to or definition of the backing file block device
1387            (default is taken from the image file). It is allowed to
1388            pass ``null`` here in order to disable the default backing
1389            file.
1390
1391        ``lazy-refcounts``
1392            Whether to enable the lazy refcounts feature (on/off;
1393            default is taken from the image file)
1394
1395        ``cache-size``
1396            The maximum total size of the L2 table and refcount block
1397            caches in bytes (default: the sum of l2-cache-size and
1398            refcount-cache-size)
1399
1400        ``l2-cache-size``
1401            The maximum size of the L2 table cache in bytes (default: if
1402            cache-size is not specified - 32M on Linux platforms, and 8M
1403            on non-Linux platforms; otherwise, as large as possible
1404            within the cache-size, while permitting the requested or the
1405            minimal refcount cache size)
1406
1407        ``refcount-cache-size``
1408            The maximum size of the refcount block cache in bytes
1409            (default: 4 times the cluster size; or if cache-size is
1410            specified, the part of it which is not used for the L2
1411            cache)
1412
1413        ``cache-clean-interval``
1414            Clean unused entries in the L2 and refcount caches. The
1415            interval is in seconds. The default value is 600 on
1416            supporting platforms, and 0 on other platforms. Setting it
1417            to 0 disables this feature.
1418
1419        ``pass-discard-request``
1420            Whether discard requests to the qcow2 device should be
1421            forwarded to the data source (on/off; default: on if
1422            discard=unmap is specified, off otherwise)
1423
1424        ``pass-discard-snapshot``
1425            Whether discard requests for the data source should be
1426            issued when a snapshot operation (e.g. deleting a snapshot)
1427            frees clusters in the qcow2 file (on/off; default: on)
1428
1429        ``pass-discard-other``
1430            Whether discard requests for the data source should be
1431            issued on other occasions where a cluster gets freed
1432            (on/off; default: off)
1433
1434        ``discard-no-unref``
1435            When enabled, discards from the guest will not cause cluster
1436            allocations to be relinquished. This prevents qcow2 fragmentation
1437            that would be caused by such discards. Besides potential
1438            performance degradation, such fragmentation can lead to increased
1439            allocation of clusters past the end of the image file,
1440            resulting in image files whose file length can grow much larger
1441            than their guest disk size would suggest.
1442            If image file length is of concern (e.g. when storing qcow2
1443            images directly on block devices), you should consider enabling
1444            this option.
1445
1446        ``overlap-check``
1447            Which overlap checks to perform for writes to the image
1448            (none/constant/cached/all; default: cached). For details or
1449            finer granularity control refer to the QAPI documentation of
1450            ``blockdev-add``.
1451
1452        Example 1:
1453
1454        ::
1455
1456            -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1457            -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1458
1459        Example 2:
1460
1461        ::
1462
1463            -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1464
1465    ``Driver-specific options for other drivers``
1466        Please refer to the QAPI documentation of the ``blockdev-add``
1467        QMP command.
1468ERST
1469
1470DEF("drive", HAS_ARG, QEMU_OPTION_drive,
1471    "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
1472    "       [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
1473    "       [,snapshot=on|off][,rerror=ignore|stop|report]\n"
1474    "       [,werror=ignore|stop|report|enospc][,id=name]\n"
1475    "       [,aio=threads|native|io_uring]\n"
1476    "       [,readonly=on|off][,copy-on-read=on|off]\n"
1477    "       [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
1478    "       [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
1479    "       [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
1480    "       [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
1481    "       [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
1482    "       [[,iops_size=is]]\n"
1483    "       [[,group=g]]\n"
1484    "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
1485SRST
1486``-drive option[,option[,option[,...]]]``
1487    Define a new drive. This includes creating a block driver node (the
1488    backend) as well as a guest device, and is mostly a shortcut for
1489    defining the corresponding ``-blockdev`` and ``-device`` options.
1490
1491    ``-drive`` accepts all options that are accepted by ``-blockdev``.
1492    In addition, it knows the following options:
1493
1494    ``file=file``
1495        This option defines which disk image (see the :ref:`disk images`
1496        chapter in the System Emulation Users Guide) to use with this drive.
1497        If the filename contains comma, you must double it (for instance,
1498        "file=my,,file" to use file "my,file").
1499
1500        Special files such as iSCSI devices can be specified using
1501        protocol specific URLs. See the section for "Device URL Syntax"
1502        for more information.
1503
1504    ``if=interface``
1505        This option defines on which type on interface the drive is
1506        connected. Available types are: ide, scsi, sd, mtd, floppy,
1507        pflash, virtio, none.
1508
1509    ``bus=bus,unit=unit``
1510        These options define where is connected the drive by defining
1511        the bus number and the unit id.
1512
1513    ``index=index``
1514        This option defines where the drive is connected by using an
1515        index in the list of available connectors of a given interface
1516        type.
1517
1518    ``media=media``
1519        This option defines the type of the media: disk or cdrom.
1520
1521    ``snapshot=snapshot``
1522        snapshot is "on" or "off" and controls snapshot mode for the
1523        given drive (see ``-snapshot``).
1524
1525    ``cache=cache``
1526        cache is "none", "writeback", "unsafe", "directsync" or
1527        "writethrough" and controls how the host cache is used to access
1528        block data. This is a shortcut that sets the ``cache.direct``
1529        and ``cache.no-flush`` options (as in ``-blockdev``), and
1530        additionally ``cache.writeback``, which provides a default for
1531        the ``write-cache`` option of block guest devices (as in
1532        ``-device``). The modes correspond to the following settings:
1533
1534        =============  ===============   ============   ==============
1535        \              cache.writeback   cache.direct   cache.no-flush
1536        =============  ===============   ============   ==============
1537        writeback      on                off            off
1538        none           on                on             off
1539        writethrough   off               off            off
1540        directsync     off               on             off
1541        unsafe         on                off            on
1542        =============  ===============   ============   ==============
1543
1544        The default mode is ``cache=writeback``.
1545
1546    ``aio=aio``
1547        aio is "threads", "native", or "io_uring" and selects between pthread
1548        based disk I/O, native Linux AIO, or Linux io_uring API.
1549
1550    ``format=format``
1551        Specify which disk format will be used rather than detecting the
1552        format. Can be used to specify format=raw to avoid interpreting
1553        an untrusted format header.
1554
1555    ``werror=action,rerror=action``
1556        Specify which action to take on write and read errors. Valid
1557        actions are: "ignore" (ignore the error and try to continue),
1558        "stop" (pause QEMU), "report" (report the error to the guest),
1559        "enospc" (pause QEMU only if the host disk is full; report the
1560        error to the guest otherwise). The default setting is
1561        ``werror=enospc`` and ``rerror=report``.
1562
1563    ``copy-on-read=copy-on-read``
1564        copy-on-read is "on" or "off" and enables whether to copy read
1565        backing file sectors into the image file.
1566
1567    ``bps=b,bps_rd=r,bps_wr=w``
1568        Specify bandwidth throttling limits in bytes per second, either
1569        for all request types or for reads or writes only. Small values
1570        can lead to timeouts or hangs inside the guest. A safe minimum
1571        for disks is 2 MB/s.
1572
1573    ``bps_max=bm,bps_rd_max=rm,bps_wr_max=wm``
1574        Specify bursts in bytes per second, either for all request types
1575        or for reads or writes only. Bursts allow the guest I/O to spike
1576        above the limit temporarily.
1577
1578    ``iops=i,iops_rd=r,iops_wr=w``
1579        Specify request rate limits in requests per second, either for
1580        all request types or for reads or writes only.
1581
1582    ``iops_max=bm,iops_rd_max=rm,iops_wr_max=wm``
1583        Specify bursts in requests per second, either for all request
1584        types or for reads or writes only. Bursts allow the guest I/O to
1585        spike above the limit temporarily.
1586
1587    ``iops_size=is``
1588        Let every is bytes of a request count as a new request for iops
1589        throttling purposes. Use this option to prevent guests from
1590        circumventing iops limits by sending fewer but larger requests.
1591
1592    ``group=g``
1593        Join a throttling quota group with given name g. All drives that
1594        are members of the same group are accounted for together. Use
1595        this option to prevent guests from circumventing throttling
1596        limits by using many small disks instead of a single larger
1597        disk.
1598
1599    By default, the ``cache.writeback=on`` mode is used. It will report
1600    data writes as completed as soon as the data is present in the host
1601    page cache. This is safe as long as your guest OS makes sure to
1602    correctly flush disk caches where needed. If your guest OS does not
1603    handle volatile disk write caches correctly and your host crashes or
1604    loses power, then the guest may experience data corruption.
1605
1606    For such guests, you should consider using ``cache.writeback=off``.
1607    This means that the host page cache will be used to read and write
1608    data, but write notification will be sent to the guest only after
1609    QEMU has made sure to flush each write to the disk. Be aware that
1610    this has a major impact on performance.
1611
1612    When using the ``-snapshot`` option, unsafe caching is always used.
1613
1614    Copy-on-read avoids accessing the same backing file sectors
1615    repeatedly and is useful when the backing file is over a slow
1616    network. By default copy-on-read is off.
1617
1618    Instead of ``-cdrom`` you can use:
1619
1620    .. parsed-literal::
1621
1622        |qemu_system| -drive file=file,index=2,media=cdrom
1623
1624    Instead of ``-hda``, ``-hdb``, ``-hdc``, ``-hdd``, you can use:
1625
1626    .. parsed-literal::
1627
1628        |qemu_system| -drive file=file,index=0,media=disk
1629        |qemu_system| -drive file=file,index=1,media=disk
1630        |qemu_system| -drive file=file,index=2,media=disk
1631        |qemu_system| -drive file=file,index=3,media=disk
1632
1633    You can open an image using pre-opened file descriptors from an fd
1634    set:
1635
1636    .. parsed-literal::
1637
1638        |qemu_system| \\
1639         -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \\
1640         -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \\
1641         -drive file=/dev/fdset/2,index=0,media=disk
1642
1643    You can connect a CDROM to the slave of ide0:
1644
1645    .. parsed-literal::
1646
1647        |qemu_system_x86| -drive file=file,if=ide,index=1,media=cdrom
1648
1649    If you don't specify the "file=" argument, you define an empty
1650    drive:
1651
1652    .. parsed-literal::
1653
1654        |qemu_system_x86| -drive if=ide,index=1,media=cdrom
1655
1656    Instead of ``-fda``, ``-fdb``, you can use:
1657
1658    .. parsed-literal::
1659
1660        |qemu_system_x86| -drive file=file,index=0,if=floppy
1661        |qemu_system_x86| -drive file=file,index=1,if=floppy
1662
1663    By default, interface is "ide" and index is automatically
1664    incremented:
1665
1666    .. parsed-literal::
1667
1668        |qemu_system_x86| -drive file=a -drive file=b
1669
1670    is interpreted like:
1671
1672    .. parsed-literal::
1673
1674        |qemu_system_x86| -hda a -hdb b
1675ERST
1676
1677DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
1678    "-mtdblock file  use 'file' as on-board Flash memory image\n",
1679    QEMU_ARCH_ALL)
1680SRST
1681``-mtdblock file``
1682    Use file as on-board Flash memory image.
1683ERST
1684
1685DEF("sd", HAS_ARG, QEMU_OPTION_sd,
1686    "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
1687SRST
1688``-sd file``
1689    Use file as SecureDigital card image.
1690ERST
1691
1692DEF("snapshot", 0, QEMU_OPTION_snapshot,
1693    "-snapshot       write to temporary files instead of disk image files\n",
1694    QEMU_ARCH_ALL)
1695SRST
1696``-snapshot``
1697    Write to temporary files instead of disk image files. In this case,
1698    the raw disk image you use is not written back. You can however
1699    force the write back by pressing C-a s (see the :ref:`disk images`
1700    chapter in the System Emulation Users Guide).
1701
1702    .. warning::
1703       snapshot is incompatible with ``-blockdev`` (instead use qemu-img
1704       to manually create snapshot images to attach to your blockdev).
1705       If you have mixed ``-blockdev`` and ``-drive`` declarations you
1706       can use the 'snapshot' property on your drive declarations
1707       instead of this global option.
1708
1709ERST
1710
1711DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
1712    "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1713    " [,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]\n"
1714    " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1715    " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1716    " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1717    " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1718    " [[,throttling.iops-size=is]]\n"
1719    "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]\n"
1720    "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]\n"
1721    "-fsdev synth,id=id\n",
1722    QEMU_ARCH_ALL)
1723
1724SRST
1725``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly=on][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
1726  \
1727``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly=on]``
1728  \
1729``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly=on]``
1730  \
1731``-fsdev synth,id=id[,readonly=on]``
1732    Define a new file system device. Valid options are:
1733
1734    ``local``
1735        Accesses to the filesystem are done by QEMU.
1736
1737    ``proxy``
1738        Accesses to the filesystem are done by virtfs-proxy-helper(1). This
1739        option is deprecated (since QEMU 8.1) and will be removed in a future
1740        version of QEMU. Use ``local`` instead.
1741
1742    ``synth``
1743        Synthetic filesystem, only used by QTests.
1744
1745    ``id=id``
1746        Specifies identifier for this device.
1747
1748    ``path=path``
1749        Specifies the export path for the file system device. Files
1750        under this path will be available to the 9p client on the guest.
1751
1752    ``security_model=security_model``
1753        Specifies the security model to be used for this export path.
1754        Supported security models are "passthrough", "mapped-xattr",
1755        "mapped-file" and "none". In "passthrough" security model, files
1756        are stored using the same credentials as they are created on the
1757        guest. This requires QEMU to run as root. In "mapped-xattr"
1758        security model, some of the file attributes like uid, gid, mode
1759        bits and link target are stored as file attributes. For
1760        "mapped-file" these attributes are stored in the hidden
1761        .virtfs\_metadata directory. Directories exported by this
1762        security model cannot interact with other unix tools. "none"
1763        security model is same as passthrough except the sever won't
1764        report failures if it fails to set file attributes like
1765        ownership. Security model is mandatory only for local fsdriver.
1766        Other fsdrivers (like proxy) don't take security model as a
1767        parameter.
1768
1769    ``writeout=writeout``
1770        This is an optional argument. The only supported value is
1771        "immediate". This means that host page cache will be used to
1772        read and write data but write notification will be sent to the
1773        guest only when the data has been reported as written by the
1774        storage subsystem.
1775
1776    ``readonly=on``
1777        Enables exporting 9p share as a readonly mount for guests. By
1778        default read-write access is given.
1779
1780    ``socket=socket``
1781        Enables proxy filesystem driver to use passed socket file for
1782        communicating with virtfs-proxy-helper(1).
1783
1784    ``sock_fd=sock_fd``
1785        Enables proxy filesystem driver to use passed socket descriptor
1786        for communicating with virtfs-proxy-helper(1). Usually a helper
1787        like libvirt will create socketpair and pass one of the fds as
1788        sock\_fd.
1789
1790    ``fmode=fmode``
1791        Specifies the default mode for newly created files on the host.
1792        Works only with security models "mapped-xattr" and
1793        "mapped-file".
1794
1795    ``dmode=dmode``
1796        Specifies the default mode for newly created directories on the
1797        host. Works only with security models "mapped-xattr" and
1798        "mapped-file".
1799
1800    ``throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w``
1801        Specify bandwidth throttling limits in bytes per second, either
1802        for all request types or for reads or writes only.
1803
1804    ``throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm``
1805        Specify bursts in bytes per second, either for all request types
1806        or for reads or writes only. Bursts allow the guest I/O to spike
1807        above the limit temporarily.
1808
1809    ``throttling.iops-total=i,throttling.iops-read=r, throttling.iops-write=w``
1810        Specify request rate limits in requests per second, either for
1811        all request types or for reads or writes only.
1812
1813    ``throttling.iops-total-max=im,throttling.iops-read-max=irm, throttling.iops-write-max=iwm``
1814        Specify bursts in requests per second, either for all request
1815        types or for reads or writes only. Bursts allow the guest I/O to
1816        spike above the limit temporarily.
1817
1818    ``throttling.iops-size=is``
1819        Let every is bytes of a request count as a new request for iops
1820        throttling purposes.
1821
1822    -fsdev option is used along with -device driver "virtio-9p-...".
1823
1824``-device virtio-9p-type,fsdev=id,mount_tag=mount_tag``
1825    Options for virtio-9p-... driver are:
1826
1827    ``type``
1828        Specifies the variant to be used. Supported values are "pci",
1829        "ccw" or "device", depending on the machine type.
1830
1831    ``fsdev=id``
1832        Specifies the id value specified along with -fsdev option.
1833
1834    ``mount_tag=mount_tag``
1835        Specifies the tag name to be used by the guest to mount this
1836        export point.
1837ERST
1838
1839DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
1840    "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1841    "        [,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
1842    "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]\n"
1843    "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]\n"
1844    "-virtfs synth,mount_tag=tag[,id=id][,readonly=on]\n",
1845    QEMU_ARCH_ALL)
1846
1847SRST
1848``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly=on] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
1849  \
1850``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
1851  \
1852``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
1853  \
1854``-virtfs synth,mount_tag=mount_tag``
1855    Define a new virtual filesystem device and expose it to the guest using
1856    a virtio-9p-device (a.k.a. 9pfs), which essentially means that a certain
1857    directory on host is made directly accessible by guest as a pass-through
1858    file system by using the 9P network protocol for communication between
1859    host and guests, if desired even accessible, shared by several guests
1860    simultaneously.
1861
1862    Note that ``-virtfs`` is actually just a convenience shortcut for its
1863    generalized form ``-fsdev -device virtio-9p-pci``.
1864
1865    The general form of pass-through file system options are:
1866
1867    ``local``
1868        Accesses to the filesystem are done by QEMU.
1869
1870    ``proxy``
1871        Accesses to the filesystem are done by virtfs-proxy-helper(1).
1872        This option is deprecated (since QEMU 8.1) and will be removed in a
1873        future version of QEMU. Use ``local`` instead.
1874
1875    ``synth``
1876        Synthetic filesystem, only used by QTests.
1877
1878    ``id=id``
1879        Specifies identifier for the filesystem device
1880
1881    ``path=path``
1882        Specifies the export path for the file system device. Files
1883        under this path will be available to the 9p client on the guest.
1884
1885    ``security_model=security_model``
1886        Specifies the security model to be used for this export path.
1887        Supported security models are "passthrough", "mapped-xattr",
1888        "mapped-file" and "none". In "passthrough" security model, files
1889        are stored using the same credentials as they are created on the
1890        guest. This requires QEMU to run as root. In "mapped-xattr"
1891        security model, some of the file attributes like uid, gid, mode
1892        bits and link target are stored as file attributes. For
1893        "mapped-file" these attributes are stored in the hidden
1894        .virtfs\_metadata directory. Directories exported by this
1895        security model cannot interact with other unix tools. "none"
1896        security model is same as passthrough except the sever won't
1897        report failures if it fails to set file attributes like
1898        ownership. Security model is mandatory only for local fsdriver.
1899        Other fsdrivers (like proxy) don't take security model as a
1900        parameter.
1901
1902    ``writeout=writeout``
1903        This is an optional argument. The only supported value is
1904        "immediate". This means that host page cache will be used to
1905        read and write data but write notification will be sent to the
1906        guest only when the data has been reported as written by the
1907        storage subsystem.
1908
1909    ``readonly=on``
1910        Enables exporting 9p share as a readonly mount for guests. By
1911        default read-write access is given.
1912
1913    ``socket=socket``
1914        Enables proxy filesystem driver to use passed socket file for
1915        communicating with virtfs-proxy-helper(1). Usually a helper like
1916        libvirt will create socketpair and pass one of the fds as
1917        sock\_fd.
1918
1919    ``sock_fd``
1920        Enables proxy filesystem driver to use passed 'sock\_fd' as the
1921        socket descriptor for interfacing with virtfs-proxy-helper(1).
1922
1923    ``fmode=fmode``
1924        Specifies the default mode for newly created files on the host.
1925        Works only with security models "mapped-xattr" and
1926        "mapped-file".
1927
1928    ``dmode=dmode``
1929        Specifies the default mode for newly created directories on the
1930        host. Works only with security models "mapped-xattr" and
1931        "mapped-file".
1932
1933    ``mount_tag=mount_tag``
1934        Specifies the tag name to be used by the guest to mount this
1935        export point.
1936
1937    ``multidevs=multidevs``
1938        Specifies how to deal with multiple devices being shared with a
1939        9p export. Supported behaviours are either "remap", "forbid" or
1940        "warn". The latter is the default behaviour on which virtfs 9p
1941        expects only one device to be shared with the same export, and
1942        if more than one device is shared and accessed via the same 9p
1943        export then only a warning message is logged (once) by qemu on
1944        host side. In order to avoid file ID collisions on guest you
1945        should either create a separate virtfs export for each device to
1946        be shared with guests (recommended way) or you might use "remap"
1947        instead which allows you to share multiple devices with only one
1948        export instead, which is achieved by remapping the original
1949        inode numbers from host to guest in a way that would prevent
1950        such collisions. Remapping inodes in such use cases is required
1951        because the original device IDs from host are never passed and
1952        exposed on guest. Instead all files of an export shared with
1953        virtfs always share the same device id on guest. So two files
1954        with identical inode numbers but from actually different devices
1955        on host would otherwise cause a file ID collision and hence
1956        potential misbehaviours on guest. "forbid" on the other hand
1957        assumes like "warn" that only one device is shared by the same
1958        export, however it will not only log a warning message but also
1959        deny access to additional devices on guest. Note though that
1960        "forbid" does currently not block all possible file access
1961        operations (e.g. readdir() would still return entries from other
1962        devices).
1963ERST
1964
1965DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1966    "-iscsi [user=user][,password=password][,password-secret=secret-id]\n"
1967    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE]\n"
1968    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1969    "       [,timeout=timeout]\n"
1970    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
1971
1972SRST
1973``-iscsi``
1974    Configure iSCSI session parameters.
1975ERST
1976
1977DEFHEADING()
1978
1979DEFHEADING(USB convenience options:)
1980
1981DEF("usb", 0, QEMU_OPTION_usb,
1982    "-usb            enable on-board USB host controller (if not enabled by default)\n",
1983    QEMU_ARCH_ALL)
1984SRST
1985``-usb``
1986    Enable USB emulation on machine types with an on-board USB host
1987    controller (if not enabled by default). Note that on-board USB host
1988    controllers may not support USB 3.0. In this case
1989    ``-device qemu-xhci`` can be used instead on machines with PCI.
1990ERST
1991
1992DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1993    "-usbdevice name add the host or guest USB device 'name'\n",
1994    QEMU_ARCH_ALL)
1995SRST
1996``-usbdevice devname``
1997    Add the USB device devname, and enable an on-board USB controller
1998    if possible and necessary (just like it can be done via
1999    ``-machine usb=on``). Note that this option is mainly intended for
2000    the user's convenience only. More fine-grained control can be
2001    achieved by selecting a USB host controller (if necessary) and the
2002    desired USB device via the ``-device`` option instead. For example,
2003    instead of using ``-usbdevice mouse`` it is possible to use
2004    ``-device qemu-xhci -device usb-mouse`` to connect the USB mouse
2005    to a USB 3.0 controller instead (at least on machines that support
2006    PCI and do not have an USB controller enabled by default yet).
2007    For more details, see the chapter about
2008    :ref:`Connecting USB devices` in the System Emulation Users Guide.
2009    Possible devices for devname are:
2010
2011    ``braille``
2012        Braille device. This will use BrlAPI to display the braille
2013        output on a real or fake device (i.e. it also creates a
2014        corresponding ``braille`` chardev automatically beside the
2015        ``usb-braille`` USB device).
2016
2017    ``keyboard``
2018        Standard USB keyboard. Will override the PS/2 keyboard (if present).
2019
2020    ``mouse``
2021        Virtual Mouse. This will override the PS/2 mouse emulation when
2022        activated.
2023
2024    ``tablet``
2025        Pointer device that uses absolute coordinates (like a
2026        touchscreen). This means QEMU is able to report the mouse
2027        position without having to grab the mouse. Also overrides the
2028        PS/2 mouse emulation when activated.
2029
2030    ``wacom-tablet``
2031        Wacom PenPartner USB tablet.
2032
2033
2034ERST
2035
2036DEFHEADING()
2037
2038DEFHEADING(Display options:)
2039
2040DEF("display", HAS_ARG, QEMU_OPTION_display,
2041#if defined(CONFIG_SPICE)
2042    "-display spice-app[,gl=on|off]\n"
2043#endif
2044#if defined(CONFIG_SDL)
2045    "-display sdl[,gl=on|core|es|off][,grab-mod=<mod>][,show-cursor=on|off]\n"
2046    "            [,window-close=on|off]\n"
2047#endif
2048#if defined(CONFIG_GTK)
2049    "-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]\n"
2050    "            [,show-tabs=on|off][,show-cursor=on|off][,window-close=on|off]\n"
2051    "            [,show-menubar=on|off]\n"
2052#endif
2053#if defined(CONFIG_VNC)
2054    "-display vnc=<display>[,<optargs>]\n"
2055#endif
2056#if defined(CONFIG_CURSES)
2057    "-display curses[,charset=<encoding>]\n"
2058#endif
2059#if defined(CONFIG_COCOA)
2060    "-display cocoa[,full-grab=on|off][,swap-opt-cmd=on|off]\n"
2061#endif
2062#if defined(CONFIG_OPENGL)
2063    "-display egl-headless[,rendernode=<file>]\n"
2064#endif
2065#if defined(CONFIG_DBUS_DISPLAY)
2066    "-display dbus[,addr=<dbusaddr>]\n"
2067    "             [,gl=on|core|es|off][,rendernode=<file>]\n"
2068#endif
2069#if defined(CONFIG_COCOA)
2070    "-display cocoa[,show-cursor=on|off][,left-command-key=on|off]\n"
2071#endif
2072    "-display none\n"
2073    "                select display backend type\n"
2074    "                The default display is equivalent to\n                "
2075#if defined(CONFIG_GTK)
2076            "\"-display gtk\"\n"
2077#elif defined(CONFIG_SDL)
2078            "\"-display sdl\"\n"
2079#elif defined(CONFIG_COCOA)
2080            "\"-display cocoa\"\n"
2081#elif defined(CONFIG_VNC)
2082            "\"-vnc localhost:0,to=99,id=default\"\n"
2083#else
2084            "\"-display none\"\n"
2085#endif
2086    , QEMU_ARCH_ALL)
2087SRST
2088``-display type``
2089    Select type of display to use. Use ``-display help`` to list the available
2090    display types. Valid values for type are
2091
2092    ``spice-app[,gl=on|off]``
2093        Start QEMU as a Spice server and launch the default Spice client
2094        application. The Spice server will redirect the serial consoles
2095        and QEMU monitors. (Since 4.0)
2096
2097    ``dbus``
2098        Export the display over D-Bus interfaces. (Since 7.0)
2099
2100        The connection is registered with the "org.qemu" name (and queued when
2101        already owned).
2102
2103        ``addr=<dbusaddr>`` : D-Bus bus address to connect to.
2104
2105        ``p2p=yes|no`` : Use peer-to-peer connection, accepted via QMP ``add_client``.
2106
2107        ``gl=on|off|core|es`` : Use OpenGL for rendering (the D-Bus interface
2108        will share framebuffers with DMABUF file descriptors).
2109
2110    ``sdl``
2111        Display video output via SDL (usually in a separate graphics
2112        window; see the SDL documentation for other possibilities).
2113        Valid parameters are:
2114
2115        ``grab-mod=<mods>`` : Used to select the modifier keys for toggling
2116        the mouse grabbing in conjunction with the "g" key. ``<mods>`` can be
2117        either ``lshift-lctrl-lalt`` or ``rctrl``.
2118
2119        ``gl=on|off|core|es`` : Use OpenGL for displaying
2120
2121        ``show-cursor=on|off`` :  Force showing the mouse cursor
2122
2123        ``window-close=on|off`` : Allow to quit qemu with window close button
2124
2125    ``gtk``
2126        Display video output in a GTK window. This interface provides
2127        drop-down menus and other UI elements to configure and control
2128        the VM during runtime. Valid parameters are:
2129
2130        ``full-screen=on|off`` : Start in fullscreen mode
2131
2132        ``gl=on|off`` : Use OpenGL for displaying
2133
2134        ``grab-on-hover=on|off`` : Grab keyboard input on mouse hover
2135
2136        ``show-tabs=on|off`` : Display the tab bar for switching between the
2137                               various graphical interfaces (e.g. VGA and
2138                               virtual console character devices) by default.
2139
2140        ``show-cursor=on|off`` :  Force showing the mouse cursor
2141
2142        ``window-close=on|off`` : Allow to quit qemu with window close button
2143
2144        ``show-menubar=on|off`` : Display the main window menubar, defaults to "on"
2145
2146        ``zoom-to-fit=on|off`` : Expand video output to the window size,
2147                                 defaults to "off"
2148
2149    ``curses[,charset=<encoding>]``
2150        Display video output via curses. For graphics device models
2151        which support a text mode, QEMU can display this output using a
2152        curses/ncurses interface. Nothing is displayed when the graphics
2153        device is in graphical mode or if the graphics device does not
2154        support a text mode. Generally only the VGA device models
2155        support text mode. The font charset used by the guest can be
2156        specified with the ``charset`` option, for example
2157        ``charset=CP850`` for IBM CP850 encoding. The default is
2158        ``CP437``.
2159
2160    ``cocoa``
2161        Display video output in a Cocoa window. Mac only. This interface
2162        provides drop-down menus and other UI elements to configure and
2163        control the VM during runtime. Valid parameters are:
2164
2165        ``show-cursor=on|off`` :  Force showing the mouse cursor
2166
2167        ``left-command-key=on|off`` : Disable forwarding left command key to host
2168
2169    ``egl-headless[,rendernode=<file>]``
2170        Offload all OpenGL operations to a local DRI device. For any
2171        graphical display, this display needs to be paired with either
2172        VNC or SPICE displays.
2173
2174    ``vnc=<display>``
2175        Start a VNC server on display <display>
2176
2177    ``none``
2178        Do not display video output. The guest will still see an
2179        emulated graphics card, but its output will not be displayed to
2180        the QEMU user. This option differs from the -nographic option in
2181        that it only affects what is done with video output; -nographic
2182        also changes the destination of the serial and parallel port
2183        data.
2184ERST
2185
2186DEF("nographic", 0, QEMU_OPTION_nographic,
2187    "-nographic      disable graphical output and redirect serial I/Os to console\n",
2188    QEMU_ARCH_ALL)
2189SRST
2190``-nographic``
2191    Normally, if QEMU is compiled with graphical window support, it
2192    displays output such as guest graphics, guest console, and the QEMU
2193    monitor in a window. With this option, you can totally disable
2194    graphical output so that QEMU is a simple command line application.
2195    The emulated serial port is redirected on the console and muxed with
2196    the monitor (unless redirected elsewhere explicitly). Therefore, you
2197    can still use QEMU to debug a Linux kernel with a serial console.
2198    Use C-a h for help on switching between the console and monitor.
2199ERST
2200
2201#ifdef CONFIG_SPICE
2202DEF("spice", HAS_ARG, QEMU_OPTION_spice,
2203    "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
2204    "       [,x509-key-file=<file>][,x509-key-password=<file>]\n"
2205    "       [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
2206    "       [,x509-dh-key-file=<file>][,addr=addr]\n"
2207    "       [,ipv4=on|off][,ipv6=on|off][,unix=on|off]\n"
2208    "       [,tls-ciphers=<list>]\n"
2209    "       [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
2210    "       [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
2211    "       [,sasl=on|off][,disable-ticketing=on|off]\n"
2212    "       [,password-secret=<secret-id>]\n"
2213    "       [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
2214    "       [,jpeg-wan-compression=[auto|never|always]]\n"
2215    "       [,zlib-glz-wan-compression=[auto|never|always]]\n"
2216    "       [,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]\n"
2217    "       [,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]\n"
2218    "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
2219    "       [,gl=[on|off]][,rendernode=<file>]\n"
2220    "                enable spice\n"
2221    "                at least one of {port, tls-port} is mandatory\n",
2222    QEMU_ARCH_ALL)
2223#endif
2224SRST
2225``-spice option[,option[,...]]``
2226    Enable the spice remote desktop protocol. Valid options are
2227
2228    ``port=<nr>``
2229        Set the TCP port spice is listening on for plaintext channels.
2230
2231    ``addr=<addr>``
2232        Set the IP address spice is listening on. Default is any
2233        address.
2234
2235    ``ipv4=on|off``; \ ``ipv6=on|off``; \ ``unix=on|off``
2236        Force using the specified IP version.
2237
2238    ``password-secret=<secret-id>``
2239        Set the ID of the ``secret`` object containing the password
2240        you need to authenticate.
2241
2242    ``sasl=on|off``
2243        Require that the client use SASL to authenticate with the spice.
2244        The exact choice of authentication method used is controlled
2245        from the system / user's SASL configuration file for the 'qemu'
2246        service. This is typically found in /etc/sasl2/qemu.conf. If
2247        running QEMU as an unprivileged user, an environment variable
2248        SASL\_CONF\_PATH can be used to make it search alternate
2249        locations for the service config. While some SASL auth methods
2250        can also provide data encryption (eg GSSAPI), it is recommended
2251        that SASL always be combined with the 'tls' and 'x509' settings
2252        to enable use of SSL and server certificates. This ensures a
2253        data encryption preventing compromise of authentication
2254        credentials.
2255
2256    ``disable-ticketing=on|off``
2257        Allow client connects without authentication.
2258
2259    ``disable-copy-paste=on|off``
2260        Disable copy paste between the client and the guest.
2261
2262    ``disable-agent-file-xfer=on|off``
2263        Disable spice-vdagent based file-xfer between the client and the
2264        guest.
2265
2266    ``tls-port=<nr>``
2267        Set the TCP port spice is listening on for encrypted channels.
2268
2269    ``x509-dir=<dir>``
2270        Set the x509 file directory. Expects same filenames as -vnc
2271        $display,x509=$dir
2272
2273    ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>``
2274        The x509 file names can also be configured individually.
2275
2276    ``tls-ciphers=<list>``
2277        Specify which ciphers to use.
2278
2279    ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]``
2280        Force specific channel to be used with or without TLS
2281        encryption. The options can be specified multiple times to
2282        configure multiple channels. The special name "default" can be
2283        used to set the default mode. For channels which are not
2284        explicitly forced into one mode the spice client is allowed to
2285        pick tls/plaintext as he pleases.
2286
2287    ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]``
2288        Configure image compression (lossless). Default is auto\_glz.
2289
2290    ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]``
2291        Configure wan image compression (lossy for slow links). Default
2292        is auto.
2293
2294    ``streaming-video=[off|all|filter]``
2295        Configure video stream detection. Default is off.
2296
2297    ``agent-mouse=[on|off]``
2298        Enable/disable passing mouse events via vdagent. Default is on.
2299
2300    ``playback-compression=[on|off]``
2301        Enable/disable audio stream compression (using celt 0.5.1).
2302        Default is on.
2303
2304    ``seamless-migration=[on|off]``
2305        Enable/disable spice seamless migration. Default is off.
2306
2307    ``gl=[on|off]``
2308        Enable/disable OpenGL context. Default is off.
2309
2310    ``rendernode=<file>``
2311        DRM render node for OpenGL rendering. If not specified, it will
2312        pick the first available. (Since 2.9)
2313ERST
2314
2315DEF("portrait", 0, QEMU_OPTION_portrait,
2316    "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
2317    QEMU_ARCH_ALL)
2318SRST
2319``-portrait``
2320    Rotate graphical output 90 deg left (only PXA LCD).
2321ERST
2322
2323DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
2324    "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
2325    QEMU_ARCH_ALL)
2326SRST
2327``-rotate deg``
2328    Rotate graphical output some deg left (only PXA LCD).
2329ERST
2330
2331DEF("vga", HAS_ARG, QEMU_OPTION_vga,
2332    "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
2333    "                select video card type\n", QEMU_ARCH_ALL)
2334SRST
2335``-vga type``
2336    Select type of VGA card to emulate. Valid values for type are
2337
2338    ``cirrus``
2339        Cirrus Logic GD5446 Video card. All Windows versions starting
2340        from Windows 95 should recognize and use this graphic card. For
2341        optimal performances, use 16 bit color depth in the guest and
2342        the host OS. (This card was the default before QEMU 2.2)
2343
2344    ``std``
2345        Standard VGA card with Bochs VBE extensions. If your guest OS
2346        supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
2347        you want to use high resolution modes (>= 1280x1024x16) then you
2348        should use this option. (This card is the default since QEMU
2349        2.2)
2350
2351    ``vmware``
2352        VMWare SVGA-II compatible adapter. Use it if you have
2353        sufficiently recent XFree86/XOrg server or Windows guest with a
2354        driver for this card.
2355
2356    ``qxl``
2357        QXL paravirtual graphic card. It is VGA compatible (including
2358        VESA 2.0 VBE support). Works best with qxl guest drivers
2359        installed though. Recommended choice when using the spice
2360        protocol.
2361
2362    ``tcx``
2363        (sun4m only) Sun TCX framebuffer. This is the default
2364        framebuffer for sun4m machines and offers both 8-bit and 24-bit
2365        colour depths at a fixed resolution of 1024x768.
2366
2367    ``cg3``
2368        (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
2369        framebuffer for sun4m machines available in both 1024x768
2370        (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
2371        wishing to run older Solaris versions.
2372
2373    ``virtio``
2374        Virtio VGA card.
2375
2376    ``none``
2377        Disable VGA card.
2378ERST
2379
2380DEF("full-screen", 0, QEMU_OPTION_full_screen,
2381    "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
2382SRST
2383``-full-screen``
2384    Start in full screen.
2385ERST
2386
2387DEF("g", HAS_ARG, QEMU_OPTION_g ,
2388    "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
2389    QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
2390SRST
2391``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]``
2392    Set the initial graphical resolution and depth (PPC, SPARC only).
2393
2394    For PPC the default is 800x600x32.
2395
2396    For SPARC with the TCX graphics device, the default is 1024x768x8
2397    with the option of 1024x768x24. For cgthree, the default is
2398    1024x768x8 with the option of 1152x900x8 for people who wish to use
2399    OBP.
2400ERST
2401
2402DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
2403    "-vnc <display>  shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
2404SRST
2405``-vnc display[,option[,option[,...]]]``
2406    Normally, if QEMU is compiled with graphical window support, it
2407    displays output such as guest graphics, guest console, and the QEMU
2408    monitor in a window. With this option, you can have QEMU listen on
2409    VNC display display and redirect the VGA display over the VNC
2410    session. It is very useful to enable the usb tablet device when
2411    using this option (option ``-device usb-tablet``). When using the
2412    VNC display, you must use the ``-k`` parameter to set the keyboard
2413    layout if you are not using en-us. Valid syntax for the display is
2414
2415    ``to=L``
2416        With this option, QEMU will try next available VNC displays,
2417        until the number L, if the origianlly defined "-vnc display" is
2418        not available, e.g. port 5900+display is already used by another
2419        application. By default, to=0.
2420
2421    ``host:d``
2422        TCP connections will only be allowed from host on display d. By
2423        convention the TCP port is 5900+d. Optionally, host can be
2424        omitted in which case the server will accept connections from
2425        any host.
2426
2427    ``unix:path``
2428        Connections will be allowed over UNIX domain sockets where path
2429        is the location of a unix socket to listen for connections on.
2430
2431    ``none``
2432        VNC is initialized but not started. The monitor ``change``
2433        command can be used to later start the VNC server.
2434
2435    Following the display value there may be one or more option flags
2436    separated by commas. Valid options are
2437
2438    ``reverse=on|off``
2439        Connect to a listening VNC client via a "reverse" connection.
2440        The client is specified by the display. For reverse network
2441        connections (host:d,``reverse``), the d argument is a TCP port
2442        number, not a display number.
2443
2444    ``websocket=on|off``
2445        Opens an additional TCP listening port dedicated to VNC
2446        Websocket connections. If a bare websocket option is given, the
2447        Websocket port is 5700+display. An alternative port can be
2448        specified with the syntax ``websocket``\ =port.
2449
2450        If host is specified connections will only be allowed from this
2451        host. It is possible to control the websocket listen address
2452        independently, using the syntax ``websocket``\ =host:port.
2453
2454        If no TLS credentials are provided, the websocket connection
2455        runs in unencrypted mode. If TLS credentials are provided, the
2456        websocket connection requires encrypted client connections.
2457
2458    ``password=on|off``
2459        Require that password based authentication is used for client
2460        connections.
2461
2462        The password must be set separately using the ``set_password``
2463        command in the :ref:`QEMU monitor`. The
2464        syntax to change your password is:
2465        ``set_password <protocol> <password>`` where <protocol> could be
2466        either "vnc" or "spice".
2467
2468        If you would like to change <protocol> password expiration, you
2469        should use ``expire_password <protocol> <expiration-time>``
2470        where expiration time could be one of the following options:
2471        now, never, +seconds or UNIX time of expiration, e.g. +60 to
2472        make password expire in 60 seconds, or 1335196800 to make
2473        password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for
2474        this date and time).
2475
2476        You can also use keywords "now" or "never" for the expiration
2477        time to allow <protocol> password to expire immediately or never
2478        expire.
2479
2480    ``password-secret=<secret-id>``
2481        Require that password based authentication is used for client
2482        connections, using the password provided by the ``secret``
2483        object identified by ``secret-id``.
2484
2485    ``tls-creds=ID``
2486        Provides the ID of a set of TLS credentials to use to secure the
2487        VNC server. They will apply to both the normal VNC server socket
2488        and the websocket socket (if enabled). Setting TLS credentials
2489        will cause the VNC server socket to enable the VeNCrypt auth
2490        mechanism. The credentials should have been previously created
2491        using the ``-object tls-creds`` argument.
2492
2493    ``tls-authz=ID``
2494        Provides the ID of the QAuthZ authorization object against which
2495        the client's x509 distinguished name will validated. This object
2496        is only resolved at time of use, so can be deleted and recreated
2497        on the fly while the VNC server is active. If missing, it will
2498        default to denying access.
2499
2500    ``sasl=on|off``
2501        Require that the client use SASL to authenticate with the VNC
2502        server. The exact choice of authentication method used is
2503        controlled from the system / user's SASL configuration file for
2504        the 'qemu' service. This is typically found in
2505        /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
2506        an environment variable SASL\_CONF\_PATH can be used to make it
2507        search alternate locations for the service config. While some
2508        SASL auth methods can also provide data encryption (eg GSSAPI),
2509        it is recommended that SASL always be combined with the 'tls'
2510        and 'x509' settings to enable use of SSL and server
2511        certificates. This ensures a data encryption preventing
2512        compromise of authentication credentials. See the
2513        :ref:`VNC security` section in the System Emulation Users Guide
2514        for details on using SASL authentication.
2515
2516    ``sasl-authz=ID``
2517        Provides the ID of the QAuthZ authorization object against which
2518        the client's SASL username will validated. This object is only
2519        resolved at time of use, so can be deleted and recreated on the
2520        fly while the VNC server is active. If missing, it will default
2521        to denying access.
2522
2523    ``acl=on|off``
2524        Legacy method for enabling authorization of clients against the
2525        x509 distinguished name and SASL username. It results in the
2526        creation of two ``authz-list`` objects with IDs of
2527        ``vnc.username`` and ``vnc.x509dname``. The rules for these
2528        objects must be configured with the HMP ACL commands.
2529
2530        This option is deprecated and should no longer be used. The new
2531        ``sasl-authz`` and ``tls-authz`` options are a replacement.
2532
2533    ``lossy=on|off``
2534        Enable lossy compression methods (gradient, JPEG, ...). If this
2535        option is set, VNC client may receive lossy framebuffer updates
2536        depending on its encoding settings. Enabling this option can
2537        save a lot of bandwidth at the expense of quality.
2538
2539    ``non-adaptive=on|off``
2540        Disable adaptive encodings. Adaptive encodings are enabled by
2541        default. An adaptive encoding will try to detect frequently
2542        updated screen regions, and send updates in these regions using
2543        a lossy encoding (like JPEG). This can be really helpful to save
2544        bandwidth when playing videos. Disabling adaptive encodings
2545        restores the original static behavior of encodings like Tight.
2546
2547    ``share=[allow-exclusive|force-shared|ignore]``
2548        Set display sharing policy. 'allow-exclusive' allows clients to
2549        ask for exclusive access. As suggested by the rfb spec this is
2550        implemented by dropping other connections. Connecting multiple
2551        clients in parallel requires all clients asking for a shared
2552        session (vncviewer: -shared switch). This is the default.
2553        'force-shared' disables exclusive client access. Useful for
2554        shared desktop sessions, where you don't want someone forgetting
2555        specify -shared disconnect everybody else. 'ignore' completely
2556        ignores the shared flag and allows everybody connect
2557        unconditionally. Doesn't conform to the rfb spec but is
2558        traditional QEMU behavior.
2559
2560    ``key-delay-ms``
2561        Set keyboard delay, for key down and key up events, in
2562        milliseconds. Default is 10. Keyboards are low-bandwidth
2563        devices, so this slowdown can help the device and guest to keep
2564        up and not lose events in case events are arriving in bulk.
2565        Possible causes for the latter are flaky network connections, or
2566        scripts for automated testing.
2567
2568    ``audiodev=audiodev``
2569        Use the specified audiodev when the VNC client requests audio
2570        transmission. When not using an -audiodev argument, this option
2571        must be omitted, otherwise is must be present and specify a
2572        valid audiodev.
2573
2574    ``power-control=on|off``
2575        Permit the remote client to issue shutdown, reboot or reset power
2576        control requests.
2577ERST
2578
2579ARCHHEADING(, QEMU_ARCH_I386)
2580
2581ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
2582
2583DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
2584    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
2585    QEMU_ARCH_I386)
2586SRST
2587``-win2k-hack``
2588    Use it when installing Windows 2000 to avoid a disk full bug. After
2589    Windows 2000 is installed, you no longer need this option (this
2590    option slows down the IDE transfers).
2591ERST
2592
2593DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
2594    "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
2595    QEMU_ARCH_I386)
2596SRST
2597``-no-fd-bootchk``
2598    Disable boot signature checking for floppy disks in BIOS. May be
2599    needed to boot from old floppy disks.
2600ERST
2601
2602DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
2603           "-no-acpi        disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2604SRST
2605``-no-acpi``
2606    Disable ACPI (Advanced Configuration and Power Interface) support.
2607    Use it if your guest OS complains about ACPI problems (PC target
2608    machine only).
2609ERST
2610
2611DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
2612    "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
2613SRST
2614``-no-hpet``
2615    Disable HPET support. Deprecated, use '-machine hpet=off' instead.
2616ERST
2617
2618DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
2619    "-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"
2620    "                ACPI table description\n", QEMU_ARCH_I386)
2621SRST
2622``-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]...]``
2623    Add ACPI table with specified header fields and context from
2624    specified files. For file=, take whole ACPI table from the specified
2625    files, including all ACPI headers (possible overridden by other
2626    options). For data=, only data portion of the table is used, all
2627    header information is specified in the command line. If a SLIC table
2628    is supplied to QEMU, then the SLIC's oem\_id and oem\_table\_id
2629    fields will override the same in the RSDT and the FADT (a.k.a.
2630    FACP), in order to ensure the field matches required by the
2631    Microsoft SLIC spec and the ACPI spec.
2632ERST
2633
2634DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2635    "-smbios file=binary\n"
2636    "                load SMBIOS entry from binary file\n"
2637    "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2638    "              [,uefi=on|off]\n"
2639    "                specify SMBIOS type 0 fields\n"
2640    "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2641    "              [,uuid=uuid][,sku=str][,family=str]\n"
2642    "                specify SMBIOS type 1 fields\n"
2643    "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2644    "              [,asset=str][,location=str]\n"
2645    "                specify SMBIOS type 2 fields\n"
2646    "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2647    "              [,sku=str]\n"
2648    "                specify SMBIOS type 3 fields\n"
2649    "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2650    "              [,asset=str][,part=str][,max-speed=%d][,current-speed=%d]\n"
2651    "              [,processor-id=%d]\n"
2652    "                specify SMBIOS type 4 fields\n"
2653    "-smbios type=8[,external_reference=str][,internal_reference=str][,connector_type=%d][,port_type=%d]\n"
2654    "                specify SMBIOS type 8 fields\n"
2655    "-smbios type=11[,value=str][,path=filename]\n"
2656    "                specify SMBIOS type 11 fields\n"
2657    "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
2658    "               [,asset=str][,part=str][,speed=%d]\n"
2659    "                specify SMBIOS type 17 fields\n"
2660    "-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]\n"
2661    "                specify SMBIOS type 41 fields\n",
2662    QEMU_ARCH_I386 | QEMU_ARCH_ARM | QEMU_ARCH_LOONGARCH)
2663SRST
2664``-smbios file=binary``
2665    Load SMBIOS entry from binary file.
2666
2667``-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]``
2668    Specify SMBIOS type 0 fields
2669
2670``-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]``
2671    Specify SMBIOS type 1 fields
2672
2673``-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]``
2674    Specify SMBIOS type 2 fields
2675
2676``-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]``
2677    Specify SMBIOS type 3 fields
2678
2679``-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str][,processor-id=%d]``
2680    Specify SMBIOS type 4 fields
2681
2682``-smbios type=11[,value=str][,path=filename]``
2683    Specify SMBIOS type 11 fields
2684
2685    This argument can be repeated multiple times, and values are added in the order they are parsed.
2686    Applications intending to use OEM strings data are encouraged to use their application name as
2687    a prefix for the value string. This facilitates passing information for multiple applications
2688    concurrently.
2689
2690    The ``value=str`` syntax provides the string data inline, while the ``path=filename`` syntax
2691    loads data from a file on disk. Note that the file is not permitted to contain any NUL bytes.
2692
2693    Both the ``value`` and ``path`` options can be repeated multiple times and will be added to
2694    the SMBIOS table in the order in which they appear.
2695
2696    Note that on the x86 architecture, the total size of all SMBIOS tables is limited to 65535
2697    bytes. Thus the OEM strings data is not suitable for passing large amounts of data into the
2698    guest. Instead it should be used as a indicator to inform the guest where to locate the real
2699    data set, for example, by specifying the serial ID of a block device.
2700
2701    An example passing three strings is
2702
2703    .. parsed-literal::
2704
2705        -smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\\
2706                        value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\\
2707                        path=/some/file/with/oemstringsdata.txt
2708
2709    In the guest OS this is visible with the ``dmidecode`` command
2710
2711     .. parsed-literal::
2712
2713         $ dmidecode -t 11
2714         Handle 0x0E00, DMI type 11, 5 bytes
2715         OEM Strings
2716              String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/
2717              String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os
2718              String 3: myapp:some extra data
2719
2720
2721``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]``
2722    Specify SMBIOS type 17 fields
2723
2724``-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]``
2725    Specify SMBIOS type 41 fields
2726
2727    This argument can be repeated multiple times.  Its main use is to allow network interfaces be created
2728    as ``enoX`` on Linux, with X being the instance number, instead of the name depending on the interface
2729    position on the PCI bus.
2730
2731    Here is an example of use:
2732
2733    .. parsed-literal::
2734
2735        -netdev user,id=internet \\
2736        -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \\
2737        -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev
2738
2739    In the guest OS, the device should then appear as ``eno1``:
2740
2741    ..parsed-literal::
2742
2743         $ ip -brief l
2744         lo               UNKNOWN        00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
2745         eno1             UP             50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP>
2746
2747    Currently, the PCI device has to be attached to the root bus.
2748
2749ERST
2750
2751DEFHEADING()
2752
2753DEFHEADING(Network options:)
2754
2755DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
2756#ifdef CONFIG_SLIRP
2757    "-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]\n"
2758    "         [,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2759    "         [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
2760    "         [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
2761    "         [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
2762#ifndef _WIN32
2763                                             "[,smb=dir[,smbserver=addr]]\n"
2764#endif
2765    "                configure a user mode network backend with ID 'str',\n"
2766    "                its DHCP server and optional services\n"
2767#endif
2768#ifdef _WIN32
2769    "-netdev tap,id=str,ifname=name\n"
2770    "                configure a host TAP network backend with ID 'str'\n"
2771#else
2772    "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
2773    "         [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
2774    "         [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
2775    "         [,poll-us=n]\n"
2776    "                configure a host TAP network backend with ID 'str'\n"
2777    "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2778    "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2779    "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2780    "                to deconfigure it\n"
2781    "                use '[down]script=no' to disable script execution\n"
2782    "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2783    "                configure it\n"
2784    "                use 'fd=h' to connect to an already opened TAP interface\n"
2785    "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
2786    "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
2787    "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
2788    "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2789    "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
2790    "                use vhost=on to enable experimental in kernel accelerator\n"
2791    "                    (only has effect for virtio guests which use MSIX)\n"
2792    "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
2793    "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
2794    "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
2795    "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
2796    "                use 'poll-us=n' to specify the maximum number of microseconds that could be\n"
2797    "                spent on busy polling for vhost net\n"
2798    "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2799    "                configure a host TAP network backend with ID 'str' that is\n"
2800    "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2801    "                using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
2802#endif
2803#ifdef __linux__
2804    "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2805    "         [,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]\n"
2806    "         [,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]\n"
2807    "         [,rxcookie=rxcookie][,offset=offset]\n"
2808    "                configure a network backend with ID 'str' connected to\n"
2809    "                an Ethernet over L2TPv3 pseudowire.\n"
2810    "                Linux kernel 3.3+ as well as most routers can talk\n"
2811    "                L2TPv3. This transport allows connecting a VM to a VM,\n"
2812    "                VM to a router and even VM to Host. It is a nearly-universal\n"
2813    "                standard (RFC3931). Note - this implementation uses static\n"
2814    "                pre-configured tunnels (same as the Linux kernel).\n"
2815    "                use 'src=' to specify source address\n"
2816    "                use 'dst=' to specify destination address\n"
2817    "                use 'udp=on' to specify udp encapsulation\n"
2818    "                use 'srcport=' to specify source udp port\n"
2819    "                use 'dstport=' to specify destination udp port\n"
2820    "                use 'ipv6=on' to force v6\n"
2821    "                L2TPv3 uses cookies to prevent misconfiguration as\n"
2822    "                well as a weak security measure\n"
2823    "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
2824    "                use 'txcookie=0x012345678' to specify a txcookie\n"
2825    "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2826    "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2827    "                use 'pincounter=on' to work around broken counter handling in peer\n"
2828    "                use 'offset=X' to add an extra offset between header and data\n"
2829#endif
2830    "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2831    "                configure a network backend to connect to another network\n"
2832    "                using a socket connection\n"
2833    "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2834    "                configure a network backend to connect to a multicast maddr and port\n"
2835    "                use 'localaddr=addr' to specify the host address to send packets from\n"
2836    "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2837    "                configure a network backend to connect to another network\n"
2838    "                using an UDP tunnel\n"
2839    "-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off][,reconnect=seconds]\n"
2840    "-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off][,reconnect=seconds]\n"
2841    "-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor[,reconnect=seconds]\n"
2842    "                configure a network backend to connect to another network\n"
2843    "                using a socket connection in stream mode.\n"
2844    "-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]\n"
2845    "-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]\n"
2846    "                configure a network backend to connect to a multicast maddr and port\n"
2847    "                use ``local.host=addr`` to specify the host address to send packets from\n"
2848    "-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]\n"
2849    "-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]\n"
2850    "-netdev dgram,id=str,local.type=fd,local.str=file-descriptor\n"
2851    "                configure a network backend to connect to another network\n"
2852    "                using an UDP tunnel\n"
2853#ifdef CONFIG_VDE
2854    "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2855    "                configure a network backend to connect to port 'n' of a vde switch\n"
2856    "                running on host and listening for incoming connections on 'socketpath'.\n"
2857    "                Use group 'groupname' and mode 'octalmode' to change default\n"
2858    "                ownership and permissions for communication port.\n"
2859#endif
2860#ifdef CONFIG_NETMAP
2861    "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
2862    "                attach to the existing netmap-enabled network interface 'name', or to a\n"
2863    "                VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2864    "                netmap device, defaults to '/dev/netmap')\n"
2865#endif
2866#ifdef CONFIG_POSIX
2867    "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2868    "                configure a vhost-user network, backed by a chardev 'dev'\n"
2869#endif
2870#ifdef __linux__
2871    "-netdev vhost-vdpa,id=str[,vhostdev=/path/to/dev][,vhostfd=h]\n"
2872    "                configure a vhost-vdpa network,Establish a vhost-vdpa netdev\n"
2873    "                use 'vhostdev=/path/to/dev' to open a vhost vdpa device\n"
2874    "                use 'vhostfd=h' to connect to an already opened vhost vdpa device\n"
2875#endif
2876#ifdef CONFIG_VMNET
2877    "-netdev vmnet-host,id=str[,isolated=on|off][,net-uuid=uuid]\n"
2878    "         [,start-address=addr,end-address=addr,subnet-mask=mask]\n"
2879    "                configure a vmnet network backend in host mode with ID 'str',\n"
2880    "                isolate this interface from others with 'isolated',\n"
2881    "                configure the address range and choose a subnet mask,\n"
2882    "                specify network UUID 'uuid' to disable DHCP and interact with\n"
2883    "                vmnet-host interfaces within this isolated network\n"
2884    "-netdev vmnet-shared,id=str[,isolated=on|off][,nat66-prefix=addr]\n"
2885    "         [,start-address=addr,end-address=addr,subnet-mask=mask]\n"
2886    "                configure a vmnet network backend in shared mode with ID 'str',\n"
2887    "                configure the address range and choose a subnet mask,\n"
2888    "                set IPv6 ULA prefix (of length 64) to use for internal network,\n"
2889    "                isolate this interface from others with 'isolated'\n"
2890    "-netdev vmnet-bridged,id=str,ifname=name[,isolated=on|off]\n"
2891    "                configure a vmnet network backend in bridged mode with ID 'str',\n"
2892    "                use 'ifname=name' to select a physical network interface to be bridged,\n"
2893    "                isolate this interface from others with 'isolated'\n"
2894#endif
2895    "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
2896    "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
2897DEF("nic", HAS_ARG, QEMU_OPTION_nic,
2898    "-nic [tap|bridge|"
2899#ifdef CONFIG_SLIRP
2900    "user|"
2901#endif
2902#ifdef __linux__
2903    "l2tpv3|"
2904#endif
2905#ifdef CONFIG_VDE
2906    "vde|"
2907#endif
2908#ifdef CONFIG_NETMAP
2909    "netmap|"
2910#endif
2911#ifdef CONFIG_POSIX
2912    "vhost-user|"
2913#endif
2914#ifdef CONFIG_VMNET
2915    "vmnet-host|vmnet-shared|vmnet-bridged|"
2916#endif
2917    "socket][,option][,...][mac=macaddr]\n"
2918    "                initialize an on-board / default host NIC (using MAC address\n"
2919    "                macaddr) and connect it to the given host network backend\n"
2920    "-nic none       use it alone to have zero network devices (the default is to\n"
2921    "                provided a 'user' network connection)\n",
2922    QEMU_ARCH_ALL)
2923DEF("net", HAS_ARG, QEMU_OPTION_net,
2924    "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2925    "                configure or create an on-board (or machine default) NIC and\n"
2926    "                connect it to hub 0 (please use -nic unless you need a hub)\n"
2927    "-net ["
2928#ifdef CONFIG_SLIRP
2929    "user|"
2930#endif
2931    "tap|"
2932    "bridge|"
2933#ifdef CONFIG_VDE
2934    "vde|"
2935#endif
2936#ifdef CONFIG_NETMAP
2937    "netmap|"
2938#endif
2939#ifdef CONFIG_VMNET
2940    "vmnet-host|vmnet-shared|vmnet-bridged|"
2941#endif
2942    "socket][,option][,option][,...]\n"
2943    "                old way to initialize a host network interface\n"
2944    "                (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2945SRST
2946``-nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]``
2947    This option is a shortcut for configuring both the on-board
2948    (default) guest NIC hardware and the host network backend in one go.
2949    The host backend options are the same as with the corresponding
2950    ``-netdev`` options below. The guest NIC model can be set with
2951    ``model=modelname``. Use ``model=help`` to list the available device
2952    types. The hardware MAC address can be set with ``mac=macaddr``.
2953
2954    The following two example do exactly the same, to show how ``-nic``
2955    can be used to shorten the command line length:
2956
2957    .. parsed-literal::
2958
2959        |qemu_system| -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2960        |qemu_system| -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2961
2962``-nic none``
2963    Indicate that no network devices should be configured. It is used to
2964    override the default configuration (default NIC with "user" host
2965    network backend) which is activated if no other networking options
2966    are provided.
2967
2968``-netdev user,id=id[,option][,option][,...]``
2969    Configure user mode host network backend which requires no
2970    administrator privilege to run. Valid options are:
2971
2972    ``id=id``
2973        Assign symbolic name for use in monitor commands.
2974
2975    ``ipv4=on|off and ipv6=on|off``
2976        Specify that either IPv4 or IPv6 must be enabled. If neither is
2977        specified both protocols are enabled.
2978
2979    ``net=addr[/mask]``
2980        Set IP network address the guest will see. Optionally specify
2981        the netmask, either in the form a.b.c.d or as number of valid
2982        top-most bits. Default is 10.0.2.0/24.
2983
2984    ``host=addr``
2985        Specify the guest-visible address of the host. Default is the
2986        2nd IP in the guest network, i.e. x.x.x.2.
2987
2988    ``ipv6-net=addr[/int]``
2989        Set IPv6 network address the guest will see (default is
2990        fec0::/64). The network prefix is given in the usual hexadecimal
2991        IPv6 address notation. The prefix size is optional, and is given
2992        as the number of valid top-most bits (default is 64).
2993
2994    ``ipv6-host=addr``
2995        Specify the guest-visible IPv6 address of the host. Default is
2996        the 2nd IPv6 in the guest network, i.e. xxxx::2.
2997
2998    ``restrict=on|off``
2999        If this option is enabled, the guest will be isolated, i.e. it
3000        will not be able to contact the host and no guest IP packets
3001        will be routed over the host to the outside. This option does
3002        not affect any explicitly set forwarding rules.
3003
3004    ``hostname=name``
3005        Specifies the client hostname reported by the built-in DHCP
3006        server.
3007
3008    ``dhcpstart=addr``
3009        Specify the first of the 16 IPs the built-in DHCP server can
3010        assign. Default is the 15th to 31st IP in the guest network,
3011        i.e. x.x.x.15 to x.x.x.31.
3012
3013    ``dns=addr``
3014        Specify the guest-visible address of the virtual nameserver. The
3015        address must be different from the host address. Default is the
3016        3rd IP in the guest network, i.e. x.x.x.3.
3017
3018    ``ipv6-dns=addr``
3019        Specify the guest-visible address of the IPv6 virtual
3020        nameserver. The address must be different from the host address.
3021        Default is the 3rd IP in the guest network, i.e. xxxx::3.
3022
3023    ``dnssearch=domain``
3024        Provides an entry for the domain-search list sent by the
3025        built-in DHCP server. More than one domain suffix can be
3026        transmitted by specifying this option multiple times. If
3027        supported, this will cause the guest to automatically try to
3028        append the given domain suffix(es) in case a domain name can not
3029        be resolved.
3030
3031        Example:
3032
3033        .. parsed-literal::
3034
3035            |qemu_system| -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
3036
3037    ``domainname=domain``
3038        Specifies the client domain name reported by the built-in DHCP
3039        server.
3040
3041    ``tftp=dir``
3042        When using the user mode network stack, activate a built-in TFTP
3043        server. The files in dir will be exposed as the root of a TFTP
3044        server. The TFTP client on the guest must be configured in
3045        binary mode (use the command ``bin`` of the Unix TFTP client).
3046
3047    ``tftp-server-name=name``
3048        In BOOTP reply, broadcast name as the "TFTP server name"
3049        (RFC2132 option 66). This can be used to advise the guest to
3050        load boot files or configurations from a different server than
3051        the host address.
3052
3053    ``bootfile=file``
3054        When using the user mode network stack, broadcast file as the
3055        BOOTP filename. In conjunction with ``tftp``, this can be used
3056        to network boot a guest from a local directory.
3057
3058        Example (using pxelinux):
3059
3060        .. parsed-literal::
3061
3062            |qemu_system| -hda linux.img -boot n -device e1000,netdev=n1 \\
3063                -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
3064
3065    ``smb=dir[,smbserver=addr]``
3066        When using the user mode network stack, activate a built-in SMB
3067        server so that Windows OSes can access to the host files in
3068        ``dir`` transparently. The IP address of the SMB server can be
3069        set to addr. By default the 4th IP in the guest network is used,
3070        i.e. x.x.x.4.
3071
3072        In the guest Windows OS, the line:
3073
3074        ::
3075
3076            10.0.2.4 smbserver
3077
3078        must be added in the file ``C:\WINDOWS\LMHOSTS`` (for windows
3079        9x/Me) or ``C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS`` (Windows
3080        NT/2000).
3081
3082        Then ``dir`` can be accessed in ``\\smbserver\qemu``.
3083
3084        Note that a SAMBA server must be installed on the host OS.
3085
3086    ``hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport``
3087        Redirect incoming TCP or UDP connections to the host port
3088        hostport to the guest IP address guestaddr on guest port
3089        guestport. If guestaddr is not specified, its value is x.x.x.15
3090        (default first address given by the built-in DHCP server). By
3091        specifying hostaddr, the rule can be bound to a specific host
3092        interface. If no connection type is set, TCP is used. This
3093        option can be given multiple times.
3094
3095        For example, to redirect host X11 connection from screen 1 to
3096        guest screen 0, use the following:
3097
3098        .. parsed-literal::
3099
3100            # on the host
3101            |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
3102            # this host xterm should open in the guest X11 server
3103            xterm -display :1
3104
3105        To redirect telnet connections from host port 5555 to telnet
3106        port on the guest, use the following:
3107
3108        .. parsed-literal::
3109
3110            # on the host
3111            |qemu_system| -nic user,hostfwd=tcp::5555-:23
3112            telnet localhost 5555
3113
3114        Then when you use on the host ``telnet localhost 5555``, you
3115        connect to the guest telnet server.
3116
3117    ``guestfwd=[tcp]:server:port-dev``; \ ``guestfwd=[tcp]:server:port-cmd:command``
3118        Forward guest TCP connections to the IP address server on port
3119        port to the character device dev or to a program executed by
3120        cmd:command which gets spawned for each connection. This option
3121        can be given multiple times.
3122
3123        You can either use a chardev directly and have that one used
3124        throughout QEMU's lifetime, like in the following example:
3125
3126        .. parsed-literal::
3127
3128            # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
3129            # the guest accesses it
3130            |qemu_system| -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
3131
3132        Or you can execute a command on every TCP connection established
3133        by the guest, so that QEMU behaves similar to an inetd process
3134        for that virtual server:
3135
3136        .. parsed-literal::
3137
3138            # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
3139            # and connect the TCP stream to its stdin/stdout
3140            |qemu_system| -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
3141
3142``-netdev tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]``
3143    Configure a host TAP network backend with ID id.
3144
3145    Use the network script file to configure it and the network script
3146    dfile to deconfigure it. If name is not provided, the OS
3147    automatically provides one. The default network configure script is
3148    ``/etc/qemu-ifup`` and the default network deconfigure script is
3149    ``/etc/qemu-ifdown``. Use ``script=no`` or ``downscript=no`` to
3150    disable script execution.
3151
3152    If running QEMU as an unprivileged user, use the network helper
3153    to configure the TAP interface and attach it to the bridge.
3154    The default network helper executable is
3155    ``/path/to/qemu-bridge-helper`` and the default bridge device is
3156    ``br0``.
3157
3158    ``fd``\ =h can be used to specify the handle of an already opened
3159    host TAP interface.
3160
3161    Examples:
3162
3163    .. parsed-literal::
3164
3165        #launch a QEMU instance with the default network script
3166        |qemu_system| linux.img -nic tap
3167
3168    .. parsed-literal::
3169
3170        #launch a QEMU instance with two NICs, each one connected
3171        #to a TAP device
3172        |qemu_system| linux.img \\
3173                -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \\
3174                -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
3175
3176    .. parsed-literal::
3177
3178        #launch a QEMU instance with the default network helper to
3179        #connect a TAP device to bridge br0
3180        |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\
3181                -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
3182
3183``-netdev bridge,id=id[,br=bridge][,helper=helper]``
3184    Connect a host TAP network interface to a host bridge device.
3185
3186    Use the network helper helper to configure the TAP interface and
3187    attach it to the bridge. The default network helper executable is
3188    ``/path/to/qemu-bridge-helper`` and the default bridge device is
3189    ``br0``.
3190
3191    Examples:
3192
3193    .. parsed-literal::
3194
3195        #launch a QEMU instance with the default network helper to
3196        #connect a TAP device to bridge br0
3197        |qemu_system| linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
3198
3199    .. parsed-literal::
3200
3201        #launch a QEMU instance with the default network helper to
3202        #connect a TAP device to bridge qemubr0
3203        |qemu_system| linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
3204
3205``-netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]``
3206    This host network backend can be used to connect the guest's network
3207    to another QEMU virtual machine using a TCP socket connection. If
3208    ``listen`` is specified, QEMU waits for incoming connections on port
3209    (host is optional). ``connect`` is used to connect to another QEMU
3210    instance using the ``listen`` option. ``fd``\ =h specifies an
3211    already opened TCP socket.
3212
3213    Example:
3214
3215    .. parsed-literal::
3216
3217        # launch a first QEMU instance
3218        |qemu_system| linux.img \\
3219                         -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3220                         -netdev socket,id=n1,listen=:1234
3221        # connect the network of this instance to the network of the first instance
3222        |qemu_system| linux.img \\
3223                         -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\
3224                         -netdev socket,id=n2,connect=127.0.0.1:1234
3225
3226``-netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]``
3227    Configure a socket host network backend to share the guest's network
3228    traffic with another QEMU virtual machines using a UDP multicast
3229    socket, effectively making a bus for every QEMU with same multicast
3230    address maddr and port. NOTES:
3231
3232    1. Several QEMU can be running on different hosts and share same bus
3233       (assuming correct multicast setup for these hosts).
3234
3235    2. mcast support is compatible with User Mode Linux (argument
3236       ``ethN=mcast``), see http://user-mode-linux.sf.net.
3237
3238    3. Use ``fd=h`` to specify an already opened UDP multicast socket.
3239
3240    Example:
3241
3242    .. parsed-literal::
3243
3244        # launch one QEMU instance
3245        |qemu_system| linux.img \\
3246                         -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3247                         -netdev socket,id=n1,mcast=230.0.0.1:1234
3248        # launch another QEMU instance on same "bus"
3249        |qemu_system| linux.img \\
3250                         -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\
3251                         -netdev socket,id=n2,mcast=230.0.0.1:1234
3252        # launch yet another QEMU instance on same "bus"
3253        |qemu_system| linux.img \\
3254                         -device e1000,netdev=n3,mac=52:54:00:12:34:58 \\
3255                         -netdev socket,id=n3,mcast=230.0.0.1:1234
3256
3257    Example (User Mode Linux compat.):
3258
3259    .. parsed-literal::
3260
3261        # launch QEMU instance (note mcast address selected is UML's default)
3262        |qemu_system| linux.img \\
3263                         -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3264                         -netdev socket,id=n1,mcast=239.192.168.1:1102
3265        # launch UML
3266        /path/to/linux ubd0=/path/to/root_fs eth0=mcast
3267
3268    Example (send packets from host's 1.2.3.4):
3269
3270    .. parsed-literal::
3271
3272        |qemu_system| linux.img \\
3273                         -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3274                         -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
3275
3276``-netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]``
3277    Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
3278    is a popular protocol to transport Ethernet (and other Layer 2) data
3279    frames between two systems. It is present in routers, firewalls and
3280    the Linux kernel (from version 3.3 onwards).
3281
3282    This transport allows a VM to communicate to another VM, router or
3283    firewall directly.
3284
3285    ``src=srcaddr``
3286        source address (mandatory)
3287
3288    ``dst=dstaddr``
3289        destination address (mandatory)
3290
3291    ``udp``
3292        select udp encapsulation (default is ip).
3293
3294    ``srcport=srcport``
3295        source udp port.
3296
3297    ``dstport=dstport``
3298        destination udp port.
3299
3300    ``ipv6``
3301        force v6, otherwise defaults to v4.
3302
3303    ``rxcookie=rxcookie``; \ ``txcookie=txcookie``
3304        Cookies are a weak form of security in the l2tpv3 specification.
3305        Their function is mostly to prevent misconfiguration. By default
3306        they are 32 bit.
3307
3308    ``cookie64``
3309        Set cookie size to 64 bit instead of the default 32
3310
3311    ``counter=off``
3312        Force a 'cut-down' L2TPv3 with no counter as in
3313        draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
3314
3315    ``pincounter=on``
3316        Work around broken counter handling in peer. This may also help
3317        on networks which have packet reorder.
3318
3319    ``offset=offset``
3320        Add an extra offset between header and data
3321
3322    For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
3323    the bridge br-lan on the remote Linux host 1.2.3.4:
3324
3325    .. parsed-literal::
3326
3327        # Setup tunnel on linux host using raw ip as encapsulation
3328        # on 1.2.3.4
3329        ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \\
3330            encap udp udp_sport 16384 udp_dport 16384
3331        ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \\
3332            0xFFFFFFFF peer_session_id 0xFFFFFFFF
3333        ifconfig vmtunnel0 mtu 1500
3334        ifconfig vmtunnel0 up
3335        brctl addif br-lan vmtunnel0
3336
3337
3338        # on 4.3.2.1
3339        # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
3340
3341        |qemu_system| linux.img -device e1000,netdev=n1 \\
3342            -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
3343
3344``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]``
3345    Configure VDE backend to connect to PORT n of a vde switch running
3346    on host and listening for incoming connections on socketpath. Use
3347    GROUP groupname and MODE octalmode to change default ownership and
3348    permissions for communication port. This option is only available if
3349    QEMU has been compiled with vde support enabled.
3350
3351    Example:
3352
3353    .. parsed-literal::
3354
3355        # launch vde switch
3356        vde_switch -F -sock /tmp/myswitch
3357        # launch QEMU instance
3358        |qemu_system| linux.img -nic vde,sock=/tmp/myswitch
3359
3360``-netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]``
3361    Establish a vhost-user netdev, backed by a chardev id. The chardev
3362    should be a unix domain socket backed one. The vhost-user uses a
3363    specifically defined protocol to pass vhost ioctl replacement
3364    messages to an application on the other end of the socket. On
3365    non-MSIX guests, the feature can be forced with vhostforce. Use
3366    'queues=n' to specify the number of queues to be created for
3367    multiqueue vhost-user.
3368
3369    Example:
3370
3371    ::
3372
3373        qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
3374             -numa node,memdev=mem \
3375             -chardev socket,id=chr0,path=/path/to/socket \
3376             -netdev type=vhost-user,id=net0,chardev=chr0 \
3377             -device virtio-net-pci,netdev=net0
3378
3379``-netdev vhost-vdpa[,vhostdev=/path/to/dev][,vhostfd=h]``
3380    Establish a vhost-vdpa netdev.
3381
3382    vDPA device is a device that uses a datapath which complies with
3383    the virtio specifications with a vendor specific control path.
3384    vDPA devices can be both physically located on the hardware or
3385    emulated by software.
3386
3387``-netdev hubport,id=id,hubid=hubid[,netdev=nd]``
3388    Create a hub port on the emulated hub with ID hubid.
3389
3390    The hubport netdev lets you connect a NIC to a QEMU emulated hub
3391    instead of a single netdev. Alternatively, you can also connect the
3392    hubport to another netdev with ID nd by using the ``netdev=nd``
3393    option.
3394
3395``-net nic[,netdev=nd][,macaddr=mac][,model=type] [,name=name][,addr=addr][,vectors=v]``
3396    Legacy option to configure or create an on-board (or machine
3397    default) Network Interface Card(NIC) and connect it either to the
3398    emulated hub with ID 0 (i.e. the default hub), or to the netdev nd.
3399    If model is omitted, then the default NIC model associated with the
3400    machine type is used. Note that the default NIC model may change in
3401    future QEMU releases, so it is highly recommended to always specify
3402    a model. Optionally, the MAC address can be changed to mac, the
3403    device address set to addr (PCI cards only), and a name can be
3404    assigned for use in monitor commands. Optionally, for PCI cards, you
3405    can specify the number v of MSI-X vectors that the card should have;
3406    this option currently only affects virtio cards; set v = 0 to
3407    disable MSI-X. If no ``-net`` option is specified, a single NIC is
3408    created. QEMU can emulate several different models of network card.
3409    Use ``-net nic,model=help`` for a list of available devices for your
3410    target.
3411
3412``-net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]``
3413    Configure a host network backend (with the options corresponding to
3414    the same ``-netdev`` option) and connect it to the emulated hub 0
3415    (the default hub). Use name to specify the name of the hub port.
3416ERST
3417
3418DEFHEADING()
3419
3420DEFHEADING(Character device options:)
3421
3422DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
3423    "-chardev help\n"
3424    "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3425    "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]\n"
3426    "         [,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]\n"
3427    "         [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
3428    "-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]\n"
3429    "         [,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)\n"
3430    "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
3431    "         [,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]\n"
3432    "         [,logfile=PATH][,logappend=on|off]\n"
3433    "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3434    "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
3435    "         [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3436    "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
3437    "-chardev file,id=id,path=path[,input-path=input-file][,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3438    "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3439#ifdef _WIN32
3440    "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3441    "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3442#else
3443    "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3444    "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
3445#endif
3446#ifdef CONFIG_BRLAPI
3447    "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3448#endif
3449#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
3450        || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
3451    "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3452#endif
3453#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
3454    "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3455#endif
3456#if defined(CONFIG_SPICE)
3457    "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
3458    "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
3459#endif
3460    , QEMU_ARCH_ALL
3461)
3462
3463SRST
3464The general form of a character device option is:
3465
3466``-chardev backend,id=id[,mux=on|off][,options]``
3467    Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``,
3468    ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``,
3469    ``pty``, ``stdio``, ``braille``, ``parallel``,
3470    ``spicevmc``, ``spiceport``. The specific backend will determine the
3471    applicable options.
3472
3473    Use ``-chardev help`` to print all available chardev backend types.
3474
3475    All devices must have an id, which can be any string up to 127
3476    characters long. It is used to uniquely identify this device in
3477    other command line directives.
3478
3479    A character device may be used in multiplexing mode by multiple
3480    front-ends. Specify ``mux=on`` to enable this mode. A multiplexer is
3481    a "1:N" device, and here the "1" end is your specified chardev
3482    backend, and the "N" end is the various parts of QEMU that can talk
3483    to a chardev. If you create a chardev with ``id=myid`` and
3484    ``mux=on``, QEMU will create a multiplexer with your specified ID,
3485    and you can then configure multiple front ends to use that chardev
3486    ID for their input/output. Up to four different front ends can be
3487    connected to a single multiplexed chardev. (Without multiplexing
3488    enabled, a chardev can only be used by a single front end.) For
3489    instance you could use this to allow a single stdio chardev to be
3490    used by two serial ports and the QEMU monitor:
3491
3492    ::
3493
3494        -chardev stdio,mux=on,id=char0 \
3495        -mon chardev=char0,mode=readline \
3496        -serial chardev:char0 \
3497        -serial chardev:char0
3498
3499    You can have more than one multiplexer in a system configuration;
3500    for instance you could have a TCP port multiplexed between UART 0
3501    and UART 1, and stdio multiplexed between the QEMU monitor and a
3502    parallel port:
3503
3504    ::
3505
3506        -chardev stdio,mux=on,id=char0 \
3507        -mon chardev=char0,mode=readline \
3508        -parallel chardev:char0 \
3509        -chardev tcp,...,mux=on,id=char1 \
3510        -serial chardev:char1 \
3511        -serial chardev:char1
3512
3513    When you're using a multiplexed character device, some escape
3514    sequences are interpreted in the input. See the chapter about
3515    :ref:`keys in the character backend multiplexer` in the
3516    System Emulation Users Guide for more details.
3517
3518    Note that some other command line options may implicitly create
3519    multiplexed character backends; for instance ``-serial mon:stdio``
3520    creates a multiplexed stdio backend connected to the serial port and
3521    the QEMU monitor, and ``-nographic`` also multiplexes the console
3522    and the monitor to stdio.
3523
3524    There is currently no support for multiplexing in the other
3525    direction (where a single QEMU front end takes input and output from
3526    multiple chardevs).
3527
3528    Every backend supports the ``logfile`` option, which supplies the
3529    path to a file to record all data transmitted via the backend. The
3530    ``logappend`` option controls whether the log file will be truncated
3531    or appended to when opened.
3532
3533The available backends are:
3534
3535``-chardev null,id=id``
3536    A void device. This device will not emit any data, and will drop any
3537    data it receives. The null backend does not take any options.
3538
3539``-chardev socket,id=id[,TCP options or unix options][,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,tls-creds=id][,tls-authz=id]``
3540    Create a two-way stream socket, which can be either a TCP or a unix
3541    socket. A unix socket will be created if ``path`` is specified.
3542    Behaviour is undefined if TCP options are specified for a unix
3543    socket.
3544
3545    ``server=on|off`` specifies that the socket shall be a listening socket.
3546
3547    ``wait=on|off`` specifies that QEMU should not block waiting for a client
3548    to connect to a listening socket.
3549
3550    ``telnet=on|off`` specifies that traffic on the socket should interpret
3551    telnet escape sequences.
3552
3553    ``websocket=on|off`` specifies that the socket uses WebSocket protocol for
3554    communication.
3555
3556    ``reconnect`` sets the timeout for reconnecting on non-server
3557    sockets when the remote end goes away. qemu will delay this many
3558    seconds and then attempt to reconnect. Zero disables reconnecting,
3559    and is the default.
3560
3561    ``tls-creds`` requests enablement of the TLS protocol for
3562    encryption, and specifies the id of the TLS credentials to use for
3563    the handshake. The credentials must be previously created with the
3564    ``-object tls-creds`` argument.
3565
3566    ``tls-auth`` provides the ID of the QAuthZ authorization object
3567    against which the client's x509 distinguished name will be
3568    validated. This object is only resolved at time of use, so can be
3569    deleted and recreated on the fly while the chardev server is active.
3570    If missing, it will default to denying access.
3571
3572    TCP and unix socket options are given below:
3573
3574    ``TCP options: port=port[,host=host][,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]``
3575        ``host`` for a listening socket specifies the local address to
3576        be bound. For a connecting socket species the remote host to
3577        connect to. ``host`` is optional for listening sockets. If not
3578        specified it defaults to ``0.0.0.0``.
3579
3580        ``port`` for a listening socket specifies the local port to be
3581        bound. For a connecting socket specifies the port on the remote
3582        host to connect to. ``port`` can be given as either a port
3583        number or a service name. ``port`` is required.
3584
3585        ``to`` is only relevant to listening sockets. If it is
3586        specified, and ``port`` cannot be bound, QEMU will attempt to
3587        bind to subsequent ports up to and including ``to`` until it
3588        succeeds. ``to`` must be specified as a port number.
3589
3590        ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4
3591        or IPv6 must be used. If neither is specified the socket may
3592        use either protocol.
3593
3594        ``nodelay=on|off`` disables the Nagle algorithm.
3595
3596    ``unix options: path=path[,abstract=on|off][,tight=on|off]``
3597        ``path`` specifies the local path of the unix socket. ``path``
3598        is required.
3599        ``abstract=on|off`` specifies the use of the abstract socket namespace,
3600        rather than the filesystem.  Optional, defaults to false.
3601        ``tight=on|off`` sets the socket length of abstract sockets to their minimum,
3602        rather than the full sun_path length.  Optional, defaults to true.
3603
3604``-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4=on|off][,ipv6=on|off]``
3605    Sends all traffic from the guest to a remote host over UDP.
3606
3607    ``host`` specifies the remote host to connect to. If not specified
3608    it defaults to ``localhost``.
3609
3610    ``port`` specifies the port on the remote host to connect to.
3611    ``port`` is required.
3612
3613    ``localaddr`` specifies the local address to bind to. If not
3614    specified it defaults to ``0.0.0.0``.
3615
3616    ``localport`` specifies the local port to bind to. If not specified
3617    any available local port will be used.
3618
3619    ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4 or IPv6 must be used.
3620    If neither is specified the device may use either protocol.
3621
3622``-chardev msmouse,id=id``
3623    Forward QEMU's emulated msmouse events to the guest. ``msmouse``
3624    does not take any options.
3625
3626``-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]``
3627    Connect to a QEMU text console. ``vc`` may optionally be given a
3628    specific size.
3629
3630    ``width`` and ``height`` specify the width and height respectively
3631    of the console, in pixels.
3632
3633    ``cols`` and ``rows`` specify that the console be sized to fit a
3634    text console with the given dimensions.
3635
3636``-chardev ringbuf,id=id[,size=size]``
3637    Create a ring buffer with fixed size ``size``. size must be a power
3638    of two and defaults to ``64K``.
3639
3640``-chardev file,id=id,path=path[,input-path=input-path]``
3641    Log all traffic received from the guest to a file.
3642
3643    ``path`` specifies the path of the file to be opened. This file will
3644    be created if it does not already exist, and overwritten if it does.
3645    ``path`` is required.
3646
3647    If ``input-path`` is specified, this is the path of a second file
3648    which will be used for input. If ``input-path`` is not specified,
3649    no input will be available from the chardev.
3650
3651    Note that ``input-path`` is not supported on Windows hosts.
3652
3653``-chardev pipe,id=id,path=path``
3654    Create a two-way connection to the guest. The behaviour differs
3655    slightly between Windows hosts and other hosts:
3656
3657    On Windows, a single duplex pipe will be created at
3658    ``\\.pipe\path``.
3659
3660    On other hosts, 2 pipes will be created called ``path.in`` and
3661    ``path.out``. Data written to ``path.in`` will be received by the
3662    guest. Data written by the guest can be read from ``path.out``. QEMU
3663    will not create these fifos, and requires them to be present.
3664
3665    ``path`` forms part of the pipe path as described above. ``path`` is
3666    required.
3667
3668``-chardev console,id=id``
3669    Send traffic from the guest to QEMU's standard output. ``console``
3670    does not take any options.
3671
3672    ``console`` is only available on Windows hosts.
3673
3674``-chardev serial,id=id,path=path``
3675    Send traffic from the guest to a serial device on the host.
3676
3677    On Unix hosts serial will actually accept any tty device, not only
3678    serial lines.
3679
3680    ``path`` specifies the name of the serial device to open.
3681
3682``-chardev pty,id=id``
3683    Create a new pseudo-terminal on the host and connect to it. ``pty``
3684    does not take any options.
3685
3686    ``pty`` is not available on Windows hosts.
3687
3688``-chardev stdio,id=id[,signal=on|off]``
3689    Connect to standard input and standard output of the QEMU process.
3690
3691    ``signal`` controls if signals are enabled on the terminal, that
3692    includes exiting QEMU with the key sequence Control-c. This option
3693    is enabled by default, use ``signal=off`` to disable it.
3694
3695``-chardev braille,id=id``
3696    Connect to a local BrlAPI server. ``braille`` does not take any
3697    options.
3698
3699``-chardev parallel,id=id,path=path``
3700  \
3701    ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD
3702    hosts.
3703
3704    Connect to a local parallel port.
3705
3706    ``path`` specifies the path to the parallel port device. ``path`` is
3707    required.
3708
3709``-chardev spicevmc,id=id,debug=debug,name=name``
3710    ``spicevmc`` is only available when spice support is built in.
3711
3712    ``debug`` debug level for spicevmc
3713
3714    ``name`` name of spice channel to connect to
3715
3716    Connect to a spice virtual machine channel, such as vdiport.
3717
3718``-chardev spiceport,id=id,debug=debug,name=name``
3719    ``spiceport`` is only available when spice support is built in.
3720
3721    ``debug`` debug level for spicevmc
3722
3723    ``name`` name of spice port to connect to
3724
3725    Connect to a spice port, allowing a Spice client to handle the
3726    traffic identified by a name (preferably a fqdn).
3727ERST
3728
3729DEFHEADING()
3730
3731#ifdef CONFIG_TPM
3732DEFHEADING(TPM device options:)
3733
3734DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3735    "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3736    "                use path to provide path to a character device; default is /dev/tpm0\n"
3737    "                use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3738    "                not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3739    "-tpmdev emulator,id=id,chardev=dev\n"
3740    "                configure the TPM device using chardev backend\n",
3741    QEMU_ARCH_ALL)
3742SRST
3743The general form of a TPM device option is:
3744
3745``-tpmdev backend,id=id[,options]``
3746    The specific backend type will determine the applicable options. The
3747    ``-tpmdev`` option creates the TPM backend and requires a
3748    ``-device`` option that specifies the TPM frontend interface model.
3749
3750    Use ``-tpmdev help`` to print all available TPM backend types.
3751
3752The available backends are:
3753
3754``-tpmdev passthrough,id=id,path=path,cancel-path=cancel-path``
3755    (Linux-host only) Enable access to the host's TPM using the
3756    passthrough driver.
3757
3758    ``path`` specifies the path to the host's TPM device, i.e., on a
3759    Linux host this would be ``/dev/tpm0``. ``path`` is optional and by
3760    default ``/dev/tpm0`` is used.
3761
3762    ``cancel-path`` specifies the path to the host TPM device's sysfs
3763    entry allowing for cancellation of an ongoing TPM command.
3764    ``cancel-path`` is optional and by default QEMU will search for the
3765    sysfs entry to use.
3766
3767    Some notes about using the host's TPM with the passthrough driver:
3768
3769    The TPM device accessed by the passthrough driver must not be used
3770    by any other application on the host.
3771
3772    Since the host's firmware (BIOS/UEFI) has already initialized the
3773    TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
3774    the TPM again and may therefore not show a TPM-specific menu that
3775    would otherwise allow the user to configure the TPM, e.g., allow the
3776    user to enable/disable or activate/deactivate the TPM. Further, if
3777    TPM ownership is released from within a VM then the host's TPM will
3778    get disabled and deactivated. To enable and activate the TPM again
3779    afterwards, the host has to be rebooted and the user is required to
3780    enter the firmware's menu to enable and activate the TPM. If the TPM
3781    is left disabled and/or deactivated most TPM commands will fail.
3782
3783    To create a passthrough TPM use the following two options:
3784
3785    ::
3786
3787        -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3788
3789    Note that the ``-tpmdev`` id is ``tpm0`` and is referenced by
3790    ``tpmdev=tpm0`` in the device option.
3791
3792``-tpmdev emulator,id=id,chardev=dev``
3793    (Linux-host only) Enable access to a TPM emulator using Unix domain
3794    socket based chardev backend.
3795
3796    ``chardev`` specifies the unique ID of a character device backend
3797    that provides connection to the software TPM server.
3798
3799    To create a TPM emulator backend device with chardev socket backend:
3800
3801    ::
3802
3803        -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3804ERST
3805
3806DEFHEADING()
3807
3808#endif
3809
3810DEFHEADING(Boot Image or Kernel specific:)
3811SRST
3812There are broadly 4 ways you can boot a system with QEMU.
3813
3814 - specify a firmware and let it control finding a kernel
3815 - specify a firmware and pass a hint to the kernel to boot
3816 - direct kernel image boot
3817 - manually load files into the guest's address space
3818
3819The third method is useful for quickly testing kernels but as there is
3820no firmware to pass configuration information to the kernel the
3821hardware must either be probeable, the kernel built for the exact
3822configuration or passed some configuration data (e.g. a DTB blob)
3823which tells the kernel what drivers it needs. This exact details are
3824often hardware specific.
3825
3826The final method is the most generic way of loading images into the
3827guest address space and used mostly for ``bare metal`` type
3828development where the reset vectors of the processor are taken into
3829account.
3830
3831ERST
3832
3833SRST
3834
3835For x86 machines and some other architectures ``-bios`` will generally
3836do the right thing with whatever it is given. For other machines the
3837more strict ``-pflash`` option needs an image that is sized for the
3838flash device for the given machine type.
3839
3840Please see the :ref:`system-targets-ref` section of the manual for
3841more detailed documentation.
3842
3843ERST
3844
3845DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3846    "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
3847SRST
3848``-bios file``
3849    Set the filename for the BIOS.
3850ERST
3851
3852DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
3853    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
3854SRST
3855``-pflash file``
3856    Use file as a parallel flash image.
3857ERST
3858
3859SRST
3860
3861The kernel options were designed to work with Linux kernels although
3862other things (like hypervisors) can be packaged up as a kernel
3863executable image. The exact format of a executable image is usually
3864architecture specific.
3865
3866The way in which the kernel is started (what address it is loaded at,
3867what if any information is passed to it via CPU registers, the state
3868of the hardware when it is started, and so on) is also architecture
3869specific. Typically it follows the specification laid down by the
3870Linux kernel for how kernels for that architecture must be started.
3871
3872ERST
3873
3874DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3875    "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3876SRST
3877``-kernel bzImage``
3878    Use bzImage as kernel image. The kernel can be either a Linux kernel
3879    or in multiboot format.
3880ERST
3881
3882DEF("append", HAS_ARG, QEMU_OPTION_append, \
3883    "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3884SRST
3885``-append cmdline``
3886    Use cmdline as kernel command line
3887ERST
3888
3889DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3890           "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3891SRST
3892``-initrd file``
3893    Use file as initial ram disk.
3894
3895``-initrd "file1 arg=foo,file2"``
3896    This syntax is only available with multiboot.
3897
3898    Use file1 and file2 as modules and pass arg=foo as parameter to the
3899    first module.
3900ERST
3901
3902DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3903    "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
3904SRST
3905``-dtb file``
3906    Use file as a device tree binary (dtb) image and pass it to the
3907    kernel on boot.
3908ERST
3909
3910SRST
3911
3912Finally you can also manually load images directly into the address
3913space of the guest. This is most useful for developers who already
3914know the layout of their guest and take care to ensure something sane
3915will happen when the reset vector executes.
3916
3917The generic loader can be invoked by using the loader device:
3918
3919``-device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]``
3920
3921there is also the guest loader which operates in a similar way but
3922tweaks the DTB so a hypervisor loaded via ``-kernel`` can find where
3923the guest image is:
3924
3925``-device guest-loader,addr=<addr>[,kernel=<path>,[bootargs=<arguments>]][,initrd=<path>]``
3926
3927ERST
3928
3929DEFHEADING()
3930
3931DEFHEADING(Debug/Expert options:)
3932
3933DEF("compat", HAS_ARG, QEMU_OPTION_compat,
3934    "-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]\n"
3935    "                Policy for handling deprecated management interfaces\n"
3936    "-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]\n"
3937    "                Policy for handling unstable management interfaces\n",
3938    QEMU_ARCH_ALL)
3939SRST
3940``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
3941    Set policy for handling deprecated management interfaces (experimental):
3942
3943    ``deprecated-input=accept`` (default)
3944        Accept deprecated commands and arguments
3945    ``deprecated-input=reject``
3946        Reject deprecated commands and arguments
3947    ``deprecated-input=crash``
3948        Crash on deprecated commands and arguments
3949    ``deprecated-output=accept`` (default)
3950        Emit deprecated command results and events
3951    ``deprecated-output=hide``
3952        Suppress deprecated command results and events
3953
3954    Limitation: covers only syntactic aspects of QMP.
3955
3956``-compat [unstable-input=@var{input-policy}][,unstable-output=@var{output-policy}]``
3957    Set policy for handling unstable management interfaces (experimental):
3958
3959    ``unstable-input=accept`` (default)
3960        Accept unstable commands and arguments
3961    ``unstable-input=reject``
3962        Reject unstable commands and arguments
3963    ``unstable-input=crash``
3964        Crash on unstable commands and arguments
3965    ``unstable-output=accept`` (default)
3966        Emit unstable command results and events
3967    ``unstable-output=hide``
3968        Suppress unstable command results and events
3969
3970    Limitation: covers only syntactic aspects of QMP.
3971ERST
3972
3973DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3974    "-fw_cfg [name=]<name>,file=<file>\n"
3975    "                add named fw_cfg entry with contents from file\n"
3976    "-fw_cfg [name=]<name>,string=<str>\n"
3977    "                add named fw_cfg entry with contents from string\n",
3978    QEMU_ARCH_ALL)
3979SRST
3980``-fw_cfg [name=]name,file=file``
3981    Add named fw\_cfg entry with contents from file file.
3982
3983``-fw_cfg [name=]name,string=str``
3984    Add named fw\_cfg entry with contents from string str.
3985
3986    The terminating NUL character of the contents of str will not be
3987    included as part of the fw\_cfg item data. To insert contents with
3988    embedded NUL characters, you have to use the file parameter.
3989
3990    The fw\_cfg entries are passed by QEMU through to the guest.
3991
3992    Example:
3993
3994    ::
3995
3996            -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3997
3998    creates an fw\_cfg entry named opt/com.mycompany/blob with contents
3999    from ./my\_blob.bin.
4000ERST
4001
4002DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
4003    "-serial dev     redirect the serial port to char device 'dev'\n",
4004    QEMU_ARCH_ALL)
4005SRST
4006``-serial dev``
4007    Redirect the virtual serial port to host character device dev. The
4008    default device is ``vc`` in graphical mode and ``stdio`` in non
4009    graphical mode.
4010
4011    This option can be used several times to simulate up to 4 serial
4012    ports.
4013
4014    Use ``-serial none`` to disable all serial ports.
4015
4016    Available character devices are:
4017
4018    ``vc[:WxH]``
4019        Virtual console. Optionally, a width and height can be given in
4020        pixel with
4021
4022        ::
4023
4024            vc:800x600
4025
4026        It is also possible to specify width or height in characters:
4027
4028        ::
4029
4030            vc:80Cx24C
4031
4032    ``pty``
4033        [Linux only] Pseudo TTY (a new PTY is automatically allocated)
4034
4035    ``none``
4036        No device is allocated.
4037
4038    ``null``
4039        void device
4040
4041    ``chardev:id``
4042        Use a named character device defined with the ``-chardev``
4043        option.
4044
4045    ``/dev/XXX``
4046        [Linux only] Use host tty, e.g. ``/dev/ttyS0``. The host serial
4047        port parameters are set according to the emulated ones.
4048
4049    ``/dev/parportN``
4050        [Linux only, parallel port only] Use host parallel port N.
4051        Currently SPP and EPP parallel port features can be used.
4052
4053    ``file:filename``
4054        Write output to filename. No character can be read.
4055
4056    ``stdio``
4057        [Unix only] standard input/output
4058
4059    ``pipe:filename``
4060        name pipe filename
4061
4062    ``COMn``
4063        [Windows only] Use host serial port n
4064
4065    ``udp:[remote_host]:remote_port[@[src_ip]:src_port]``
4066        This implements UDP Net Console. When remote\_host or src\_ip
4067        are not specified they default to ``0.0.0.0``. When not using a
4068        specified src\_port a random port is automatically chosen.
4069
4070        If you just want a simple readonly console you can use
4071        ``netcat`` or ``nc``, by starting QEMU with:
4072        ``-serial udp::4555`` and nc as: ``nc -u -l -p 4555``. Any time
4073        QEMU writes something to that port it will appear in the
4074        netconsole session.
4075
4076        If you plan to send characters back via netconsole or you want
4077        to stop and start QEMU a lot of times, you should have QEMU use
4078        the same source port each time by using something like ``-serial
4079        udp::4555@:4556`` to QEMU. Another approach is to use a patched
4080        version of netcat which can listen to a TCP port and send and
4081        receive characters via udp. If you have a patched version of
4082        netcat which activates telnet remote echo and single char
4083        transfer, then you can use the following options to set up a
4084        netcat redirector to allow telnet on port 5555 to access the
4085        QEMU port.
4086
4087        ``QEMU Options:``
4088            -serial udp::4555@:4556
4089
4090        ``netcat options:``
4091            -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
4092
4093        ``telnet options:``
4094            localhost 5555
4095
4096    ``tcp:[host]:port[,server=on|off][,wait=on|off][,nodelay=on|off][,reconnect=seconds]``
4097        The TCP Net Console has two modes of operation. It can send the
4098        serial I/O to a location or wait for a connection from a
4099        location. By default the TCP Net Console is sent to host at the
4100        port. If you use the ``server=on`` option QEMU will wait for a client
4101        socket application to connect to the port before continuing,
4102        unless the ``wait=on|off`` option was specified. The ``nodelay=on|off``
4103        option disables the Nagle buffering algorithm. The ``reconnect=on``
4104        option only applies if ``server=no`` is set, if the connection goes
4105        down it will attempt to reconnect at the given interval. If host
4106        is omitted, 0.0.0.0 is assumed. Only one TCP connection at a
4107        time is accepted. You can use ``telnet=on`` to connect to the
4108        corresponding character device.
4109
4110        ``Example to send tcp console to 192.168.0.2 port 4444``
4111            -serial tcp:192.168.0.2:4444
4112
4113        ``Example to listen and wait on port 4444 for connection``
4114            -serial tcp::4444,server=on
4115
4116        ``Example to not wait and listen on ip 192.168.0.100 port 4444``
4117            -serial tcp:192.168.0.100:4444,server=on,wait=off
4118
4119    ``telnet:host:port[,server=on|off][,wait=on|off][,nodelay=on|off]``
4120        The telnet protocol is used instead of raw tcp sockets. The
4121        options work the same as if you had specified ``-serial tcp``.
4122        The difference is that the port acts like a telnet server or
4123        client using telnet option negotiation. This will also allow you
4124        to send the MAGIC\_SYSRQ sequence if you use a telnet that
4125        supports sending the break sequence. Typically in unix telnet
4126        you do it with Control-] and then type "send break" followed by
4127        pressing the enter key.
4128
4129    ``websocket:host:port,server=on[,wait=on|off][,nodelay=on|off]``
4130        The WebSocket protocol is used instead of raw tcp socket. The
4131        port acts as a WebSocket server. Client mode is not supported.
4132
4133    ``unix:path[,server=on|off][,wait=on|off][,reconnect=seconds]``
4134        A unix domain socket is used instead of a tcp socket. The option
4135        works the same as if you had specified ``-serial tcp`` except
4136        the unix domain socket path is used for connections.
4137
4138    ``mon:dev_string``
4139        This is a special option to allow the monitor to be multiplexed
4140        onto another serial port. The monitor is accessed with key
4141        sequence of Control-a and then pressing c. dev\_string should be
4142        any one of the serial devices specified above. An example to
4143        multiplex the monitor onto a telnet server listening on port
4144        4444 would be:
4145
4146        ``-serial mon:telnet::4444,server=on,wait=off``
4147
4148        When the monitor is multiplexed to stdio in this way, Ctrl+C
4149        will not terminate QEMU any more but will be passed to the guest
4150        instead.
4151
4152    ``braille``
4153        Braille device. This will use BrlAPI to display the braille
4154        output on a real or fake device.
4155
4156    ``msmouse``
4157        Three button serial mouse. Configure the guest to use Microsoft
4158        protocol.
4159ERST
4160
4161DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
4162    "-parallel dev   redirect the parallel port to char device 'dev'\n",
4163    QEMU_ARCH_ALL)
4164SRST
4165``-parallel dev``
4166    Redirect the virtual parallel port to host device dev (same devices
4167    as the serial port). On Linux hosts, ``/dev/parportN`` can be used
4168    to use hardware devices connected on the corresponding host parallel
4169    port.
4170
4171    This option can be used several times to simulate up to 3 parallel
4172    ports.
4173
4174    Use ``-parallel none`` to disable all parallel ports.
4175ERST
4176
4177DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
4178    "-monitor dev    redirect the monitor to char device 'dev'\n",
4179    QEMU_ARCH_ALL)
4180SRST
4181``-monitor dev``
4182    Redirect the monitor to host device dev (same devices as the serial
4183    port). The default device is ``vc`` in graphical mode and ``stdio``
4184    in non graphical mode. Use ``-monitor none`` to disable the default
4185    monitor.
4186ERST
4187DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
4188    "-qmp dev        like -monitor but opens in 'control' mode\n",
4189    QEMU_ARCH_ALL)
4190SRST
4191``-qmp dev``
4192    Like ``-monitor`` but opens in 'control' mode. For example, to make
4193    QMP available on localhost port 4444::
4194
4195        -qmp tcp:localhost:4444,server=on,wait=off
4196
4197    Not all options are configurable via this syntax; for maximum
4198    flexibility use the ``-mon`` option and an accompanying ``-chardev``.
4199
4200ERST
4201DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
4202    "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
4203    QEMU_ARCH_ALL)
4204SRST
4205``-qmp-pretty dev``
4206    Like ``-qmp`` but uses pretty JSON formatting.
4207ERST
4208
4209DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
4210    "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
4211SRST
4212``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
4213    Set up a monitor connected to the chardev ``name``.
4214    QEMU supports two monitors: the Human Monitor Protocol
4215    (HMP; for human interaction), and the QEMU Monitor Protocol
4216    (QMP; a JSON RPC-style protocol).
4217    The default is HMP; ``mode=control`` selects QMP instead.
4218    ``pretty`` is only valid when ``mode=control``,
4219    turning on JSON pretty printing to ease
4220    human reading and debugging.
4221
4222    For example::
4223
4224      -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \
4225      -mon chardev=mon1,mode=control,pretty=on
4226
4227    enables the QMP monitor on localhost port 4444 with pretty-printing.
4228ERST
4229
4230DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
4231    "-debugcon dev   redirect the debug console to char device 'dev'\n",
4232    QEMU_ARCH_ALL)
4233SRST
4234``-debugcon dev``
4235    Redirect the debug console to host device dev (same devices as the
4236    serial port). The debug console is an I/O port which is typically
4237    port 0xe9; writing to that I/O port sends output to this device. The
4238    default device is ``vc`` in graphical mode and ``stdio`` in non
4239    graphical mode.
4240ERST
4241
4242DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
4243    "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
4244SRST
4245``-pidfile file``
4246    Store the QEMU process PID in file. It is useful if you launch QEMU
4247    from a script.
4248ERST
4249
4250DEF("singlestep", 0, QEMU_OPTION_singlestep, \
4251    "-singlestep     deprecated synonym for -accel tcg,one-insn-per-tb=on\n", QEMU_ARCH_ALL)
4252SRST
4253``-singlestep``
4254    This is a deprecated synonym for the TCG accelerator property
4255    ``one-insn-per-tb``.
4256ERST
4257
4258DEF("preconfig", 0, QEMU_OPTION_preconfig, \
4259    "--preconfig     pause QEMU before machine is initialized (experimental)\n",
4260    QEMU_ARCH_ALL)
4261SRST
4262``--preconfig``
4263    Pause QEMU for interactive configuration before the machine is
4264    created, which allows querying and configuring properties that will
4265    affect machine initialization. Use QMP command 'x-exit-preconfig' to
4266    exit the preconfig state and move to the next state (i.e. run guest
4267    if -S isn't used or pause the second time if -S is used). This
4268    option is experimental.
4269ERST
4270
4271DEF("S", 0, QEMU_OPTION_S, \
4272    "-S              freeze CPU at startup (use 'c' to start execution)\n",
4273    QEMU_ARCH_ALL)
4274SRST
4275``-S``
4276    Do not start CPU at startup (you must type 'c' in the monitor).
4277ERST
4278
4279DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
4280    "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
4281    "                run qemu with overcommit hints\n"
4282    "                mem-lock=on|off controls memory lock support (default: off)\n"
4283    "                cpu-pm=on|off controls cpu power management (default: off)\n",
4284    QEMU_ARCH_ALL)
4285SRST
4286``-overcommit mem-lock=on|off``
4287  \
4288``-overcommit cpu-pm=on|off``
4289    Run qemu with hints about host resource overcommit. The default is
4290    to assume that host overcommits all resources.
4291
4292    Locking qemu and guest memory can be enabled via ``mem-lock=on``
4293    (disabled by default). This works when host memory is not
4294    overcommitted and reduces the worst-case latency for guest.
4295
4296    Guest ability to manage power state of host cpus (increasing latency
4297    for other processes on the same host cpu, but decreasing latency for
4298    guest) can be enabled via ``cpu-pm=on`` (disabled by default). This
4299    works best when host CPU is not overcommitted. When used, host
4300    estimates of CPU cycle and power utilization will be incorrect, not
4301    taking into account guest idle time.
4302ERST
4303
4304DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
4305    "-gdb dev        accept gdb connection on 'dev'. (QEMU defaults to starting\n"
4306    "                the guest without waiting for gdb to connect; use -S too\n"
4307    "                if you want it to not start execution.)\n",
4308    QEMU_ARCH_ALL)
4309SRST
4310``-gdb dev``
4311    Accept a gdb connection on device dev (see the :ref:`GDB usage` chapter
4312    in the System Emulation Users Guide). Note that this option does not pause QEMU
4313    execution -- if you want QEMU to not start the guest until you
4314    connect with gdb and issue a ``continue`` command, you will need to
4315    also pass the ``-S`` option to QEMU.
4316
4317    The most usual configuration is to listen on a local TCP socket::
4318
4319        -gdb tcp::3117
4320
4321    but you can specify other backends; UDP, pseudo TTY, or even stdio
4322    are all reasonable use cases. For example, a stdio connection
4323    allows you to start QEMU from within gdb and establish the
4324    connection via a pipe:
4325
4326    .. parsed-literal::
4327
4328        (gdb) target remote | exec |qemu_system| -gdb stdio ...
4329ERST
4330
4331DEF("s", 0, QEMU_OPTION_s, \
4332    "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
4333    QEMU_ARCH_ALL)
4334SRST
4335``-s``
4336    Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
4337    (see the :ref:`GDB usage` chapter in the System Emulation Users Guide).
4338ERST
4339
4340DEF("d", HAS_ARG, QEMU_OPTION_d, \
4341    "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
4342    QEMU_ARCH_ALL)
4343SRST
4344``-d item1[,...]``
4345    Enable logging of specified items. Use '-d help' for a list of log
4346    items.
4347ERST
4348
4349DEF("D", HAS_ARG, QEMU_OPTION_D, \
4350    "-D logfile      output log to logfile (default stderr)\n",
4351    QEMU_ARCH_ALL)
4352SRST
4353``-D logfile``
4354    Output log in logfile instead of to stderr
4355ERST
4356
4357DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
4358    "-dfilter range,..  filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
4359    QEMU_ARCH_ALL)
4360SRST
4361``-dfilter range1[,...]``
4362    Filter debug output to that relevant to a range of target addresses.
4363    The filter spec can be either start+size, start-size or start..end
4364    where start end and size are the addresses and sizes required. For
4365    example:
4366
4367    ::
4368
4369            -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
4370
4371    Will dump output for any code in the 0x1000 sized block starting at
4372    0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and
4373    another 0x1000 sized block starting at 0xffffffc00005f000.
4374ERST
4375
4376DEF("seed", HAS_ARG, QEMU_OPTION_seed, \
4377    "-seed number       seed the pseudo-random number generator\n",
4378    QEMU_ARCH_ALL)
4379SRST
4380``-seed number``
4381    Force the guest to use a deterministic pseudo-random number
4382    generator, seeded with number. This does not affect crypto routines
4383    within the host.
4384ERST
4385
4386DEF("L", HAS_ARG, QEMU_OPTION_L, \
4387    "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
4388    QEMU_ARCH_ALL)
4389SRST
4390``-L  path``
4391    Set the directory for the BIOS, VGA BIOS and keymaps.
4392
4393    To list all the data directories, use ``-L help``.
4394ERST
4395
4396DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
4397    "-enable-kvm     enable KVM full virtualization support\n",
4398    QEMU_ARCH_ARM | QEMU_ARCH_I386 | QEMU_ARCH_MIPS | QEMU_ARCH_PPC |
4399    QEMU_ARCH_RISCV | QEMU_ARCH_S390X)
4400SRST
4401``-enable-kvm``
4402    Enable KVM full virtualization support. This option is only
4403    available if KVM support is enabled when compiling.
4404ERST
4405
4406DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
4407    "-xen-domid id   specify xen guest domain id\n",
4408    QEMU_ARCH_ARM | QEMU_ARCH_I386)
4409DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
4410    "-xen-attach     attach to existing xen domain\n"
4411    "                libxl will use this when starting QEMU\n",
4412    QEMU_ARCH_ARM | QEMU_ARCH_I386)
4413DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
4414    "-xen-domid-restrict     restrict set of available xen operations\n"
4415    "                        to specified domain id. (Does not affect\n"
4416    "                        xenpv machine type).\n",
4417    QEMU_ARCH_ARM | QEMU_ARCH_I386)
4418SRST
4419``-xen-domid id``
4420    Specify xen guest domain id (XEN only).
4421
4422``-xen-attach``
4423    Attach to existing xen domain. libxl will use this when starting
4424    QEMU (XEN only). Restrict set of available xen operations to
4425    specified domain id (XEN only).
4426ERST
4427
4428DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
4429    "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
4430SRST
4431``-no-reboot``
4432    Exit instead of rebooting.
4433ERST
4434
4435DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
4436    "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
4437SRST
4438``-no-shutdown``
4439    Don't exit QEMU on guest shutdown, but instead only stop the
4440    emulation. This allows for instance switching to monitor to commit
4441    changes to the disk image.
4442ERST
4443
4444DEF("action", HAS_ARG, QEMU_OPTION_action,
4445    "-action reboot=reset|shutdown\n"
4446    "                   action when guest reboots [default=reset]\n"
4447    "-action shutdown=poweroff|pause\n"
4448    "                   action when guest shuts down [default=poweroff]\n"
4449    "-action panic=pause|shutdown|exit-failure|none\n"
4450    "                   action when guest panics [default=shutdown]\n"
4451    "-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none\n"
4452    "                   action when watchdog fires [default=reset]\n",
4453    QEMU_ARCH_ALL)
4454SRST
4455``-action event=action``
4456    The action parameter serves to modify QEMU's default behavior when
4457    certain guest events occur. It provides a generic method for specifying the
4458    same behaviors that are modified by the ``-no-reboot`` and ``-no-shutdown``
4459    parameters.
4460
4461    Examples:
4462
4463    ``-action panic=none``
4464    ``-action reboot=shutdown,shutdown=pause``
4465    ``-device i6300esb -action watchdog=pause``
4466
4467ERST
4468
4469DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
4470    "-loadvm [tag|id]\n" \
4471    "                start right away with a saved state (loadvm in monitor)\n",
4472    QEMU_ARCH_ALL)
4473SRST
4474``-loadvm file``
4475    Start right away with a saved state (``loadvm`` in monitor)
4476ERST
4477
4478#ifndef _WIN32
4479DEF("daemonize", 0, QEMU_OPTION_daemonize, \
4480    "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
4481#endif
4482SRST
4483``-daemonize``
4484    Daemonize the QEMU process after initialization. QEMU will not
4485    detach from standard IO until it is ready to receive connections on
4486    any of its devices. This option is a useful way for external
4487    programs to launch QEMU without having to cope with initialization
4488    race conditions.
4489ERST
4490
4491DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
4492    "-option-rom rom load a file, rom, into the option ROM space\n",
4493    QEMU_ARCH_ALL)
4494SRST
4495``-option-rom file``
4496    Load the contents of file as an option ROM. This option is useful to
4497    load things like EtherBoot.
4498ERST
4499
4500DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
4501    "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
4502    "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
4503    QEMU_ARCH_ALL)
4504
4505SRST
4506``-rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]``
4507    Specify ``base`` as ``utc`` or ``localtime`` to let the RTC start at
4508    the current UTC or local time, respectively. ``localtime`` is
4509    required for correct date in MS-DOS or Windows. To start at a
4510    specific point in time, provide datetime in the format
4511    ``2006-06-17T16:01:21`` or ``2006-06-17``. The default base is UTC.
4512
4513    By default the RTC is driven by the host system time. This allows
4514    using of the RTC as accurate reference clock inside the guest,
4515    specifically if the host time is smoothly following an accurate
4516    external reference clock, e.g. via NTP. If you want to isolate the
4517    guest time from the host, you can set ``clock`` to ``rt`` instead,
4518    which provides a host monotonic clock if host support it. To even
4519    prevent the RTC from progressing during suspension, you can set
4520    ``clock`` to ``vm`` (virtual clock). '\ ``clock=vm``\ ' is
4521    recommended especially in icount mode in order to preserve
4522    determinism; however, note that in icount mode the speed of the
4523    virtual clock is variable and can in general differ from the host
4524    clock.
4525
4526    Enable ``driftfix`` (i386 targets only) if you experience time drift
4527    problems, specifically with Windows' ACPI HAL. This option will try
4528    to figure out how many timer interrupts were not processed by the
4529    Windows guest and will re-inject them.
4530ERST
4531
4532DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
4533    "-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]\n" \
4534    "                enable virtual instruction counter with 2^N clock ticks per\n" \
4535    "                instruction, enable aligning the host and virtual clocks\n" \
4536    "                or disable real time cpu sleeping, and optionally enable\n" \
4537    "                record-and-replay mode\n", QEMU_ARCH_ALL)
4538SRST
4539``-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=filename[,rrsnapshot=snapshot]]``
4540    Enable virtual instruction counter. The virtual cpu will execute one
4541    instruction every 2^N ns of virtual time. If ``auto`` is specified
4542    then the virtual cpu speed will be automatically adjusted to keep
4543    virtual time within a few seconds of real time.
4544
4545    Note that while this option can give deterministic behavior, it does
4546    not provide cycle accurate emulation. Modern CPUs contain
4547    superscalar out of order cores with complex cache hierarchies. The
4548    number of instructions executed often has little or no correlation
4549    with actual performance.
4550
4551    When the virtual cpu is sleeping, the virtual time will advance at
4552    default speed unless ``sleep=on`` is specified. With
4553    ``sleep=on``, the virtual time will jump to the next timer
4554    deadline instantly whenever the virtual cpu goes to sleep mode and
4555    will not advance if no timer is enabled. This behavior gives
4556    deterministic execution times from the guest point of view.
4557    The default if icount is enabled is ``sleep=off``.
4558    ``sleep=on`` cannot be used together with either ``shift=auto``
4559    or ``align=on``.
4560
4561    ``align=on`` will activate the delay algorithm which will try to
4562    synchronise the host clock and the virtual clock. The goal is to
4563    have a guest running at the real frequency imposed by the shift
4564    option. Whenever the guest clock is behind the host clock and if
4565    ``align=on`` is specified then we print a message to the user to
4566    inform about the delay. Currently this option does not work when
4567    ``shift`` is ``auto``. Note: The sync algorithm will work for those
4568    shift values for which the guest clock runs ahead of the host clock.
4569    Typically this happens when the shift value is high (how high
4570    depends on the host machine). The default if icount is enabled
4571    is ``align=off``.
4572
4573    When the ``rr`` option is specified deterministic record/replay is
4574    enabled. The ``rrfile=`` option must also be provided to
4575    specify the path to the replay log. In record mode data is written
4576    to this file, and in replay mode it is read back.
4577    If the ``rrsnapshot`` option is given then it specifies a VM snapshot
4578    name. In record mode, a new VM snapshot with the given name is created
4579    at the start of execution recording. In replay mode this option
4580    specifies the snapshot name used to load the initial VM state.
4581ERST
4582
4583DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
4584    "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
4585    "                action when watchdog fires [default=reset]\n",
4586    QEMU_ARCH_ALL)
4587SRST
4588``-watchdog-action action``
4589    The action controls what QEMU will do when the watchdog timer
4590    expires. The default is ``reset`` (forcefully reset the guest).
4591    Other possible actions are: ``shutdown`` (attempt to gracefully
4592    shutdown the guest), ``poweroff`` (forcefully poweroff the guest),
4593    ``inject-nmi`` (inject a NMI into the guest), ``pause`` (pause the
4594    guest), ``debug`` (print a debug message and continue), or ``none``
4595    (do nothing).
4596
4597    Note that the ``shutdown`` action requires that the guest responds
4598    to ACPI signals, which it may not be able to do in the sort of
4599    situations where the watchdog would have expired, and thus
4600    ``-watchdog-action shutdown`` is not recommended for production use.
4601
4602    Examples:
4603
4604    ``-device i6300esb -watchdog-action pause``
4605
4606ERST
4607
4608DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
4609    "-echr chr       set terminal escape character instead of ctrl-a\n",
4610    QEMU_ARCH_ALL)
4611SRST
4612``-echr numeric_ascii_value``
4613    Change the escape character used for switching to the monitor when
4614    using monitor and serial sharing. The default is ``0x01`` when using
4615    the ``-nographic`` option. ``0x01`` is equal to pressing
4616    ``Control-a``. You can select a different character from the ascii
4617    control keys where 1 through 26 map to Control-a through Control-z.
4618    For instance you could use the either of the following to change the
4619    escape character to Control-t.
4620
4621    ``-echr 0x14``; \ ``-echr 20``
4622
4623ERST
4624
4625DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
4626    "-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]\n" \
4627    "-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]\n" \
4628    "-incoming unix:socketpath\n" \
4629    "                prepare for incoming migration, listen on\n" \
4630    "                specified protocol and socket address\n" \
4631    "-incoming fd:fd\n" \
4632    "-incoming exec:cmdline\n" \
4633    "                accept incoming migration on given file descriptor\n" \
4634    "                or from given external command\n" \
4635    "-incoming defer\n" \
4636    "                wait for the URI to be specified via migrate_incoming\n",
4637    QEMU_ARCH_ALL)
4638SRST
4639``-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]``
4640  \
4641``-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]``
4642    Prepare for incoming migration, listen on a given tcp port.
4643
4644``-incoming unix:socketpath``
4645    Prepare for incoming migration, listen on a given unix socket.
4646
4647``-incoming fd:fd``
4648    Accept incoming migration from a given filedescriptor.
4649
4650``-incoming exec:cmdline``
4651    Accept incoming migration as an output from specified external
4652    command.
4653
4654``-incoming defer``
4655    Wait for the URI to be specified via migrate\_incoming. The monitor
4656    can be used to change settings (such as migration parameters) prior
4657    to issuing the migrate\_incoming to allow the migration to begin.
4658ERST
4659
4660DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
4661    "-only-migratable     allow only migratable devices\n", QEMU_ARCH_ALL)
4662SRST
4663``-only-migratable``
4664    Only allow migratable devices. Devices will not be allowed to enter
4665    an unmigratable state.
4666ERST
4667
4668DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
4669    "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
4670SRST
4671``-nodefaults``
4672    Don't create default devices. Normally, QEMU sets the default
4673    devices like serial port, parallel port, virtual console, monitor
4674    device, VGA adapter, floppy and CD-ROM drive and others. The
4675    ``-nodefaults`` option will disable all those default devices.
4676ERST
4677
4678#ifndef _WIN32
4679DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
4680    "-chroot dir     chroot to dir just before starting the VM\n",
4681    QEMU_ARCH_ALL)
4682#endif
4683SRST
4684``-chroot dir``
4685    Immediately before starting guest execution, chroot to the specified
4686    directory. Especially useful in combination with -runas.
4687ERST
4688
4689#ifndef _WIN32
4690DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
4691    "-runas user     change to user id user just before starting the VM\n" \
4692    "                user can be numeric uid:gid instead\n",
4693    QEMU_ARCH_ALL)
4694#endif
4695SRST
4696``-runas user``
4697    Immediately before starting guest execution, drop root privileges,
4698    switching to the specified user.
4699ERST
4700
4701DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
4702    "-prom-env variable=value\n"
4703    "                set OpenBIOS nvram variables\n",
4704    QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
4705SRST
4706``-prom-env variable=value``
4707    Set OpenBIOS nvram variable to given value (PPC, SPARC only).
4708
4709    ::
4710
4711        qemu-system-sparc -prom-env 'auto-boot?=false' \
4712         -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
4713
4714    ::
4715
4716        qemu-system-ppc -prom-env 'auto-boot?=false' \
4717         -prom-env 'boot-device=hd:2,\yaboot' \
4718         -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
4719ERST
4720DEF("semihosting", 0, QEMU_OPTION_semihosting,
4721    "-semihosting    semihosting mode\n",
4722    QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
4723    QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
4724SRST
4725``-semihosting``
4726    Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
4727
4728    .. warning::
4729      Note that this allows guest direct access to the host filesystem, so
4730      should only be used with a trusted guest OS.
4731
4732    See the -semihosting-config option documentation for further
4733    information about the facilities this enables.
4734ERST
4735DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
4736    "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]\n" \
4737    "                semihosting configuration\n",
4738QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
4739QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
4740SRST
4741``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]``
4742    Enable and configure :ref:`Semihosting` (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
4743    only).
4744
4745    .. warning::
4746      Note that this allows guest direct access to the host filesystem, so
4747      should only be used with a trusted guest OS.
4748
4749    ``target=native|gdb|auto``
4750        Defines where the semihosting calls will be addressed, to QEMU
4751        (``native``) or to GDB (``gdb``). The default is ``auto``, which
4752        means ``gdb`` during debug sessions and ``native`` otherwise.
4753
4754    ``chardev=str1``
4755        Send the output to a chardev backend output for native or auto
4756        output when not in gdb
4757
4758    ``userspace=on|off``
4759        Allows code running in guest userspace to access the semihosting
4760        interface. The default is that only privileged guest code can
4761        make semihosting calls. Note that setting ``userspace=on`` should
4762        only be used if all guest code is trusted (for example, in
4763        bare-metal test case code).
4764
4765    ``arg=str1,arg=str2,...``
4766        Allows the user to pass input arguments, and can be used
4767        multiple times to build up a list. The old-style
4768        ``-kernel``/``-append`` method of passing a command line is
4769        still supported for backward compatibility. If both the
4770        ``--semihosting-config arg`` and the ``-kernel``/``-append`` are
4771        specified, the former is passed to semihosting as it always
4772        takes precedence.
4773ERST
4774DEF("old-param", 0, QEMU_OPTION_old_param,
4775    "-old-param      old param mode\n", QEMU_ARCH_ARM)
4776SRST
4777``-old-param``
4778    Old param mode (ARM only).
4779ERST
4780
4781DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
4782    "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
4783    "          [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
4784    "                Enable seccomp mode 2 system call filter (default 'off').\n" \
4785    "                use 'obsolete' to allow obsolete system calls that are provided\n" \
4786    "                    by the kernel, but typically no longer used by modern\n" \
4787    "                    C library implementations.\n" \
4788    "                use 'elevateprivileges' to allow or deny the QEMU process ability\n" \
4789    "                    to elevate privileges using set*uid|gid system calls.\n" \
4790    "                    The value 'children' will deny set*uid|gid system calls for\n" \
4791    "                    main QEMU process but will allow forks and execves to run unprivileged\n" \
4792    "                use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
4793    "                     blocking *fork and execve\n" \
4794    "                use 'resourcecontrol' to disable process affinity and schedular priority\n",
4795    QEMU_ARCH_ALL)
4796SRST
4797``-sandbox arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]``
4798    Enable Seccomp mode 2 system call filter. 'on' will enable syscall
4799    filtering and 'off' will disable it. The default is 'off'.
4800
4801    ``obsolete=string``
4802        Enable Obsolete system calls
4803
4804    ``elevateprivileges=string``
4805        Disable set\*uid\|gid system calls
4806
4807    ``spawn=string``
4808        Disable \*fork and execve
4809
4810    ``resourcecontrol=string``
4811        Disable process affinity and schedular priority
4812ERST
4813
4814DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
4815    "-readconfig <file>\n"
4816    "                read config file\n", QEMU_ARCH_ALL)
4817SRST
4818``-readconfig file``
4819    Read device configuration from file. This approach is useful when
4820    you want to spawn QEMU process with many command line options but
4821    you don't want to exceed the command line character limit.
4822ERST
4823
4824DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
4825    "-no-user-config\n"
4826    "                do not load default user-provided config files at startup\n",
4827    QEMU_ARCH_ALL)
4828SRST
4829``-no-user-config``
4830    The ``-no-user-config`` option makes QEMU not load any of the
4831    user-provided config files on sysconfdir.
4832ERST
4833
4834DEF("trace", HAS_ARG, QEMU_OPTION_trace,
4835    "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
4836    "                specify tracing options\n",
4837    QEMU_ARCH_ALL)
4838SRST
4839``-trace [[enable=]pattern][,events=file][,file=file]``
4840  .. include:: ../qemu-option-trace.rst.inc
4841
4842ERST
4843DEF("plugin", HAS_ARG, QEMU_OPTION_plugin,
4844    "-plugin [file=]<file>[,<argname>=<argvalue>]\n"
4845    "                load a plugin\n",
4846    QEMU_ARCH_ALL)
4847SRST
4848``-plugin file=file[,argname=argvalue]``
4849    Load a plugin.
4850
4851    ``file=file``
4852        Load the given plugin from a shared library file.
4853
4854    ``argname=argvalue``
4855        Argument passed to the plugin. (Can be given multiple times.)
4856ERST
4857
4858HXCOMM Internal use
4859DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
4860DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
4861
4862#ifdef __linux__
4863DEF("async-teardown", 0, QEMU_OPTION_asyncteardown,
4864    "-async-teardown enable asynchronous teardown\n",
4865    QEMU_ARCH_ALL)
4866SRST
4867``-async-teardown``
4868    This option is deprecated and should no longer be used. The new option
4869    ``-run-with async-teardown=on`` is a replacement.
4870ERST
4871DEF("run-with", HAS_ARG, QEMU_OPTION_run_with,
4872    "-run-with async-teardown[=on|off]\n"
4873    "                misc QEMU process lifecycle options\n"
4874    "                async-teardown=on enables asynchronous teardown\n",
4875    QEMU_ARCH_ALL)
4876SRST
4877``-run-with``
4878    Set QEMU process lifecycle options.
4879
4880    ``async-teardown=on`` enables asynchronous teardown. A new process called
4881    "cleanup/<QEMU_PID>" will be created at startup sharing the address
4882    space with the main QEMU process, using clone. It will wait for the
4883    main QEMU process to terminate completely, and then exit. This allows
4884    QEMU to terminate very quickly even if the guest was huge, leaving the
4885    teardown of the address space to the cleanup process. Since the cleanup
4886    process shares the same cgroups as the main QEMU process, accounting is
4887    performed correctly. This only works if the cleanup process is not
4888    forcefully killed with SIGKILL before the main QEMU process has
4889    terminated completely.
4890ERST
4891#endif
4892
4893DEF("msg", HAS_ARG, QEMU_OPTION_msg,
4894    "-msg [timestamp[=on|off]][,guest-name=[on|off]]\n"
4895    "                control error message format\n"
4896    "                timestamp=on enables timestamps (default: off)\n"
4897    "                guest-name=on enables guest name prefix but only if\n"
4898    "                              -name guest option is set (default: off)\n",
4899    QEMU_ARCH_ALL)
4900SRST
4901``-msg [timestamp[=on|off]][,guest-name[=on|off]]``
4902    Control error message format.
4903
4904    ``timestamp=on|off``
4905        Prefix messages with a timestamp. Default is off.
4906
4907    ``guest-name=on|off``
4908        Prefix messages with guest name but only if -name guest option is set
4909        otherwise the option is ignored. Default is off.
4910ERST
4911
4912DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
4913    "-dump-vmstate <file>\n"
4914    "                Output vmstate information in JSON format to file.\n"
4915    "                Use the scripts/vmstate-static-checker.py file to\n"
4916    "                check for possible regressions in migration code\n"
4917    "                by comparing two such vmstate dumps.\n",
4918    QEMU_ARCH_ALL)
4919SRST
4920``-dump-vmstate file``
4921    Dump json-encoded vmstate information for current machine type to
4922    file in file
4923ERST
4924
4925DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
4926    "-enable-sync-profile\n"
4927    "                enable synchronization profiling\n",
4928    QEMU_ARCH_ALL)
4929SRST
4930``-enable-sync-profile``
4931    Enable synchronization profiling.
4932ERST
4933
4934#if defined(CONFIG_TCG) && defined(CONFIG_LINUX)
4935DEF("perfmap", 0, QEMU_OPTION_perfmap,
4936    "-perfmap        generate a /tmp/perf-${pid}.map file for perf\n",
4937    QEMU_ARCH_ALL)
4938SRST
4939``-perfmap``
4940    Generate a map file for Linux perf tools that will allow basic profiling
4941    information to be broken down into basic blocks.
4942ERST
4943
4944DEF("jitdump", 0, QEMU_OPTION_jitdump,
4945    "-jitdump        generate a jit-${pid}.dump file for perf\n",
4946    QEMU_ARCH_ALL)
4947SRST
4948``-jitdump``
4949    Generate a dump file for Linux perf tools that maps basic blocks to symbol
4950    names, line numbers and JITted code.
4951ERST
4952#endif
4953
4954DEFHEADING()
4955
4956DEFHEADING(Generic object creation:)
4957
4958DEF("object", HAS_ARG, QEMU_OPTION_object,
4959    "-object TYPENAME[,PROP1=VALUE1,...]\n"
4960    "                create a new object of type TYPENAME setting properties\n"
4961    "                in the order they are specified.  Note that the 'id'\n"
4962    "                property must be set.  These objects are placed in the\n"
4963    "                '/objects' path.\n",
4964    QEMU_ARCH_ALL)
4965SRST
4966``-object typename[,prop1=value1,...]``
4967    Create a new object of type typename setting properties in the order
4968    they are specified. Note that the 'id' property must be set. These
4969    objects are placed in the '/objects' path.
4970
4971    ``-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,offset=offset,readonly=on|off``
4972        Creates a memory file backend object, which can be used to back
4973        the guest RAM with huge pages.
4974
4975        The ``id`` parameter is a unique ID that will be used to
4976        reference this memory region in other parameters, e.g. ``-numa``,
4977        ``-device nvdimm``, etc.
4978
4979        The ``size`` option provides the size of the memory region, and
4980        accepts common suffixes, e.g. ``500M``.
4981
4982        The ``mem-path`` provides the path to either a shared memory or
4983        huge page filesystem mount.
4984
4985        The ``share`` boolean option determines whether the memory
4986        region is marked as private to QEMU, or shared. The latter
4987        allows a co-operating external process to access the QEMU memory
4988        region.
4989
4990        The ``share`` is also required for pvrdma devices due to
4991        limitations in the RDMA API provided by Linux.
4992
4993        Setting share=on might affect the ability to configure NUMA
4994        bindings for the memory backend under some circumstances, see
4995        Documentation/vm/numa\_memory\_policy.txt on the Linux kernel
4996        source tree for additional details.
4997
4998        Setting the ``discard-data`` boolean option to on indicates that
4999        file contents can be destroyed when QEMU exits, to avoid
5000        unnecessarily flushing data to the backing file. Note that
5001        ``discard-data`` is only an optimization, and QEMU might not
5002        discard file contents if it aborts unexpectedly or is terminated
5003        using SIGKILL.
5004
5005        The ``merge`` boolean option enables memory merge, also known as
5006        MADV\_MERGEABLE, so that Kernel Samepage Merging will consider
5007        the pages for memory deduplication.
5008
5009        Setting the ``dump`` boolean option to off excludes the memory
5010        from core dumps. This feature is also known as MADV\_DONTDUMP.
5011
5012        The ``prealloc`` boolean option enables memory preallocation.
5013
5014        The ``host-nodes`` option binds the memory range to a list of
5015        NUMA host nodes.
5016
5017        The ``policy`` option sets the NUMA policy to one of the
5018        following values:
5019
5020        ``default``
5021            default host policy
5022
5023        ``preferred``
5024            prefer the given host node list for allocation
5025
5026        ``bind``
5027            restrict memory allocation to the given host node list
5028
5029        ``interleave``
5030            interleave memory allocations across the given host node
5031            list
5032
5033        The ``align`` option specifies the base address alignment when
5034        QEMU mmap(2) ``mem-path``, and accepts common suffixes, eg
5035        ``2M``. Some backend store specified by ``mem-path`` requires an
5036        alignment different than the default one used by QEMU, eg the
5037        device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
5038        such cases, users can specify the required alignment via this
5039        option.
5040
5041        The ``offset`` option specifies the offset into the target file
5042        that the region starts at. You can use this parameter to back
5043        multiple regions with a single file.
5044
5045        The ``pmem`` option specifies whether the backing file specified
5046        by ``mem-path`` is in host persistent memory that can be
5047        accessed using the SNIA NVM programming model (e.g. Intel
5048        NVDIMM). If ``pmem`` is set to 'on', QEMU will take necessary
5049        operations to guarantee the persistence of its own writes to
5050        ``mem-path`` (e.g. in vNVDIMM label emulation and live
5051        migration). Also, we will map the backend-file with MAP\_SYNC
5052        flag, which ensures the file metadata is in sync for
5053        ``mem-path`` in case of host crash or a power failure. MAP\_SYNC
5054        requires support from both the host kernel (since Linux kernel
5055        4.15) and the filesystem of ``mem-path`` mounted with DAX
5056        option.
5057
5058        The ``readonly`` option specifies whether the backing file is opened
5059        read-only or read-write (default).
5060
5061    ``-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``
5062        Creates a memory backend object, which can be used to back the
5063        guest RAM. Memory backend objects offer more control than the
5064        ``-m`` option that is traditionally used to define guest RAM.
5065        Please refer to ``memory-backend-file`` for a description of the
5066        options.
5067
5068    ``-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``
5069        Creates an anonymous memory file backend object, which allows
5070        QEMU to share the memory with an external process (e.g. when
5071        using vhost-user). The memory is allocated with memfd and
5072        optional sealing. (Linux only)
5073
5074        The ``seal`` option creates a sealed-file, that will block
5075        further resizing the memory ('on' by default).
5076
5077        The ``hugetlb`` option specify the file to be created resides in
5078        the hugetlbfs filesystem (since Linux 4.14). Used in conjunction
5079        with the ``hugetlb`` option, the ``hugetlbsize`` option specify
5080        the hugetlb page size on systems that support multiple hugetlb
5081        page sizes (it must be a power of 2 value supported by the
5082        system).
5083
5084        In some versions of Linux, the ``hugetlb`` option is
5085        incompatible with the ``seal`` option (requires at least Linux
5086        4.16).
5087
5088        Please refer to ``memory-backend-file`` for a description of the
5089        other options.
5090
5091        The ``share`` boolean option is on by default with memfd.
5092
5093    ``-object rng-builtin,id=id``
5094        Creates a random number generator backend which obtains entropy
5095        from QEMU builtin functions. The ``id`` parameter is a unique ID
5096        that will be used to reference this entropy backend from the
5097        ``virtio-rng`` device. By default, the ``virtio-rng`` device
5098        uses this RNG backend.
5099
5100    ``-object rng-random,id=id,filename=/dev/random``
5101        Creates a random number generator backend which obtains entropy
5102        from a device on the host. The ``id`` parameter is a unique ID
5103        that will be used to reference this entropy backend from the
5104        ``virtio-rng`` device. The ``filename`` parameter specifies
5105        which file to obtain entropy from and if omitted defaults to
5106        ``/dev/urandom``.
5107
5108    ``-object rng-egd,id=id,chardev=chardevid``
5109        Creates a random number generator backend which obtains entropy
5110        from an external daemon running on the host. The ``id``
5111        parameter is a unique ID that will be used to reference this
5112        entropy backend from the ``virtio-rng`` device. The ``chardev``
5113        parameter is the unique ID of a character device backend that
5114        provides the connection to the RNG daemon.
5115
5116    ``-object tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off``
5117        Creates a TLS anonymous credentials object, which can be used to
5118        provide TLS support on network backends. The ``id`` parameter is
5119        a unique ID which network backends will use to access the
5120        credentials. The ``endpoint`` is either ``server`` or ``client``
5121        depending on whether the QEMU network backend that uses the
5122        credentials will be acting as a client or as a server. If
5123        ``verify-peer`` is enabled (the default) then once the handshake
5124        is completed, the peer credentials will be verified, though this
5125        is a no-op for anonymous credentials.
5126
5127        The dir parameter tells QEMU where to find the credential files.
5128        For server endpoints, this directory may contain a file
5129        dh-params.pem providing diffie-hellman parameters to use for the
5130        TLS server. If the file is missing, QEMU will generate a set of
5131        DH parameters at startup. This is a computationally expensive
5132        operation that consumes random pool entropy, so it is
5133        recommended that a persistent set of parameters be generated
5134        upfront and saved.
5135
5136    ``-object tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]``
5137        Creates a TLS Pre-Shared Keys (PSK) credentials object, which
5138        can be used to provide TLS support on network backends. The
5139        ``id`` parameter is a unique ID which network backends will use
5140        to access the credentials. The ``endpoint`` is either ``server``
5141        or ``client`` depending on whether the QEMU network backend that
5142        uses the credentials will be acting as a client or as a server.
5143        For clients only, ``username`` is the username which will be
5144        sent to the server. If omitted it defaults to "qemu".
5145
5146        The dir parameter tells QEMU where to find the keys file. It is
5147        called "dir/keys.psk" and contains "username:key" pairs. This
5148        file can most easily be created using the GnuTLS ``psktool``
5149        program.
5150
5151        For server endpoints, dir may also contain a file dh-params.pem
5152        providing diffie-hellman parameters to use for the TLS server.
5153        If the file is missing, QEMU will generate a set of DH
5154        parameters at startup. This is a computationally expensive
5155        operation that consumes random pool entropy, so it is
5156        recommended that a persistent set of parameters be generated up
5157        front and saved.
5158
5159    ``-object tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id``
5160        Creates a TLS anonymous credentials object, which can be used to
5161        provide TLS support on network backends. The ``id`` parameter is
5162        a unique ID which network backends will use to access the
5163        credentials. The ``endpoint`` is either ``server`` or ``client``
5164        depending on whether the QEMU network backend that uses the
5165        credentials will be acting as a client or as a server. If
5166        ``verify-peer`` is enabled (the default) then once the handshake
5167        is completed, the peer credentials will be verified. With x509
5168        certificates, this implies that the clients must be provided
5169        with valid client certificates too.
5170
5171        The dir parameter tells QEMU where to find the credential files.
5172        For server endpoints, this directory may contain a file
5173        dh-params.pem providing diffie-hellman parameters to use for the
5174        TLS server. If the file is missing, QEMU will generate a set of
5175        DH parameters at startup. This is a computationally expensive
5176        operation that consumes random pool entropy, so it is
5177        recommended that a persistent set of parameters be generated
5178        upfront and saved.
5179
5180        For x509 certificate credentials the directory will contain
5181        further files providing the x509 certificates. The certificates
5182        must be stored in PEM format, in filenames ca-cert.pem,
5183        ca-crl.pem (optional), server-cert.pem (only servers),
5184        server-key.pem (only servers), client-cert.pem (only clients),
5185        and client-key.pem (only clients).
5186
5187        For the server-key.pem and client-key.pem files which contain
5188        sensitive private keys, it is possible to use an encrypted
5189        version by providing the passwordid parameter. This provides the
5190        ID of a previously created ``secret`` object containing the
5191        password for decryption.
5192
5193        The priority parameter allows to override the global default
5194        priority used by gnutls. This can be useful if the system
5195        administrator needs to use a weaker set of crypto priorities for
5196        QEMU without potentially forcing the weakness onto all
5197        applications. Or conversely if one wants wants a stronger
5198        default for QEMU than for all other applications, they can do
5199        this through this parameter. Its format is a gnutls priority
5200        string as described at
5201        https://gnutls.org/manual/html_node/Priority-Strings.html.
5202
5203    ``-object tls-cipher-suites,id=id,priority=priority``
5204        Creates a TLS cipher suites object, which can be used to control
5205        the TLS cipher/protocol algorithms that applications are permitted
5206        to use.
5207
5208        The ``id`` parameter is a unique ID which frontends will use to
5209        access the ordered list of permitted TLS cipher suites from the
5210        host.
5211
5212        The ``priority`` parameter allows to override the global default
5213        priority used by gnutls. This can be useful if the system
5214        administrator needs to use a weaker set of crypto priorities for
5215        QEMU without potentially forcing the weakness onto all
5216        applications. Or conversely if one wants wants a stronger
5217        default for QEMU than for all other applications, they can do
5218        this through this parameter. Its format is a gnutls priority
5219        string as described at
5220        https://gnutls.org/manual/html_node/Priority-Strings.html.
5221
5222        An example of use of this object is to control UEFI HTTPS Boot.
5223        The tls-cipher-suites object exposes the ordered list of permitted
5224        TLS cipher suites from the host side to the guest firmware, via
5225        fw_cfg. The list is represented as an array of IANA_TLS_CIPHER
5226        objects. The firmware uses the IANA_TLS_CIPHER array for configuring
5227        guest-side TLS.
5228
5229        In the following example, the priority at which the host-side policy
5230        is retrieved is given by the ``priority`` property.
5231        Given that QEMU uses GNUTLS, ``priority=@SYSTEM`` may be used to
5232        refer to /etc/crypto-policies/back-ends/gnutls.config.
5233
5234        .. parsed-literal::
5235
5236             # |qemu_system| \\
5237                 -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM \\
5238                 -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
5239
5240    ``-object filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off][,position=head|tail|id=<id>][,insert=behind|before]``
5241        Interval t can't be 0, this filter batches the packet delivery:
5242        all packets arriving in a given interval on netdev netdevid are
5243        delayed until the end of the interval. Interval is in
5244        microseconds. ``status`` is optional that indicate whether the
5245        netfilter is on (enabled) or off (disabled), the default status
5246        for netfilter will be 'on'.
5247
5248        queue all\|rx\|tx is an option that can be applied to any
5249        netfilter.
5250
5251        ``all``: the filter is attached both to the receive and the
5252        transmit queue of the netdev (default).
5253
5254        ``rx``: the filter is attached to the receive queue of the
5255        netdev, where it will receive packets sent to the netdev.
5256
5257        ``tx``: the filter is attached to the transmit queue of the
5258        netdev, where it will receive packets sent by the netdev.
5259
5260        position head\|tail\|id=<id> is an option to specify where the
5261        filter should be inserted in the filter list. It can be applied
5262        to any netfilter.
5263
5264        ``head``: the filter is inserted at the head of the filter list,
5265        before any existing filters.
5266
5267        ``tail``: the filter is inserted at the tail of the filter list,
5268        behind any existing filters (default).
5269
5270        ``id=<id>``: the filter is inserted before or behind the filter
5271        specified by <id>, see the insert option below.
5272
5273        insert behind\|before is an option to specify where to insert
5274        the new filter relative to the one specified with
5275        position=id=<id>. It can be applied to any netfilter.
5276
5277        ``before``: insert before the specified filter.
5278
5279        ``behind``: insert behind the specified filter (default).
5280
5281    ``-object filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]``
5282        filter-mirror on netdev netdevid,mirror net packet to
5283        chardevchardevid, if it has the vnet\_hdr\_support flag,
5284        filter-mirror will mirror packet with vnet\_hdr\_len.
5285
5286    ``-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]``
5287        filter-redirector on netdev netdevid,redirect filter's net
5288        packet to chardev chardevid,and redirect indev's packet to
5289        filter.if it has the vnet\_hdr\_support flag, filter-redirector
5290        will redirect packet with vnet\_hdr\_len. Create a
5291        filter-redirector we need to differ outdev id from indev id, id
5292        can not be the same. we can just use indev or outdev, but at
5293        least one of indev or outdev need to be specified.
5294
5295    ``-object filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]``
5296        Filter-rewriter is a part of COLO project.It will rewrite tcp
5297        packet to secondary from primary to keep secondary tcp
5298        connection,and rewrite tcp packet to primary from secondary make
5299        tcp packet can be handled by client.if it has the
5300        vnet\_hdr\_support flag, we can parse packet with vnet header.
5301
5302        usage: colo secondary: -object
5303        filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object
5304        filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object
5305        filter-rewriter,id=rew0,netdev=hn0,queue=all
5306
5307    ``-object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len][,position=head|tail|id=<id>][,insert=behind|before]``
5308        Dump the network traffic on netdev dev to the file specified by
5309        filename. At most len bytes (64k by default) per packet are
5310        stored. The file format is libpcap, so it can be analyzed with
5311        tools such as tcpdump or Wireshark.
5312
5313    ``-object colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id][,compare_timeout=@var{ms}][,expired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]``
5314        Colo-compare gets packet from primary\_in chardevid and
5315        secondary\_in, then compare whether the payload of primary packet
5316        and secondary packet are the same. If same, it will output
5317        primary packet to out\_dev, else it will notify COLO-framework to do
5318        checkpoint and send primary packet to out\_dev. In order to
5319        improve efficiency, we need to put the task of comparison in
5320        another iothread. If it has the vnet\_hdr\_support flag,
5321        colo compare will send/recv packet with vnet\_hdr\_len.
5322        The compare\_timeout=@var{ms} determines the maximum time of the
5323        colo-compare hold the packet. The expired\_scan\_cycle=@var{ms}
5324        is to set the period of scanning expired primary node network packets.
5325        The max\_queue\_size=@var{size} is to set the max compare queue
5326        size depend on user environment.
5327        If user want to use Xen COLO, need to add the notify\_dev to
5328        notify Xen colo-frame to do checkpoint.
5329
5330        COLO-compare must be used with the help of filter-mirror,
5331        filter-redirector and filter-rewriter.
5332
5333        ::
5334
5335            KVM COLO
5336
5337            primary:
5338            -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
5339            -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
5340            -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
5341            -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off
5342            -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off
5343            -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
5344            -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off
5345            -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
5346            -object iothread,id=iothread1
5347            -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
5348            -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
5349            -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
5350            -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
5351
5352            secondary:
5353            -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
5354            -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
5355            -chardev socket,id=red0,host=3.3.3.3,port=9003
5356            -chardev socket,id=red1,host=3.3.3.3,port=9004
5357            -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
5358            -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
5359
5360
5361            Xen COLO
5362
5363            primary:
5364            -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
5365            -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
5366            -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
5367            -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off
5368            -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off
5369            -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
5370            -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off
5371            -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
5372            -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server=on,wait=off
5373            -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
5374            -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
5375            -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
5376            -object iothread,id=iothread1
5377            -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
5378
5379            secondary:
5380            -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
5381            -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
5382            -chardev socket,id=red0,host=3.3.3.3,port=9003
5383            -chardev socket,id=red1,host=3.3.3.3,port=9004
5384            -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
5385            -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
5386
5387        If you want to know the detail of above command line, you can
5388        read the colo-compare git log.
5389
5390    ``-object cryptodev-backend-builtin,id=id[,queues=queues]``
5391        Creates a cryptodev backend which executes crypto operations from
5392        the QEMU cipher APIs. The id parameter is a unique ID that will
5393        be used to reference this cryptodev backend from the
5394        ``virtio-crypto`` device. The queues parameter is optional,
5395        which specify the queue number of cryptodev backend, the default
5396        of queues is 1.
5397
5398        .. parsed-literal::
5399
5400             # |qemu_system| \\
5401               [...] \\
5402                   -object cryptodev-backend-builtin,id=cryptodev0 \\
5403                   -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \\
5404               [...]
5405
5406    ``-object cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]``
5407        Creates a vhost-user cryptodev backend, backed by a chardev
5408        chardevid. The id parameter is a unique ID that will be used to
5409        reference this cryptodev backend from the ``virtio-crypto``
5410        device. The chardev should be a unix domain socket backed one.
5411        The vhost-user uses a specifically defined protocol to pass
5412        vhost ioctl replacement messages to an application on the other
5413        end of the socket. The queues parameter is optional, which
5414        specify the queue number of cryptodev backend for multiqueue
5415        vhost-user, the default of queues is 1.
5416
5417        .. parsed-literal::
5418
5419             # |qemu_system| \\
5420               [...] \\
5421                   -chardev socket,id=chardev0,path=/path/to/socket \\
5422                   -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \\
5423                   -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \\
5424               [...]
5425
5426    ``-object secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]``
5427      \
5428    ``-object secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]``
5429        Defines a secret to store a password, encryption key, or some
5430        other sensitive data. The sensitive data can either be passed
5431        directly via the data parameter, or indirectly via the file
5432        parameter. Using the data parameter is insecure unless the
5433        sensitive data is encrypted.
5434
5435        The sensitive data can be provided in raw format (the default),
5436        or base64. When encoded as JSON, the raw format only supports
5437        valid UTF-8 characters, so base64 is recommended for sending
5438        binary data. QEMU will convert from which ever format is
5439        provided to the format it needs internally. eg, an RBD password
5440        can be provided in raw format, even though it will be base64
5441        encoded when passed onto the RBD sever.
5442
5443        For added protection, it is possible to encrypt the data
5444        associated with a secret using the AES-256-CBC cipher. Use of
5445        encryption is indicated by providing the keyid and iv
5446        parameters. The keyid parameter provides the ID of a previously
5447        defined secret that contains the AES-256 decryption key. This
5448        key should be 32-bytes long and be base64 encoded. The iv
5449        parameter provides the random initialization vector used for
5450        encryption of this particular secret and should be a base64
5451        encrypted string of the 16-byte IV.
5452
5453        The simplest (insecure) usage is to provide the secret inline
5454
5455        .. parsed-literal::
5456
5457             # |qemu_system| -object secret,id=sec0,data=letmein,format=raw
5458
5459        The simplest secure usage is to provide the secret via a file
5460
5461        # printf "letmein" > mypasswd.txt # QEMU\_SYSTEM\_MACRO -object
5462        secret,id=sec0,file=mypasswd.txt,format=raw
5463
5464        For greater security, AES-256-CBC should be used. To illustrate
5465        usage, consider the openssl command line tool which can encrypt
5466        the data. Note that when encrypting, the plaintext must be
5467        padded to the cipher block size (32 bytes) using the standard
5468        PKCS#5/6 compatible padding algorithm.
5469
5470        First a master key needs to be created in base64 encoding:
5471
5472        ::
5473
5474             # openssl rand -base64 32 > key.b64
5475             # KEY=$(base64 -d key.b64 | hexdump  -v -e '/1 "%02X"')
5476
5477        Each secret to be encrypted needs to have a random
5478        initialization vector generated. These do not need to be kept
5479        secret
5480
5481        ::
5482
5483             # openssl rand -base64 16 > iv.b64
5484             # IV=$(base64 -d iv.b64 | hexdump  -v -e '/1 "%02X"')
5485
5486        The secret to be defined can now be encrypted, in this case
5487        we're telling openssl to base64 encode the result, but it could
5488        be left as raw bytes if desired.
5489
5490        ::
5491
5492             # SECRET=$(printf "letmein" |
5493                        openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
5494
5495        When launching QEMU, create a master secret pointing to
5496        ``key.b64`` and specify that to be used to decrypt the user
5497        password. Pass the contents of ``iv.b64`` to the second secret
5498
5499        .. parsed-literal::
5500
5501             # |qemu_system| \\
5502                 -object secret,id=secmaster0,format=base64,file=key.b64 \\
5503                 -object secret,id=sec0,keyid=secmaster0,format=base64,\\
5504                     data=$SECRET,iv=$(<iv.b64)
5505
5506    ``-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,kernel-hashes=on|off]``
5507        Create a Secure Encrypted Virtualization (SEV) guest object,
5508        which can be used to provide the guest memory encryption support
5509        on AMD processors.
5510
5511        When memory encryption is enabled, one of the physical address
5512        bit (aka the C-bit) is utilized to mark if a memory page is
5513        protected. The ``cbitpos`` is used to provide the C-bit
5514        position. The C-bit position is Host family dependent hence user
5515        must provide this value. On EPYC, the value should be 47.
5516
5517        When memory encryption is enabled, we loose certain bits in
5518        physical address space. The ``reduced-phys-bits`` is used to
5519        provide the number of bits we loose in physical address space.
5520        Similar to C-bit, the value is Host family dependent. On EPYC,
5521        a guest will lose a maximum of 1 bit, so the value should be 1.
5522
5523        The ``sev-device`` provides the device file to use for
5524        communicating with the SEV firmware running inside AMD Secure
5525        Processor. The default device is '/dev/sev'. If hardware
5526        supports memory encryption then /dev/sev devices are created by
5527        CCP driver.
5528
5529        The ``policy`` provides the guest policy to be enforced by the
5530        SEV firmware and restrict what configuration and operational
5531        commands can be performed on this guest by the hypervisor. The
5532        policy should be provided by the guest owner and is bound to the
5533        guest and cannot be changed throughout the lifetime of the
5534        guest. The default is 0.
5535
5536        If guest ``policy`` allows sharing the key with another SEV
5537        guest then ``handle`` can be use to provide handle of the guest
5538        from which to share the key.
5539
5540        The ``dh-cert-file`` and ``session-file`` provides the guest
5541        owner's Public Diffie-Hillman key defined in SEV spec. The PDH
5542        and session parameters are used for establishing a cryptographic
5543        session with the guest owner to negotiate keys used for
5544        attestation. The file must be encoded in base64.
5545
5546        The ``kernel-hashes`` adds the hashes of given kernel/initrd/
5547        cmdline to a designated guest firmware page for measured Linux
5548        boot with -kernel. The default is off. (Since 6.2)
5549
5550        e.g to launch a SEV guest
5551
5552        .. parsed-literal::
5553
5554             # |qemu_system_x86| \\
5555                 ...... \\
5556                 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \\
5557                 -machine ...,memory-encryption=sev0 \\
5558                 .....
5559
5560    ``-object authz-simple,id=id,identity=string``
5561        Create an authorization object that will control access to
5562        network services.
5563
5564        The ``identity`` parameter is identifies the user and its format
5565        depends on the network service that authorization object is
5566        associated with. For authorizing based on TLS x509 certificates,
5567        the identity must be the x509 distinguished name. Note that care
5568        must be taken to escape any commas in the distinguished name.
5569
5570        An example authorization object to validate a x509 distinguished
5571        name would look like:
5572
5573        .. parsed-literal::
5574
5575             # |qemu_system| \\
5576                 ... \\
5577                 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \\
5578                 ...
5579
5580        Note the use of quotes due to the x509 distinguished name
5581        containing whitespace, and escaping of ','.
5582
5583    ``-object authz-listfile,id=id,filename=path,refresh=on|off``
5584        Create an authorization object that will control access to
5585        network services.
5586
5587        The ``filename`` parameter is the fully qualified path to a file
5588        containing the access control list rules in JSON format.
5589
5590        An example set of rules that match against SASL usernames might
5591        look like:
5592
5593        ::
5594
5595              {
5596                "rules": [
5597                   { "match": "fred", "policy": "allow", "format": "exact" },
5598                   { "match": "bob", "policy": "allow", "format": "exact" },
5599                   { "match": "danb", "policy": "deny", "format": "glob" },
5600                   { "match": "dan*", "policy": "allow", "format": "exact" },
5601                ],
5602                "policy": "deny"
5603              }
5604
5605        When checking access the object will iterate over all the rules
5606        and the first rule to match will have its ``policy`` value
5607        returned as the result. If no rules match, then the default
5608        ``policy`` value is returned.
5609
5610        The rules can either be an exact string match, or they can use
5611        the simple UNIX glob pattern matching to allow wildcards to be
5612        used.
5613
5614        If ``refresh`` is set to true the file will be monitored and
5615        automatically reloaded whenever its content changes.
5616
5617        As with the ``authz-simple`` object, the format of the identity
5618        strings being matched depends on the network service, but is
5619        usually a TLS x509 distinguished name, or a SASL username.
5620
5621        An example authorization object to validate a SASL username
5622        would look like:
5623
5624        .. parsed-literal::
5625
5626             # |qemu_system| \\
5627                 ... \\
5628                 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=on \\
5629                 ...
5630
5631    ``-object authz-pam,id=id,service=string``
5632        Create an authorization object that will control access to
5633        network services.
5634
5635        The ``service`` parameter provides the name of a PAM service to
5636        use for authorization. It requires that a file
5637        ``/etc/pam.d/service`` exist to provide the configuration for
5638        the ``account`` subsystem.
5639
5640        An example authorization object to validate a TLS x509
5641        distinguished name would look like:
5642
5643        .. parsed-literal::
5644
5645             # |qemu_system| \\
5646                 ... \\
5647                 -object authz-pam,id=auth0,service=qemu-vnc \\
5648                 ...
5649
5650        There would then be a corresponding config file for PAM at
5651        ``/etc/pam.d/qemu-vnc`` that contains:
5652
5653        ::
5654
5655            account requisite  pam_listfile.so item=user sense=allow \
5656                       file=/etc/qemu/vnc.allow
5657
5658        Finally the ``/etc/qemu/vnc.allow`` file would contain the list
5659        of x509 distinguished names that are permitted access
5660
5661        ::
5662
5663            CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
5664
5665    ``-object iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink,aio-max-batch=aio-max-batch``
5666        Creates a dedicated event loop thread that devices can be
5667        assigned to. This is known as an IOThread. By default device
5668        emulation happens in vCPU threads or the main event loop thread.
5669        This can become a scalability bottleneck. IOThreads allow device
5670        emulation and I/O to run on other host CPUs.
5671
5672        The ``id`` parameter is a unique ID that will be used to
5673        reference this IOThread from ``-device ...,iothread=id``.
5674        Multiple devices can be assigned to an IOThread. Note that not
5675        all devices support an ``iothread`` parameter.
5676
5677        The ``query-iothreads`` QMP command lists IOThreads and reports
5678        their thread IDs so that the user can configure host CPU
5679        pinning/affinity.
5680
5681        IOThreads use an adaptive polling algorithm to reduce event loop
5682        latency. Instead of entering a blocking system call to monitor
5683        file descriptors and then pay the cost of being woken up when an
5684        event occurs, the polling algorithm spins waiting for events for
5685        a short time. The algorithm's default parameters are suitable
5686        for many cases but can be adjusted based on knowledge of the
5687        workload and/or host device latency.
5688
5689        The ``poll-max-ns`` parameter is the maximum number of
5690        nanoseconds to busy wait for events. Polling can be disabled by
5691        setting this value to 0.
5692
5693        The ``poll-grow`` parameter is the multiplier used to increase
5694        the polling time when the algorithm detects it is missing events
5695        due to not polling long enough.
5696
5697        The ``poll-shrink`` parameter is the divisor used to decrease
5698        the polling time when the algorithm detects it is spending too
5699        long polling without encountering events.
5700
5701        The ``aio-max-batch`` parameter is the maximum number of requests
5702        in a batch for the AIO engine, 0 means that the engine will use
5703        its default.
5704
5705        The IOThread parameters can be modified at run-time using the
5706        ``qom-set`` command (where ``iothread1`` is the IOThread's
5707        ``id``):
5708
5709        ::
5710
5711            (qemu) qom-set /objects/iothread1 poll-max-ns 100000
5712ERST
5713
5714
5715HXCOMM This is the last statement. Insert new options before this line!
5716
5717#undef DEF
5718#undef DEFHEADING
5719#undef ARCHHEADING
5720