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