Merge remote-tracking branch 'remotes/vivier2/tags/linux-user-for-6.2-pull-request...
[qemu.git] / qemu-options.hx
1 HXCOMM Use DEFHEADING() to define headings in both help text and rST.
2 HXCOMM Text between SRST and ERST is copied to the rST version and
3 HXCOMM discarded from C version.
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
6 HXCOMM architectures.
7 HXCOMM HXCOMM can be used for comments, discarded from both rST and C.
8
9 DEFHEADING(Standard options:)
10
11 DEF("help", 0, QEMU_OPTION_h,
12     "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
13 SRST
14 ``-h``
15     Display help and exit
16 ERST
17
18 DEF("version", 0, QEMU_OPTION_version,
19     "-version        display version information and exit\n", QEMU_ARCH_ALL)
20 SRST
21 ``-version``
22     Display version information and exit
23 ERST
24
25 DEF("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)
41 SRST
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         -object memory-backend-file,id=pc.ram,size=512M,mem-path=/hugetlbfs,prealloc=on,share=on
108         -machine memory-backend=pc.ram
109         -m 512M
110
111         Migration compatibility note:
112         a) as backend id one shall use value of 'default-ram-id', advertised by
113         machine type (available via ``query-machines`` QMP command), if migration
114         to/from old QEMU (<5.0) is expected.
115         b) for machine types 4.0 and older, user shall
116         use ``x-use-canonical-path-for-ramblock-id=off`` backend option
117         if migration to/from old QEMU (<5.0) is expected.
118         For example:
119         ::
120         -object memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-ramblock-id=off
121         -machine memory-backend=pc.ram
122         -m 512M
123 ERST
124
125 HXCOMM Deprecated by -machine
126 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
127
128 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
129     "-cpu cpu        select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
130 SRST
131 ``-cpu model``
132     Select CPU model (``-cpu help`` for list and additional feature
133     selection)
134 ERST
135
136 DEF("accel", HAS_ARG, QEMU_OPTION_accel,
137     "-accel [accel=]accelerator[,prop[=value][,...]]\n"
138     "                select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)\n"
139     "                igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
140     "                kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
141     "                kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
142     "                split-wx=on|off (enable TCG split w^x mapping)\n"
143     "                tb-size=n (TCG translation block cache size)\n"
144     "                dirty-ring-size=n (KVM dirty ring GFN count, default 0)\n"
145     "                thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
146 SRST
147 ``-accel name[,prop=value[,...]]``
148     This is used to enable an accelerator. Depending on the target
149     architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be available. By
150     default, tcg is used. If there is more than one accelerator
151     specified, the next one is used if the previous one fails to
152     initialize.
153
154     ``igd-passthru=on|off``
155         When Xen is in use, this option controls whether Intel
156         integrated graphics devices can be passed through to the guest
157         (default=off)
158
159     ``kernel-irqchip=on|off|split``
160         Controls KVM in-kernel irqchip support. The default is full
161         acceleration of the interrupt controllers. On x86, split irqchip
162         reduces the kernel attack surface, at a performance cost for
163         non-MSI interrupts. Disabling the in-kernel irqchip completely
164         is not recommended except for debugging purposes.
165
166     ``kvm-shadow-mem=size``
167         Defines the size of the KVM shadow MMU.
168
169     ``split-wx=on|off``
170         Controls the use of split w^x mapping for the TCG code generation
171         buffer. Some operating systems require this to be enabled, and in
172         such a case this will default on. On other operating systems, this
173         will default off, but one may enable this for testing or debugging.
174
175     ``tb-size=n``
176         Controls the size (in MiB) of the TCG translation block cache.
177
178     ``thread=single|multi``
179         Controls number of TCG threads. When the TCG is multi-threaded
180         there will be one thread per vCPU therefore taking advantage of
181         additional host cores. The default is to enable multi-threading
182         where both the back-end and front-ends support it and no
183         incompatible TCG features have been enabled (e.g.
184         icount/replay).
185
186     ``dirty-ring-size=n``
187         When the KVM accelerator is used, it controls the size of the per-vCPU
188         dirty page ring buffer (number of entries for each vCPU). It should
189         be a value that is power of two, and it should be 1024 or bigger (but
190         still less than the maximum value that the kernel supports).  4096
191         could be a good initial value if you have no idea which is the best.
192         Set this value to 0 to disable the feature.  By default, this feature
193         is disabled (dirty-ring-size=0).  When enabled, KVM will instead
194         record dirty pages in a bitmap.
195
196 ERST
197
198 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
199     "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
200     "                set the number of CPUs to 'n' [default=1]\n"
201     "                maxcpus= maximum number of total cpus, including\n"
202     "                offline CPUs for hotplug, etc\n"
203     "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"
204     "                threads= number of threads on one CPU core\n"
205     "                dies= number of CPU dies on one socket (for PC only)\n"
206     "                sockets= number of discrete sockets in the system\n",
207         QEMU_ARCH_ALL)
208 SRST
209 ``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
210     Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
211     are supported. On Sparc32 target, Linux limits the number of usable
212     CPUs to 4. For the PC target, the number of cores per die, the
213     number of threads per cores, the number of dies per packages and the
214     total number of sockets can be specified. Missing values will be
215     computed. If any on the three values is given, the total number of
216     CPUs n can be omitted. maxcpus specifies the maximum number of
217     hotpluggable CPUs.
218 ERST
219
220 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
221     "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
222     "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
223     "-numa dist,src=source,dst=destination,val=distance\n"
224     "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
225     "-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"
226     "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
227     QEMU_ARCH_ALL)
228 SRST
229 ``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
230   \ 
231 ``-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
232   \
233 ``-numa dist,src=source,dst=destination,val=distance``
234   \ 
235 ``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``
236   \ 
237 ``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
238   \ 
239 ``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
240     Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
241     distance from a source node to a destination node. Set the ACPI
242     Heterogeneous Memory Attributes for the given nodes.
243
244     Legacy VCPU assignment uses '\ ``cpus``\ ' option where firstcpu and
245     lastcpu are CPU indexes. Each '\ ``cpus``\ ' option represent a
246     contiguous range of CPU indexes (or a single VCPU if lastcpu is
247     omitted). A non-contiguous set of VCPUs can be represented by
248     providing multiple '\ ``cpus``\ ' options. If '\ ``cpus``\ ' is
249     omitted on all nodes, VCPUs are automatically split between them.
250
251     For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
252     NUMA node:
253
254     ::
255
256         -numa node,cpus=0-2,cpus=5
257
258     '\ ``cpu``\ ' option is a new alternative to '\ ``cpus``\ ' option
259     which uses '\ ``socket-id|core-id|thread-id``\ ' properties to
260     assign CPU objects to a node using topology layout properties of
261     CPU. The set of properties is machine specific, and depends on used
262     machine type/'\ ``smp``\ ' options. It could be queried with
263     '\ ``hotpluggable-cpus``\ ' monitor command. '\ ``node-id``\ '
264     property specifies node to which CPU object will be assigned, it's
265     required for node to be declared with '\ ``node``\ ' option before
266     it's used with '\ ``cpu``\ ' option.
267
268     For example:
269
270     ::
271
272         -M pc \
273         -smp 1,sockets=2,maxcpus=2 \
274         -numa node,nodeid=0 -numa node,nodeid=1 \
275         -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
276
277     Legacy '\ ``mem``\ ' assigns a given RAM amount to a node (not supported
278     for 5.1 and newer machine types). '\ ``memdev``\ ' assigns RAM from
279     a given memory backend device to a node. If '\ ``mem``\ ' and
280     '\ ``memdev``\ ' are omitted in all nodes, RAM is split equally between them.
281
282
283     '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
284     Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
285     use it.
286
287     '\ ``initiator``\ ' is an additional option that points to an
288     initiator NUMA node that has best performance (the lowest latency or
289     largest bandwidth) to this NUMA node. Note that this option can be
290     set only when the machine property 'hmat' is set to 'on'.
291
292     Following example creates a machine with 2 NUMA nodes, node 0 has
293     CPU. node 1 has only memory, and its initiator is node 0. Note that
294     because node 0 has CPU, by default the initiator of node 0 is itself
295     and must be itself.
296
297     ::
298
299         -machine hmat=on \
300         -m 2G,slots=2,maxmem=4G \
301         -object memory-backend-ram,size=1G,id=m0 \
302         -object memory-backend-ram,size=1G,id=m1 \
303         -numa node,nodeid=0,memdev=m0 \
304         -numa node,nodeid=1,memdev=m1,initiator=0 \
305         -smp 2,sockets=2,maxcpus=2  \
306         -numa cpu,node-id=0,socket-id=0 \
307         -numa cpu,node-id=0,socket-id=1
308
309     source and destination are NUMA node IDs. distance is the NUMA
310     distance from source to destination. The distance from a node to
311     itself is always 10. If any pair of nodes is given a distance, then
312     all pairs must be given distances. Although, when distances are only
313     given in one direction for each pair of nodes, then the distances in
314     the opposite directions are assumed to be the same. If, however, an
315     asymmetrical pair of distances is given for even one node pair, then
316     all node pairs must be provided distance values for both directions,
317     even when they are symmetrical. When a node is unreachable from
318     another node, set the pair's distance to 255.
319
320     Note that the -``numa`` option doesn't allocate any of the specified
321     resources, it just assigns existing resources to NUMA nodes. This
322     means that one still has to use the ``-m``, ``-smp`` options to
323     allocate RAM and VCPUs respectively.
324
325     Use '\ ``hmat-lb``\ ' to set System Locality Latency and Bandwidth
326     Information between initiator and target NUMA nodes in ACPI
327     Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can
328     create memory requests, usually it has one or more processors.
329     Target NUMA node contains addressable memory.
330
331     In '\ ``hmat-lb``\ ' option, node are NUMA node IDs. hierarchy is
332     the memory hierarchy of the target NUMA node: if hierarchy is
333     'memory', the structure represents the memory performance; if
334     hierarchy is 'first-level\|second-level\|third-level', this
335     structure represents aggregated performance of memory side caches
336     for each domain. type of 'data-type' is type of data represented by
337     this structure instance: if 'hierarchy' is 'memory', 'data-type' is
338     'access\|read\|write' latency or 'access\|read\|write' bandwidth of
339     the target memory; if 'hierarchy' is
340     'first-level\|second-level\|third-level', 'data-type' is
341     'access\|read\|write' hit latency or 'access\|read\|write' hit
342     bandwidth of the target memory side cache.
343
344     lat is latency value in nanoseconds. bw is bandwidth value, the
345     possible value and units are NUM[M\|G\|T], mean that the bandwidth
346     value are NUM byte per second (or MB/s, GB/s or TB/s depending on
347     used suffix). Note that if latency or bandwidth value is 0, means
348     the corresponding latency or bandwidth information is not provided.
349
350     In '\ ``hmat-cache``\ ' option, node-id is the NUMA-id of the memory
351     belongs. size is the size of memory side cache in bytes. level is
352     the cache level described in this structure, note that the cache
353     level 0 should not be used with '\ ``hmat-cache``\ ' option.
354     associativity is the cache associativity, the possible value is
355     'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
356     is the write policy. line is the cache Line size in bytes.
357
358     For example, the following options describe 2 NUMA nodes. Node 0 has
359     2 cpus and a ram, node 1 has only a ram. The processors in node 0
360     access memory in node 0 with access-latency 5 nanoseconds,
361     access-bandwidth is 200 MB/s; The processors in NUMA node 0 access
362     memory in NUMA node 1 with access-latency 10 nanoseconds,
363     access-bandwidth is 100 MB/s. And for memory side cache information,
364     NUMA node 0 and 1 both have 1 level memory cache, size is 10KB,
365     policy is write-back, the cache Line size is 8 bytes:
366
367     ::
368
369         -machine hmat=on \
370         -m 2G \
371         -object memory-backend-ram,size=1G,id=m0 \
372         -object memory-backend-ram,size=1G,id=m1 \
373         -smp 2 \
374         -numa node,nodeid=0,memdev=m0 \
375         -numa node,nodeid=1,memdev=m1,initiator=0 \
376         -numa cpu,node-id=0,socket-id=0 \
377         -numa cpu,node-id=0,socket-id=1 \
378         -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
379         -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
380         -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
381         -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
382         -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
383         -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
384 ERST
385
386 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
387     "-add-fd fd=fd,set=set[,opaque=opaque]\n"
388     "                Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
389 SRST
390 ``-add-fd fd=fd,set=set[,opaque=opaque]``
391     Add a file descriptor to an fd set. Valid options are:
392
393     ``fd=fd``
394         This option defines the file descriptor of which a duplicate is
395         added to fd set. The file descriptor cannot be stdin, stdout, or
396         stderr.
397
398     ``set=set``
399         This option defines the ID of the fd set to add the file
400         descriptor to.
401
402     ``opaque=opaque``
403         This option defines a free-form string that can be used to
404         describe fd.
405
406     You can open an image using pre-opened file descriptors from an fd
407     set:
408
409     .. parsed-literal::
410
411         |qemu_system| \\
412          -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \\
413          -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \\
414          -drive file=/dev/fdset/2,index=0,media=disk
415 ERST
416
417 DEF("set", HAS_ARG, QEMU_OPTION_set,
418     "-set group.id.arg=value\n"
419     "                set <arg> parameter for item <id> of type <group>\n"
420     "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
421 SRST
422 ``-set group.id.arg=value``
423     Set parameter arg for item id of type group
424 ERST
425
426 DEF("global", HAS_ARG, QEMU_OPTION_global,
427     "-global driver.property=value\n"
428     "-global driver=driver,property=property,value=value\n"
429     "                set a global default for a driver property\n",
430     QEMU_ARCH_ALL)
431 SRST
432 ``-global driver.prop=value``
433   \ 
434 ``-global driver=driver,property=property,value=value``
435     Set default value of driver's property prop to value, e.g.:
436
437     .. parsed-literal::
438
439         |qemu_system_x86| -global ide-hd.physical_block_size=4096 disk-image.img
440
441     In particular, you can use this to set driver properties for devices
442     which are created automatically by the machine model. To create a
443     device which is not created automatically and set properties on it,
444     use -``device``.
445
446     -global driver.prop=value is shorthand for -global
447     driver=driver,property=prop,value=value. The longhand syntax works
448     even when driver contains a dot.
449 ERST
450
451 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
452     "-boot [order=drives][,once=drives][,menu=on|off]\n"
453     "      [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
454     "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
455     "                'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
456     "                'sp_time': the period that splash picture last if menu=on, unit is ms\n"
457     "                'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
458     QEMU_ARCH_ALL)
459 SRST
460 ``-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]``
461     Specify boot order drives as a string of drive letters. Valid drive
462     letters depend on the target architecture. The x86 PC uses: a, b
463     (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
464     (Etherboot from network adapter 1-4), hard disk boot is the default.
465     To apply a particular boot order only on the first startup, specify
466     it via ``once``. Note that the ``order`` or ``once`` parameter
467     should not be used together with the ``bootindex`` property of
468     devices, since the firmware implementations normally do not support
469     both at the same time.
470
471     Interactive boot menus/prompts can be enabled via ``menu=on`` as far
472     as firmware/BIOS supports them. The default is non-interactive boot.
473
474     A splash picture could be passed to bios, enabling user to show it
475     as logo, when option splash=sp\_name is given and menu=on, If
476     firmware/BIOS supports them. Currently Seabios for X86 system
477     support it. limitation: The splash file could be a jpeg file or a
478     BMP file in 24 BPP format(true color). The resolution should be
479     supported by the SVGA mode, so the recommended is 320x240, 640x480,
480     800x640.
481
482     A timeout could be passed to bios, guest will pause for rb\_timeout
483     ms when boot failed, then reboot. If rb\_timeout is '-1', guest will
484     not reboot, qemu passes '-1' to bios by default. Currently Seabios
485     for X86 system support it.
486
487     Do strict boot via ``strict=on`` as far as firmware/BIOS supports
488     it. This only effects when boot priority is changed by bootindex
489     options. The default is non-strict boot.
490
491     .. parsed-literal::
492
493         # try to boot from network first, then from hard disk
494         |qemu_system_x86| -boot order=nc
495         # boot from CD-ROM first, switch back to default order after reboot
496         |qemu_system_x86| -boot once=d
497         # boot with a splash picture for 5 seconds.
498         |qemu_system_x86| -boot menu=on,splash=/root/boot.bmp,splash-time=5000
499
500     Note: The legacy format '-boot drives' is still supported but its
501     use is discouraged as it may be removed from future versions.
502 ERST
503
504 DEF("m", HAS_ARG, QEMU_OPTION_m,
505     "-m [size=]megs[,slots=n,maxmem=size]\n"
506     "                configure guest RAM\n"
507     "                size: initial amount of guest memory\n"
508     "                slots: number of hotplug slots (default: none)\n"
509     "                maxmem: maximum amount of guest memory (default: none)\n"
510     "NOTE: Some architectures might enforce a specific granularity\n",
511     QEMU_ARCH_ALL)
512 SRST
513 ``-m [size=]megs[,slots=n,maxmem=size]``
514     Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
515     Optionally, a suffix of "M" or "G" can be used to signify a value in
516     megabytes or gigabytes respectively. Optional pair slots, maxmem
517     could be used to set amount of hotpluggable memory slots and maximum
518     amount of memory. Note that maxmem must be aligned to the page size.
519
520     For example, the following command-line sets the guest startup RAM
521     size to 1GB, creates 3 slots to hotplug additional memory and sets
522     the maximum memory the guest can reach to 4GB:
523
524     .. parsed-literal::
525
526         |qemu_system| -m 1G,slots=3,maxmem=4G
527
528     If slots and maxmem are not specified, memory hotplug won't be
529     enabled and the guest startup RAM will never increase.
530 ERST
531
532 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
533     "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
534 SRST
535 ``-mem-path path``
536     Allocate guest RAM from a temporarily created file in path.
537 ERST
538
539 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
540     "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
541     QEMU_ARCH_ALL)
542 SRST
543 ``-mem-prealloc``
544     Preallocate memory when using -mem-path.
545 ERST
546
547 DEF("k", HAS_ARG, QEMU_OPTION_k,
548     "-k language     use keyboard layout (for example 'fr' for French)\n",
549     QEMU_ARCH_ALL)
550 SRST
551 ``-k language``
552     Use keyboard layout language (for example ``fr`` for French). This
553     option is only needed where it is not easy to get raw PC keycodes
554     (e.g. on Macs, with some X11 servers or with a VNC or curses
555     display). You don't normally need to use it on PC/Linux or
556     PC/Windows hosts.
557
558     The available layouts are:
559
560     ::
561
562         ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
563         da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
564         de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
565
566     The default is ``en-us``.
567 ERST
568
569
570 HXCOMM Deprecated by -audiodev
571 DEF("audio-help", 0, QEMU_OPTION_audio_help,
572     "-audio-help     show -audiodev equivalent of the currently specified audio settings\n",
573     QEMU_ARCH_ALL)
574 SRST
575 ``-audio-help``
576     Will show the -audiodev equivalent of the currently specified
577     (deprecated) environment variables.
578 ERST
579
580 DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
581     "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
582     "                specifies the audio backend to use\n"
583     "                id= identifier of the backend\n"
584     "                timer-period= timer period in microseconds\n"
585     "                in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
586     "                in|out.fixed-settings= use fixed settings for host audio\n"
587     "                in|out.frequency= frequency to use with fixed settings\n"
588     "                in|out.channels= number of channels to use with fixed settings\n"
589     "                in|out.format= sample format to use with fixed settings\n"
590     "                valid values: s8, s16, s32, u8, u16, u32, f32\n"
591     "                in|out.voices= number of voices to use\n"
592     "                in|out.buffer-length= length of buffer in microseconds\n"
593     "-audiodev none,id=id,[,prop[=value][,...]]\n"
594     "                dummy driver that discards all output\n"
595 #ifdef CONFIG_AUDIO_ALSA
596     "-audiodev alsa,id=id[,prop[=value][,...]]\n"
597     "                in|out.dev= name of the audio device to use\n"
598     "                in|out.period-length= length of period in microseconds\n"
599     "                in|out.try-poll= attempt to use poll mode\n"
600     "                threshold= threshold (in microseconds) when playback starts\n"
601 #endif
602 #ifdef CONFIG_AUDIO_COREAUDIO
603     "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
604     "                in|out.buffer-count= number of buffers\n"
605 #endif
606 #ifdef CONFIG_AUDIO_DSOUND
607     "-audiodev dsound,id=id[,prop[=value][,...]]\n"
608     "                latency= add extra latency to playback in microseconds\n"
609 #endif
610 #ifdef CONFIG_AUDIO_OSS
611     "-audiodev oss,id=id[,prop[=value][,...]]\n"
612     "                in|out.dev= path of the audio device to use\n"
613     "                in|out.buffer-count= number of buffers\n"
614     "                in|out.try-poll= attempt to use poll mode\n"
615     "                try-mmap= try using memory mapped access\n"
616     "                exclusive= open device in exclusive mode\n"
617     "                dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
618 #endif
619 #ifdef CONFIG_AUDIO_PA
620     "-audiodev pa,id=id[,prop[=value][,...]]\n"
621     "                server= PulseAudio server address\n"
622     "                in|out.name= source/sink device name\n"
623     "                in|out.latency= desired latency in microseconds\n"
624 #endif
625 #ifdef CONFIG_AUDIO_SDL
626     "-audiodev sdl,id=id[,prop[=value][,...]]\n"
627     "                in|out.buffer-count= number of buffers\n"
628 #endif
629 #ifdef CONFIG_SPICE
630     "-audiodev spice,id=id[,prop[=value][,...]]\n"
631 #endif
632     "-audiodev wav,id=id[,prop[=value][,...]]\n"
633     "                path= path of wav file to record\n",
634     QEMU_ARCH_ALL)
635 SRST
636 ``-audiodev [driver=]driver,id=id[,prop[=value][,...]]``
637     Adds a new audio backend driver identified by id. There are global
638     and driver specific properties. Some values can be set differently
639     for input and output, they're marked with ``in|out.``. You can set
640     the input's property with ``in.prop`` and the output's property with
641     ``out.prop``. For example:
642
643     ::
644
645         -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
646         -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
647
648     NOTE: parameter validation is known to be incomplete, in many cases
649     specifying an invalid option causes QEMU to print an error message
650     and continue emulation without sound.
651
652     Valid global options are:
653
654     ``id=identifier``
655         Identifies the audio backend.
656
657     ``timer-period=period``
658         Sets the timer period used by the audio subsystem in
659         microseconds. Default is 10000 (10 ms).
660
661     ``in|out.mixing-engine=on|off``
662         Use QEMU's mixing engine to mix all streams inside QEMU and
663         convert audio formats when not supported by the backend. When
664         off, fixed-settings must be off too. Note that disabling this
665         option means that the selected backend must support multiple
666         streams and the audio formats used by the virtual cards,
667         otherwise you'll get no sound. It's not recommended to disable
668         this option unless you want to use 5.1 or 7.1 audio, as mixing
669         engine only supports mono and stereo audio. Default is on.
670
671     ``in|out.fixed-settings=on|off``
672         Use fixed settings for host audio. When off, it will change
673         based on how the guest opens the sound card. In this case you
674         must not specify frequency, channels or format. Default is on.
675
676     ``in|out.frequency=frequency``
677         Specify the frequency to use when using fixed-settings. Default
678         is 44100Hz.
679
680     ``in|out.channels=channels``
681         Specify the number of channels to use when using fixed-settings.
682         Default is 2 (stereo).
683
684     ``in|out.format=format``
685         Specify the sample format to use when using fixed-settings.
686         Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``,
687         ``u32``, ``f32``. Default is ``s16``.
688
689     ``in|out.voices=voices``
690         Specify the number of voices to use. Default is 1.
691
692     ``in|out.buffer-length=usecs``
693         Sets the size of the buffer in microseconds.
694
695 ``-audiodev none,id=id[,prop[=value][,...]]``
696     Creates a dummy backend that discards all outputs. This backend has
697     no backend specific properties.
698
699 ``-audiodev alsa,id=id[,prop[=value][,...]]``
700     Creates backend using the ALSA. This backend is only available on
701     Linux.
702
703     ALSA specific options are:
704
705     ``in|out.dev=device``
706         Specify the ALSA device to use for input and/or output. Default
707         is ``default``.
708
709     ``in|out.period-length=usecs``
710         Sets the period length in microseconds.
711
712     ``in|out.try-poll=on|off``
713         Attempt to use poll mode with the device. Default is on.
714
715     ``threshold=threshold``
716         Threshold (in microseconds) when playback starts. Default is 0.
717
718 ``-audiodev coreaudio,id=id[,prop[=value][,...]]``
719     Creates a backend using Apple's Core Audio. This backend is only
720     available on Mac OS and only supports playback.
721
722     Core Audio specific options are:
723
724     ``in|out.buffer-count=count``
725         Sets the count of the buffers.
726
727 ``-audiodev dsound,id=id[,prop[=value][,...]]``
728     Creates a backend using Microsoft's DirectSound. This backend is
729     only available on Windows and only supports playback.
730
731     DirectSound specific options are:
732
733     ``latency=usecs``
734         Add extra usecs microseconds latency to playback. Default is
735         10000 (10 ms).
736
737 ``-audiodev oss,id=id[,prop[=value][,...]]``
738     Creates a backend using OSS. This backend is available on most
739     Unix-like systems.
740
741     OSS specific options are:
742
743     ``in|out.dev=device``
744         Specify the file name of the OSS device to use. Default is
745         ``/dev/dsp``.
746
747     ``in|out.buffer-count=count``
748         Sets the count of the buffers.
749
750     ``in|out.try-poll=on|of``
751         Attempt to use poll mode with the device. Default is on.
752
753     ``try-mmap=on|off``
754         Try using memory mapped device access. Default is off.
755
756     ``exclusive=on|off``
757         Open the device in exclusive mode (vmix won't work in this
758         case). Default is off.
759
760     ``dsp-policy=policy``
761         Sets the timing policy (between 0 and 10, where smaller number
762         means smaller latency but higher CPU usage). Use -1 to use
763         buffer sizes specified by ``buffer`` and ``buffer-count``. This
764         option is ignored if you do not have OSS 4. Default is 5.
765
766 ``-audiodev pa,id=id[,prop[=value][,...]]``
767     Creates a backend using PulseAudio. This backend is available on
768     most systems.
769
770     PulseAudio specific options are:
771
772     ``server=server``
773         Sets the PulseAudio server to connect to.
774
775     ``in|out.name=sink``
776         Use the specified source/sink for recording/playback.
777
778     ``in|out.latency=usecs``
779         Desired latency in microseconds. The PulseAudio server will try
780         to honor this value but actual latencies may be lower or higher.
781
782 ``-audiodev sdl,id=id[,prop[=value][,...]]``
783     Creates a backend using SDL. This backend is available on most
784     systems, but you should use your platform's native backend if
785     possible.
786
787     SDL specific options are:
788
789     ``in|out.buffer-count=count``
790         Sets the count of the buffers.
791
792 ``-audiodev spice,id=id[,prop[=value][,...]]``
793     Creates a backend that sends audio through SPICE. This backend
794     requires ``-spice`` and automatically selected in that case, so
795     usually you can ignore this option. This backend has no backend
796     specific properties.
797
798 ``-audiodev wav,id=id[,prop[=value][,...]]``
799     Creates a backend that writes audio to a WAV file.
800
801     Backend specific options are:
802
803     ``path=path``
804         Write recorded audio into the specified file. Default is
805         ``qemu.wav``.
806 ERST
807
808 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
809     "-soundhw c1,... enable audio support\n"
810     "                and only specified sound cards (comma separated list)\n"
811     "                use '-soundhw help' to get the list of supported cards\n"
812     "                use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
813 SRST
814 ``-soundhw card1[,card2,...] or -soundhw all``
815     Enable audio and selected sound hardware. Use 'help' to print all
816     available sound hardware. For example:
817
818     .. parsed-literal::
819
820         |qemu_system_x86| -soundhw sb16,adlib disk.img
821         |qemu_system_x86| -soundhw es1370 disk.img
822         |qemu_system_x86| -soundhw ac97 disk.img
823         |qemu_system_x86| -soundhw hda disk.img
824         |qemu_system_x86| -soundhw all disk.img
825         |qemu_system_x86| -soundhw help
826
827     Note that Linux's i810\_audio OSS kernel (for AC97) module might
828     require manually specifying clocking.
829
830     ::
831
832         modprobe i810_audio clocking=48000
833 ERST
834
835 DEF("device", HAS_ARG, QEMU_OPTION_device,
836     "-device driver[,prop[=value][,...]]\n"
837     "                add device (based on driver)\n"
838     "                prop=value,... sets driver properties\n"
839     "                use '-device help' to print all possible drivers\n"
840     "                use '-device driver,help' to print all possible properties\n",
841     QEMU_ARCH_ALL)
842 SRST
843 ``-device driver[,prop[=value][,...]]``
844     Add device driver. prop=value sets driver properties. Valid
845     properties depend on the driver. To get help on possible drivers and
846     properties, use ``-device help`` and ``-device driver,help``.
847
848     Some drivers are:
849
850 ``-device ipmi-bmc-sim,id=id[,prop[=value][,...]]``
851     Add an IPMI BMC. This is a simulation of a hardware management
852     interface processor that normally sits on a system. It provides a
853     watchdog and the ability to reset and power control the system. You
854     need to connect this to an IPMI interface to make it useful
855
856     The IPMI slave address to use for the BMC. The default is 0x20. This
857     address is the BMC's address on the I2C network of management
858     controllers. If you don't know what this means, it is safe to ignore
859     it.
860
861     ``id=id``
862         The BMC id for interfaces to use this device.
863
864     ``slave_addr=val``
865         Define slave address to use for the BMC. The default is 0x20.
866
867     ``sdrfile=file``
868         file containing raw Sensor Data Records (SDR) data. The default
869         is none.
870
871     ``fruareasize=val``
872         size of a Field Replaceable Unit (FRU) area. The default is
873         1024.
874
875     ``frudatafile=file``
876         file containing raw Field Replaceable Unit (FRU) inventory data.
877         The default is none.
878
879     ``guid=uuid``
880         value for the GUID for the BMC, in standard UUID format. If this
881         is set, get "Get GUID" command to the BMC will return it.
882         Otherwise "Get GUID" will return an error.
883
884 ``-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]``
885     Add a connection to an external IPMI BMC simulator. Instead of
886     locally emulating the BMC like the above item, instead connect to an
887     external entity that provides the IPMI services.
888
889     A connection is made to an external BMC simulator. If you do this,
890     it is strongly recommended that you use the "reconnect=" chardev
891     option to reconnect to the simulator if the connection is lost. Note
892     that if this is not used carefully, it can be a security issue, as
893     the interface has the ability to send resets, NMIs, and power off
894     the VM. It's best if QEMU makes a connection to an external
895     simulator running on a secure port on localhost, so neither the
896     simulator nor QEMU is exposed to any outside network.
897
898     See the "lanserv/README.vm" file in the OpenIPMI library for more
899     details on the external interface.
900
901 ``-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]``
902     Add a KCS IPMI interafce on the ISA bus. This also adds a
903     corresponding ACPI and SMBIOS entries, if appropriate.
904
905     ``bmc=id``
906         The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
907         above.
908
909     ``ioport=val``
910         Define the I/O address of the interface. The default is 0xca0
911         for KCS.
912
913     ``irq=val``
914         Define the interrupt to use. The default is 5. To disable
915         interrupts, set this to 0.
916
917 ``-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]``
918     Like the KCS interface, but defines a BT interface. The default port
919     is 0xe4 and the default interrupt is 5.
920
921 ``-device pci-ipmi-kcs,bmc=id``
922     Add a KCS IPMI interafce on the PCI bus.
923
924     ``bmc=id``
925         The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
926
927 ``-device pci-ipmi-bt,bmc=id``
928     Like the KCS interface, but defines a BT interface on the PCI bus.
929 ERST
930
931 DEF("name", HAS_ARG, QEMU_OPTION_name,
932     "-name string1[,process=string2][,debug-threads=on|off]\n"
933     "                set the name of the guest\n"
934     "                string1 sets the window title and string2 the process name\n"
935     "                When debug-threads is enabled, individual threads are given a separate name\n"
936     "                NOTE: The thread names are for debugging and not a stable API.\n",
937     QEMU_ARCH_ALL)
938 SRST
939 ``-name name``
940     Sets the name of the guest. This name will be displayed in the SDL
941     window caption. The name will also be used for the VNC server. Also
942     optionally set the top visible process name in Linux. Naming of
943     individual threads can also be enabled on Linux to aid debugging.
944 ERST
945
946 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
947     "-uuid %08x-%04x-%04x-%04x-%012x\n"
948     "                specify machine UUID\n", QEMU_ARCH_ALL)
949 SRST
950 ``-uuid uuid``
951     Set system UUID.
952 ERST
953
954 DEFHEADING()
955
956 DEFHEADING(Block device options:)
957
958 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
959     "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
960 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
961 SRST
962 ``-fda file``
963   \
964 ``-fdb file``
965     Use file as floppy disk 0/1 image (see the :ref:`disk images` chapter in
966     the System Emulation Users Guide).
967 ERST
968
969 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
970     "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
971 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
972 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
973     "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
974 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
975 SRST
976 ``-hda file``
977   \
978 ``-hdb file``
979   \ 
980 ``-hdc file``
981   \ 
982 ``-hdd file``
983     Use file as hard disk 0, 1, 2 or 3 image (see the :ref:`disk images`
984     chapter in the System Emulation Users Guide).
985 ERST
986
987 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
988     "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
989     QEMU_ARCH_ALL)
990 SRST
991 ``-cdrom file``
992     Use file as CD-ROM image (you cannot use ``-hdc`` and ``-cdrom`` at
993     the same time). You can use the host CD-ROM by using ``/dev/cdrom``
994     as filename.
995 ERST
996
997 DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
998     "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
999     "          [,cache.direct=on|off][,cache.no-flush=on|off]\n"
1000     "          [,read-only=on|off][,auto-read-only=on|off]\n"
1001     "          [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
1002     "          [,driver specific parameters...]\n"
1003     "                configure a block backend\n", QEMU_ARCH_ALL)
1004 SRST
1005 ``-blockdev option[,option[,option[,...]]]``
1006     Define a new block driver node. Some of the options apply to all
1007     block drivers, other options are only accepted for a specific block
1008     driver. See below for a list of generic options and options for the
1009     most common block drivers.
1010
1011     Options that expect a reference to another node (e.g. ``file``) can
1012     be given in two ways. Either you specify the node name of an already
1013     existing node (file=node-name), or you define a new node inline,
1014     adding options for the referenced node after a dot
1015     (file.filename=path,file.aio=native).
1016
1017     A block driver node created with ``-blockdev`` can be used for a
1018     guest device by specifying its node name for the ``drive`` property
1019     in a ``-device`` argument that defines a block device.
1020
1021     ``Valid options for any block driver node:``
1022         ``driver``
1023             Specifies the block driver to use for the given node.
1024
1025         ``node-name``
1026             This defines the name of the block driver node by which it
1027             will be referenced later. The name must be unique, i.e. it
1028             must not match the name of a different block driver node, or
1029             (if you use ``-drive`` as well) the ID of a drive.
1030
1031             If no node name is specified, it is automatically generated.
1032             The generated node name is not intended to be predictable
1033             and changes between QEMU invocations. For the top level, an
1034             explicit node name must be specified.
1035
1036         ``read-only``
1037             Open the node read-only. Guest write attempts will fail.
1038
1039             Note that some block drivers support only read-only access,
1040             either generally or in certain configurations. In this case,
1041             the default value ``read-only=off`` does not work and the
1042             option must be specified explicitly.
1043
1044         ``auto-read-only``
1045             If ``auto-read-only=on`` is set, QEMU may fall back to
1046             read-only usage even when ``read-only=off`` is requested, or
1047             even switch between modes as needed, e.g. depending on
1048             whether the image file is writable or whether a writing user
1049             is attached to the node.
1050
1051         ``force-share``
1052             Override the image locking system of QEMU by forcing the
1053             node to utilize weaker shared access for permissions where
1054             it would normally request exclusive access. When there is
1055             the potential for multiple instances to have the same file
1056             open (whether this invocation of QEMU is the first or the
1057             second instance), both instances must permit shared access
1058             for the second instance to succeed at opening the file.
1059
1060             Enabling ``force-share=on`` requires ``read-only=on``.
1061
1062         ``cache.direct``
1063             The host page cache can be avoided with ``cache.direct=on``.
1064             This will attempt to do disk IO directly to the guest's
1065             memory. QEMU may still perform an internal copy of the data.
1066
1067         ``cache.no-flush``
1068             In case you don't care about data integrity over host
1069             failures, you can use ``cache.no-flush=on``. This option
1070             tells QEMU that it never needs to write any data to the disk
1071             but can instead keep things in cache. If anything goes
1072             wrong, like your host losing power, the disk storage getting
1073             disconnected accidentally, etc. your image will most
1074             probably be rendered unusable.
1075
1076         ``discard=discard``
1077             discard is one of "ignore" (or "off") or "unmap" (or "on")
1078             and controls whether ``discard`` (also known as ``trim`` or
1079             ``unmap``) requests are ignored or passed to the filesystem.
1080             Some machine types may not support discard requests.
1081
1082         ``detect-zeroes=detect-zeroes``
1083             detect-zeroes is "off", "on" or "unmap" and enables the
1084             automatic conversion of plain zero writes by the OS to
1085             driver specific optimized zero write commands. You may even
1086             choose "unmap" if discard is set to "unmap" to allow a zero
1087             write to be converted to an ``unmap`` operation.
1088
1089     ``Driver-specific options for file``
1090         This is the protocol-level block driver for accessing regular
1091         files.
1092
1093         ``filename``
1094             The path to the image file in the local filesystem
1095
1096         ``aio``
1097             Specifies the AIO backend (threads/native/io_uring,
1098             default: threads)
1099
1100         ``locking``
1101             Specifies whether the image file is protected with Linux OFD
1102             / POSIX locks. The default is to use the Linux Open File
1103             Descriptor API if available, otherwise no lock is applied.
1104             (auto/on/off, default: auto)
1105
1106         Example:
1107
1108         ::
1109
1110             -blockdev driver=file,node-name=disk,filename=disk.img
1111
1112     ``Driver-specific options for raw``
1113         This is the image format block driver for raw images. It is
1114         usually stacked on top of a protocol level block driver such as
1115         ``file``.
1116
1117         ``file``
1118             Reference to or definition of the data source block driver
1119             node (e.g. a ``file`` driver node)
1120
1121         Example 1:
1122
1123         ::
1124
1125             -blockdev driver=file,node-name=disk_file,filename=disk.img
1126             -blockdev driver=raw,node-name=disk,file=disk_file
1127
1128         Example 2:
1129
1130         ::
1131
1132             -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
1133
1134     ``Driver-specific options for qcow2``
1135         This is the image format block driver for qcow2 images. It is
1136         usually stacked on top of a protocol level block driver such as
1137         ``file``.
1138
1139         ``file``
1140             Reference to or definition of the data source block driver
1141             node (e.g. a ``file`` driver node)
1142
1143         ``backing``
1144             Reference to or definition of the backing file block device
1145             (default is taken from the image file). It is allowed to
1146             pass ``null`` here in order to disable the default backing
1147             file.
1148
1149         ``lazy-refcounts``
1150             Whether to enable the lazy refcounts feature (on/off;
1151             default is taken from the image file)
1152
1153         ``cache-size``
1154             The maximum total size of the L2 table and refcount block
1155             caches in bytes (default: the sum of l2-cache-size and
1156             refcount-cache-size)
1157
1158         ``l2-cache-size``
1159             The maximum size of the L2 table cache in bytes (default: if
1160             cache-size is not specified - 32M on Linux platforms, and 8M
1161             on non-Linux platforms; otherwise, as large as possible
1162             within the cache-size, while permitting the requested or the
1163             minimal refcount cache size)
1164
1165         ``refcount-cache-size``
1166             The maximum size of the refcount block cache in bytes
1167             (default: 4 times the cluster size; or if cache-size is
1168             specified, the part of it which is not used for the L2
1169             cache)
1170
1171         ``cache-clean-interval``
1172             Clean unused entries in the L2 and refcount caches. The
1173             interval is in seconds. The default value is 600 on
1174             supporting platforms, and 0 on other platforms. Setting it
1175             to 0 disables this feature.
1176
1177         ``pass-discard-request``
1178             Whether discard requests to the qcow2 device should be
1179             forwarded to the data source (on/off; default: on if
1180             discard=unmap is specified, off otherwise)
1181
1182         ``pass-discard-snapshot``
1183             Whether discard requests for the data source should be
1184             issued when a snapshot operation (e.g. deleting a snapshot)
1185             frees clusters in the qcow2 file (on/off; default: on)
1186
1187         ``pass-discard-other``
1188             Whether discard requests for the data source should be
1189             issued on other occasions where a cluster gets freed
1190             (on/off; default: off)
1191
1192         ``overlap-check``
1193             Which overlap checks to perform for writes to the image
1194             (none/constant/cached/all; default: cached). For details or
1195             finer granularity control refer to the QAPI documentation of
1196             ``blockdev-add``.
1197
1198         Example 1:
1199
1200         ::
1201
1202             -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1203             -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1204
1205         Example 2:
1206
1207         ::
1208
1209             -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1210
1211     ``Driver-specific options for other drivers``
1212         Please refer to the QAPI documentation of the ``blockdev-add``
1213         QMP command.
1214 ERST
1215
1216 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
1217     "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
1218     "       [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
1219     "       [,snapshot=on|off][,rerror=ignore|stop|report]\n"
1220     "       [,werror=ignore|stop|report|enospc][,id=name]\n"
1221     "       [,aio=threads|native|io_uring]\n"
1222     "       [,readonly=on|off][,copy-on-read=on|off]\n"
1223     "       [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
1224     "       [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
1225     "       [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
1226     "       [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
1227     "       [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
1228     "       [[,iops_size=is]]\n"
1229     "       [[,group=g]]\n"
1230     "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
1231 SRST
1232 ``-drive option[,option[,option[,...]]]``
1233     Define a new drive. This includes creating a block driver node (the
1234     backend) as well as a guest device, and is mostly a shortcut for
1235     defining the corresponding ``-blockdev`` and ``-device`` options.
1236
1237     ``-drive`` accepts all options that are accepted by ``-blockdev``.
1238     In addition, it knows the following options:
1239
1240     ``file=file``
1241         This option defines which disk image (see the :ref:`disk images`
1242         chapter in the System Emulation Users Guide) to use with this drive.
1243         If the filename contains comma, you must double it (for instance,
1244         "file=my,,file" to use file "my,file").
1245
1246         Special files such as iSCSI devices can be specified using
1247         protocol specific URLs. See the section for "Device URL Syntax"
1248         for more information.
1249
1250     ``if=interface``
1251         This option defines on which type on interface the drive is
1252         connected. Available types are: ide, scsi, sd, mtd, floppy,
1253         pflash, virtio, none.
1254
1255     ``bus=bus,unit=unit``
1256         These options define where is connected the drive by defining
1257         the bus number and the unit id.
1258
1259     ``index=index``
1260         This option defines where is connected the drive by using an
1261         index in the list of available connectors of a given interface
1262         type.
1263
1264     ``media=media``
1265         This option defines the type of the media: disk or cdrom.
1266
1267     ``snapshot=snapshot``
1268         snapshot is "on" or "off" and controls snapshot mode for the
1269         given drive (see ``-snapshot``).
1270
1271     ``cache=cache``
1272         cache is "none", "writeback", "unsafe", "directsync" or
1273         "writethrough" and controls how the host cache is used to access
1274         block data. This is a shortcut that sets the ``cache.direct``
1275         and ``cache.no-flush`` options (as in ``-blockdev``), and
1276         additionally ``cache.writeback``, which provides a default for
1277         the ``write-cache`` option of block guest devices (as in
1278         ``-device``). The modes correspond to the following settings:
1279
1280         =============  ===============   ============   ==============
1281         \              cache.writeback   cache.direct   cache.no-flush
1282         =============  ===============   ============   ==============
1283         writeback      on                off            off
1284         none           on                on             off
1285         writethrough   off               off            off
1286         directsync     off               on             off
1287         unsafe         on                off            on
1288         =============  ===============   ============   ==============
1289
1290         The default mode is ``cache=writeback``.
1291
1292     ``aio=aio``
1293         aio is "threads", "native", or "io_uring" and selects between pthread
1294         based disk I/O, native Linux AIO, or Linux io_uring API.
1295
1296     ``format=format``
1297         Specify which disk format will be used rather than detecting the
1298         format. Can be used to specify format=raw to avoid interpreting
1299         an untrusted format header.
1300
1301     ``werror=action,rerror=action``
1302         Specify which action to take on write and read errors. Valid
1303         actions are: "ignore" (ignore the error and try to continue),
1304         "stop" (pause QEMU), "report" (report the error to the guest),
1305         "enospc" (pause QEMU only if the host disk is full; report the
1306         error to the guest otherwise). The default setting is
1307         ``werror=enospc`` and ``rerror=report``.
1308
1309     ``copy-on-read=copy-on-read``
1310         copy-on-read is "on" or "off" and enables whether to copy read
1311         backing file sectors into the image file.
1312
1313     ``bps=b,bps_rd=r,bps_wr=w``
1314         Specify bandwidth throttling limits in bytes per second, either
1315         for all request types or for reads or writes only. Small values
1316         can lead to timeouts or hangs inside the guest. A safe minimum
1317         for disks is 2 MB/s.
1318
1319     ``bps_max=bm,bps_rd_max=rm,bps_wr_max=wm``
1320         Specify bursts in bytes per second, either for all request types
1321         or for reads or writes only. Bursts allow the guest I/O to spike
1322         above the limit temporarily.
1323
1324     ``iops=i,iops_rd=r,iops_wr=w``
1325         Specify request rate limits in requests per second, either for
1326         all request types or for reads or writes only.
1327
1328     ``iops_max=bm,iops_rd_max=rm,iops_wr_max=wm``
1329         Specify bursts in requests per second, either for all request
1330         types or for reads or writes only. Bursts allow the guest I/O to
1331         spike above the limit temporarily.
1332
1333     ``iops_size=is``
1334         Let every is bytes of a request count as a new request for iops
1335         throttling purposes. Use this option to prevent guests from
1336         circumventing iops limits by sending fewer but larger requests.
1337
1338     ``group=g``
1339         Join a throttling quota group with given name g. All drives that
1340         are members of the same group are accounted for together. Use
1341         this option to prevent guests from circumventing throttling
1342         limits by using many small disks instead of a single larger
1343         disk.
1344
1345     By default, the ``cache.writeback=on`` mode is used. It will report
1346     data writes as completed as soon as the data is present in the host
1347     page cache. This is safe as long as your guest OS makes sure to
1348     correctly flush disk caches where needed. If your guest OS does not
1349     handle volatile disk write caches correctly and your host crashes or
1350     loses power, then the guest may experience data corruption.
1351
1352     For such guests, you should consider using ``cache.writeback=off``.
1353     This means that the host page cache will be used to read and write
1354     data, but write notification will be sent to the guest only after
1355     QEMU has made sure to flush each write to the disk. Be aware that
1356     this has a major impact on performance.
1357
1358     When using the ``-snapshot`` option, unsafe caching is always used.
1359
1360     Copy-on-read avoids accessing the same backing file sectors
1361     repeatedly and is useful when the backing file is over a slow
1362     network. By default copy-on-read is off.
1363
1364     Instead of ``-cdrom`` you can use:
1365
1366     .. parsed-literal::
1367
1368         |qemu_system| -drive file=file,index=2,media=cdrom
1369
1370     Instead of ``-hda``, ``-hdb``, ``-hdc``, ``-hdd``, you can use:
1371
1372     .. parsed-literal::
1373
1374         |qemu_system| -drive file=file,index=0,media=disk
1375         |qemu_system| -drive file=file,index=1,media=disk
1376         |qemu_system| -drive file=file,index=2,media=disk
1377         |qemu_system| -drive file=file,index=3,media=disk
1378
1379     You can open an image using pre-opened file descriptors from an fd
1380     set:
1381
1382     .. parsed-literal::
1383
1384         |qemu_system| \\
1385          -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \\
1386          -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \\
1387          -drive file=/dev/fdset/2,index=0,media=disk
1388
1389     You can connect a CDROM to the slave of ide0:
1390
1391     .. parsed-literal::
1392
1393         |qemu_system_x86| -drive file=file,if=ide,index=1,media=cdrom
1394
1395     If you don't specify the "file=" argument, you define an empty
1396     drive:
1397
1398     .. parsed-literal::
1399
1400         |qemu_system_x86| -drive if=ide,index=1,media=cdrom
1401
1402     Instead of ``-fda``, ``-fdb``, you can use:
1403
1404     .. parsed-literal::
1405
1406         |qemu_system_x86| -drive file=file,index=0,if=floppy
1407         |qemu_system_x86| -drive file=file,index=1,if=floppy
1408
1409     By default, interface is "ide" and index is automatically
1410     incremented:
1411
1412     .. parsed-literal::
1413
1414         |qemu_system_x86| -drive file=a -drive file=b"
1415
1416     is interpreted like:
1417
1418     .. parsed-literal::
1419
1420         |qemu_system_x86| -hda a -hdb b
1421 ERST
1422
1423 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
1424     "-mtdblock file  use 'file' as on-board Flash memory image\n",
1425     QEMU_ARCH_ALL)
1426 SRST
1427 ``-mtdblock file``
1428     Use file as on-board Flash memory image.
1429 ERST
1430
1431 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
1432     "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
1433 SRST
1434 ``-sd file``
1435     Use file as SecureDigital card image.
1436 ERST
1437
1438 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
1439     "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
1440 SRST
1441 ``-pflash file``
1442     Use file as a parallel flash image.
1443 ERST
1444
1445 DEF("snapshot", 0, QEMU_OPTION_snapshot,
1446     "-snapshot       write to temporary files instead of disk image files\n",
1447     QEMU_ARCH_ALL)
1448 SRST
1449 ``-snapshot``
1450     Write to temporary files instead of disk image files. In this case,
1451     the raw disk image you use is not written back. You can however
1452     force the write back by pressing C-a s (see the :ref:`disk images`
1453     chapter in the System Emulation Users Guide).
1454 ERST
1455
1456 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
1457     "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1458     " [,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]\n"
1459     " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1460     " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1461     " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1462     " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1463     " [[,throttling.iops-size=is]]\n"
1464     "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]\n"
1465     "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]\n"
1466     "-fsdev synth,id=id\n",
1467     QEMU_ARCH_ALL)
1468
1469 SRST
1470 ``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly=on][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
1471   \ 
1472 ``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly=on]``
1473   \
1474 ``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly=on]``
1475   \
1476 ``-fsdev synth,id=id[,readonly=on]``
1477     Define a new file system device. Valid options are:
1478
1479     ``local``
1480         Accesses to the filesystem are done by QEMU.
1481
1482     ``proxy``
1483         Accesses to the filesystem are done by virtfs-proxy-helper(1).
1484
1485     ``synth``
1486         Synthetic filesystem, only used by QTests.
1487
1488     ``id=id``
1489         Specifies identifier for this device.
1490
1491     ``path=path``
1492         Specifies the export path for the file system device. Files
1493         under this path will be available to the 9p client on the guest.
1494
1495     ``security_model=security_model``
1496         Specifies the security model to be used for this export path.
1497         Supported security models are "passthrough", "mapped-xattr",
1498         "mapped-file" and "none". In "passthrough" security model, files
1499         are stored using the same credentials as they are created on the
1500         guest. This requires QEMU to run as root. In "mapped-xattr"
1501         security model, some of the file attributes like uid, gid, mode
1502         bits and link target are stored as file attributes. For
1503         "mapped-file" these attributes are stored in the hidden
1504         .virtfs\_metadata directory. Directories exported by this
1505         security model cannot interact with other unix tools. "none"
1506         security model is same as passthrough except the sever won't
1507         report failures if it fails to set file attributes like
1508         ownership. Security model is mandatory only for local fsdriver.
1509         Other fsdrivers (like proxy) don't take security model as a
1510         parameter.
1511
1512     ``writeout=writeout``
1513         This is an optional argument. The only supported value is
1514         "immediate". This means that host page cache will be used to
1515         read and write data but write notification will be sent to the
1516         guest only when the data has been reported as written by the
1517         storage subsystem.
1518
1519     ``readonly=on``
1520         Enables exporting 9p share as a readonly mount for guests. By
1521         default read-write access is given.
1522
1523     ``socket=socket``
1524         Enables proxy filesystem driver to use passed socket file for
1525         communicating with virtfs-proxy-helper(1).
1526
1527     ``sock_fd=sock_fd``
1528         Enables proxy filesystem driver to use passed socket descriptor
1529         for communicating with virtfs-proxy-helper(1). Usually a helper
1530         like libvirt will create socketpair and pass one of the fds as
1531         sock\_fd.
1532
1533     ``fmode=fmode``
1534         Specifies the default mode for newly created files on the host.
1535         Works only with security models "mapped-xattr" and
1536         "mapped-file".
1537
1538     ``dmode=dmode``
1539         Specifies the default mode for newly created directories on the
1540         host. Works only with security models "mapped-xattr" and
1541         "mapped-file".
1542
1543     ``throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w``
1544         Specify bandwidth throttling limits in bytes per second, either
1545         for all request types or for reads or writes only.
1546
1547     ``throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm``
1548         Specify bursts in bytes per second, either for all request types
1549         or for reads or writes only. Bursts allow the guest I/O to spike
1550         above the limit temporarily.
1551
1552     ``throttling.iops-total=i,throttling.iops-read=r, throttling.iops-write=w``
1553         Specify request rate limits in requests per second, either for
1554         all request types or for reads or writes only.
1555
1556     ``throttling.iops-total-max=im,throttling.iops-read-max=irm, throttling.iops-write-max=iwm``
1557         Specify bursts in requests per second, either for all request
1558         types or for reads or writes only. Bursts allow the guest I/O to
1559         spike above the limit temporarily.
1560
1561     ``throttling.iops-size=is``
1562         Let every is bytes of a request count as a new request for iops
1563         throttling purposes.
1564
1565     -fsdev option is used along with -device driver "virtio-9p-...".
1566
1567 ``-device virtio-9p-type,fsdev=id,mount_tag=mount_tag``
1568     Options for virtio-9p-... driver are:
1569
1570     ``type``
1571         Specifies the variant to be used. Supported values are "pci",
1572         "ccw" or "device", depending on the machine type.
1573
1574     ``fsdev=id``
1575         Specifies the id value specified along with -fsdev option.
1576
1577     ``mount_tag=mount_tag``
1578         Specifies the tag name to be used by the guest to mount this
1579         export point.
1580 ERST
1581
1582 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
1583     "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1584     "        [,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
1585     "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]\n"
1586     "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]\n"
1587     "-virtfs synth,mount_tag=tag[,id=id][,readonly=on]\n",
1588     QEMU_ARCH_ALL)
1589
1590 SRST
1591 ``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly=on] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
1592   \ 
1593 ``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
1594   \ 
1595 ``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
1596   \
1597 ``-virtfs synth,mount_tag=mount_tag``
1598     Define a new virtual filesystem device and expose it to the guest using
1599     a virtio-9p-device (a.k.a. 9pfs), which essentially means that a certain
1600     directory on host is made directly accessible by guest as a pass-through
1601     file system by using the 9P network protocol for communication between
1602     host and guests, if desired even accessible, shared by several guests
1603     simultaniously.
1604
1605     Note that ``-virtfs`` is actually just a convenience shortcut for its
1606     generalized form ``-fsdev -device virtio-9p-pci``.
1607
1608     The general form of pass-through file system options are:
1609
1610     ``local``
1611         Accesses to the filesystem are done by QEMU.
1612
1613     ``proxy``
1614         Accesses to the filesystem are done by virtfs-proxy-helper(1).
1615
1616     ``synth``
1617         Synthetic filesystem, only used by QTests.
1618
1619     ``id=id``
1620         Specifies identifier for the filesystem device
1621
1622     ``path=path``
1623         Specifies the export path for the file system device. Files
1624         under this path will be available to the 9p client on the guest.
1625
1626     ``security_model=security_model``
1627         Specifies the security model to be used for this export path.
1628         Supported security models are "passthrough", "mapped-xattr",
1629         "mapped-file" and "none". In "passthrough" security model, files
1630         are stored using the same credentials as they are created on the
1631         guest. This requires QEMU to run as root. In "mapped-xattr"
1632         security model, some of the file attributes like uid, gid, mode
1633         bits and link target are stored as file attributes. For
1634         "mapped-file" these attributes are stored in the hidden
1635         .virtfs\_metadata directory. Directories exported by this
1636         security model cannot interact with other unix tools. "none"
1637         security model is same as passthrough except the sever won't
1638         report failures if it fails to set file attributes like
1639         ownership. Security model is mandatory only for local fsdriver.
1640         Other fsdrivers (like proxy) don't take security model as a
1641         parameter.
1642
1643     ``writeout=writeout``
1644         This is an optional argument. The only supported value is
1645         "immediate". This means that host page cache will be used to
1646         read and write data but write notification will be sent to the
1647         guest only when the data has been reported as written by the
1648         storage subsystem.
1649
1650     ``readonly=on``
1651         Enables exporting 9p share as a readonly mount for guests. By
1652         default read-write access is given.
1653
1654     ``socket=socket``
1655         Enables proxy filesystem driver to use passed socket file for
1656         communicating with virtfs-proxy-helper(1). Usually a helper like
1657         libvirt will create socketpair and pass one of the fds as
1658         sock\_fd.
1659
1660     ``sock_fd``
1661         Enables proxy filesystem driver to use passed 'sock\_fd' as the
1662         socket descriptor for interfacing with virtfs-proxy-helper(1).
1663
1664     ``fmode=fmode``
1665         Specifies the default mode for newly created files on the host.
1666         Works only with security models "mapped-xattr" and
1667         "mapped-file".
1668
1669     ``dmode=dmode``
1670         Specifies the default mode for newly created directories on the
1671         host. Works only with security models "mapped-xattr" and
1672         "mapped-file".
1673
1674     ``mount_tag=mount_tag``
1675         Specifies the tag name to be used by the guest to mount this
1676         export point.
1677
1678     ``multidevs=multidevs``
1679         Specifies how to deal with multiple devices being shared with a
1680         9p export. Supported behaviours are either "remap", "forbid" or
1681         "warn". The latter is the default behaviour on which virtfs 9p
1682         expects only one device to be shared with the same export, and
1683         if more than one device is shared and accessed via the same 9p
1684         export then only a warning message is logged (once) by qemu on
1685         host side. In order to avoid file ID collisions on guest you
1686         should either create a separate virtfs export for each device to
1687         be shared with guests (recommended way) or you might use "remap"
1688         instead which allows you to share multiple devices with only one
1689         export instead, which is achieved by remapping the original
1690         inode numbers from host to guest in a way that would prevent
1691         such collisions. Remapping inodes in such use cases is required
1692         because the original device IDs from host are never passed and
1693         exposed on guest. Instead all files of an export shared with
1694         virtfs always share the same device id on guest. So two files
1695         with identical inode numbers but from actually different devices
1696         on host would otherwise cause a file ID collision and hence
1697         potential misbehaviours on guest. "forbid" on the other hand
1698         assumes like "warn" that only one device is shared by the same
1699         export, however it will not only log a warning message but also
1700         deny access to additional devices on guest. Note though that
1701         "forbid" does currently not block all possible file access
1702         operations (e.g. readdir() would still return entries from other
1703         devices).
1704 ERST
1705
1706 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1707     "-iscsi [user=user][,password=password]\n"
1708     "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1709     "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1710     "       [,timeout=timeout]\n"
1711     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
1712
1713 SRST
1714 ``-iscsi``
1715     Configure iSCSI session parameters.
1716 ERST
1717
1718 DEFHEADING()
1719
1720 DEFHEADING(USB convenience options:)
1721
1722 DEF("usb", 0, QEMU_OPTION_usb,
1723     "-usb            enable on-board USB host controller (if not enabled by default)\n",
1724     QEMU_ARCH_ALL)
1725 SRST
1726 ``-usb``
1727     Enable USB emulation on machine types with an on-board USB host
1728     controller (if not enabled by default). Note that on-board USB host
1729     controllers may not support USB 3.0. In this case
1730     ``-device qemu-xhci`` can be used instead on machines with PCI.
1731 ERST
1732
1733 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1734     "-usbdevice name add the host or guest USB device 'name'\n",
1735     QEMU_ARCH_ALL)
1736 SRST
1737 ``-usbdevice devname``
1738     Add the USB device devname, and enable an on-board USB controller
1739     if possible and necessary (just like it can be done via
1740     ``-machine usb=on``). Note that this option is mainly intended for
1741     the user's convenience only. More fine-grained control can be
1742     achieved by selecting a USB host controller (if necessary) and the
1743     desired USB device via the ``-device`` option instead. For example,
1744     instead of using ``-usbdevice mouse`` it is possible to use
1745     ``-device qemu-xhci -device usb-mouse`` to connect the USB mouse
1746     to a USB 3.0 controller instead (at least on machines that support
1747     PCI and do not have an USB controller enabled by default yet).
1748     For more details, see the chapter about
1749     :ref:`Connecting USB devices` in the System Emulation Users Guide.
1750     Possible devices for devname are:
1751
1752     ``braille``
1753         Braille device. This will use BrlAPI to display the braille
1754         output on a real or fake device (i.e. it also creates a
1755         corresponding ``braille`` chardev automatically beside the
1756         ``usb-braille`` USB device).
1757
1758     ``keyboard``
1759         Standard USB keyboard. Will override the PS/2 keyboard (if present).
1760
1761     ``mouse``
1762         Virtual Mouse. This will override the PS/2 mouse emulation when
1763         activated.
1764
1765     ``tablet``
1766         Pointer device that uses absolute coordinates (like a
1767         touchscreen). This means QEMU is able to report the mouse
1768         position without having to grab the mouse. Also overrides the
1769         PS/2 mouse emulation when activated.
1770
1771     ``wacom-tablet``
1772         Wacom PenPartner USB tablet.
1773
1774
1775 ERST
1776
1777 DEFHEADING()
1778
1779 DEFHEADING(Display options:)
1780
1781 DEF("display", HAS_ARG, QEMU_OPTION_display,
1782 #if defined(CONFIG_SPICE)
1783     "-display spice-app[,gl=on|off]\n"
1784 #endif
1785 #if defined(CONFIG_SDL)
1786     "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
1787     "            [,window_close=on|off][,gl=on|core|es|off]\n"
1788 #endif
1789 #if defined(CONFIG_GTK)
1790     "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1791 #endif
1792 #if defined(CONFIG_VNC)
1793     "-display vnc=<display>[,<optargs>]\n"
1794 #endif
1795 #if defined(CONFIG_CURSES)
1796     "-display curses[,charset=<encoding>]\n"
1797 #endif
1798 #if defined(CONFIG_OPENGL)
1799     "-display egl-headless[,rendernode=<file>]\n"
1800 #endif
1801     "-display none\n"
1802     "                select display backend type\n"
1803     "                The default display is equivalent to\n                "
1804 #if defined(CONFIG_GTK)
1805             "\"-display gtk\"\n"
1806 #elif defined(CONFIG_SDL)
1807             "\"-display sdl\"\n"
1808 #elif defined(CONFIG_COCOA)
1809             "\"-display cocoa\"\n"
1810 #elif defined(CONFIG_VNC)
1811             "\"-vnc localhost:0,to=99,id=default\"\n"
1812 #else
1813             "\"-display none\"\n"
1814 #endif
1815     , QEMU_ARCH_ALL)
1816 SRST
1817 ``-display type``
1818     Select type of display to use. This option is a replacement for the
1819     old style -sdl/-curses/... options. Use ``-display help`` to list
1820     the available display types. Valid values for type are
1821
1822     ``sdl``
1823         Display video output via SDL (usually in a separate graphics
1824         window; see the SDL documentation for other possibilities).
1825
1826     ``curses``
1827         Display video output via curses. For graphics device models
1828         which support a text mode, QEMU can display this output using a
1829         curses/ncurses interface. Nothing is displayed when the graphics
1830         device is in graphical mode or if the graphics device does not
1831         support a text mode. Generally only the VGA device models
1832         support text mode. The font charset used by the guest can be
1833         specified with the ``charset`` option, for example
1834         ``charset=CP850`` for IBM CP850 encoding. The default is
1835         ``CP437``.
1836
1837     ``none``
1838         Do not display video output. The guest will still see an
1839         emulated graphics card, but its output will not be displayed to
1840         the QEMU user. This option differs from the -nographic option in
1841         that it only affects what is done with video output; -nographic
1842         also changes the destination of the serial and parallel port
1843         data.
1844
1845     ``gtk``
1846         Display video output in a GTK window. This interface provides
1847         drop-down menus and other UI elements to configure and control
1848         the VM during runtime.
1849
1850     ``vnc``
1851         Start a VNC server on display <arg>
1852
1853     ``egl-headless``
1854         Offload all OpenGL operations to a local DRI device. For any
1855         graphical display, this display needs to be paired with either
1856         VNC or SPICE displays.
1857
1858     ``spice-app``
1859         Start QEMU as a Spice server and launch the default Spice client
1860         application. The Spice server will redirect the serial consoles
1861         and QEMU monitors. (Since 4.0)
1862 ERST
1863
1864 DEF("nographic", 0, QEMU_OPTION_nographic,
1865     "-nographic      disable graphical output and redirect serial I/Os to console\n",
1866     QEMU_ARCH_ALL)
1867 SRST
1868 ``-nographic``
1869     Normally, if QEMU is compiled with graphical window support, it
1870     displays output such as guest graphics, guest console, and the QEMU
1871     monitor in a window. With this option, you can totally disable
1872     graphical output so that QEMU is a simple command line application.
1873     The emulated serial port is redirected on the console and muxed with
1874     the monitor (unless redirected elsewhere explicitly). Therefore, you
1875     can still use QEMU to debug a Linux kernel with a serial console.
1876     Use C-a h for help on switching between the console and monitor.
1877 ERST
1878
1879 DEF("curses", 0, QEMU_OPTION_curses,
1880     "-curses         shorthand for -display curses\n",
1881     QEMU_ARCH_ALL)
1882 SRST
1883 ``-curses``
1884     Normally, if QEMU is compiled with graphical window support, it
1885     displays output such as guest graphics, guest console, and the QEMU
1886     monitor in a window. With this option, QEMU can display the VGA
1887     output when in text mode using a curses/ncurses interface. Nothing
1888     is displayed in graphical mode.
1889 ERST
1890
1891 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
1892     "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1893     QEMU_ARCH_ALL)
1894 SRST
1895 ``-alt-grab``
1896     Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that
1897     this also affects the special keys (for fullscreen, monitor-mode
1898     switching, etc).
1899 ERST
1900
1901 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
1902     "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1903     QEMU_ARCH_ALL)
1904 SRST
1905 ``-ctrl-grab``
1906     Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this
1907     also affects the special keys (for fullscreen, monitor-mode
1908     switching, etc).
1909 ERST
1910
1911 DEF("no-quit", 0, QEMU_OPTION_no_quit,
1912     "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
1913 SRST
1914 ``-no-quit``
1915     Disable SDL window close capability.
1916 ERST
1917
1918 DEF("sdl", 0, QEMU_OPTION_sdl,
1919     "-sdl            shorthand for -display sdl\n", QEMU_ARCH_ALL)
1920 SRST
1921 ``-sdl``
1922     Enable SDL.
1923 ERST
1924
1925 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
1926     "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1927     "       [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1928     "       [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
1929     "       [,x509-dh-key-file=<file>][,addr=addr]\n"
1930     "       [,ipv4=on|off][,ipv6=on|off][,unix=on|off]\n"
1931     "       [,tls-ciphers=<list>]\n"
1932     "       [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1933     "       [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1934     "       [,sasl=on|off][,disable-ticketing=on|off]\n"
1935     "       [,password=<string>][,password-secret=<secret-id>]\n"
1936     "       [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1937     "       [,jpeg-wan-compression=[auto|never|always]]\n"
1938     "       [,zlib-glz-wan-compression=[auto|never|always]]\n"
1939     "       [,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]\n"
1940     "       [,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]\n"
1941     "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
1942     "       [,gl=[on|off]][,rendernode=<file>]\n"
1943     "   enable spice\n"
1944     "   at least one of {port, tls-port} is mandatory\n",
1945     QEMU_ARCH_ALL)
1946 SRST
1947 ``-spice option[,option[,...]]``
1948     Enable the spice remote desktop protocol. Valid options are
1949
1950     ``port=<nr>``
1951         Set the TCP port spice is listening on for plaintext channels.
1952
1953     ``addr=<addr>``
1954         Set the IP address spice is listening on. Default is any
1955         address.
1956
1957     ``ipv4=on|off``; \ ``ipv6=on|off``; \ ``unix=on|off``
1958         Force using the specified IP version.
1959
1960     ``password=<string>``
1961         Set the password you need to authenticate.
1962
1963         This option is deprecated and insecure because it leaves the
1964         password visible in the process listing. Use ``password-secret``
1965         instead.
1966
1967     ``password-secret=<secret-id>``
1968         Set the ID of the ``secret`` object containing the password
1969         you need to authenticate.
1970
1971     ``sasl=on|off``
1972         Require that the client use SASL to authenticate with the spice.
1973         The exact choice of authentication method used is controlled
1974         from the system / user's SASL configuration file for the 'qemu'
1975         service. This is typically found in /etc/sasl2/qemu.conf. If
1976         running QEMU as an unprivileged user, an environment variable
1977         SASL\_CONF\_PATH can be used to make it search alternate
1978         locations for the service config. While some SASL auth methods
1979         can also provide data encryption (eg GSSAPI), it is recommended
1980         that SASL always be combined with the 'tls' and 'x509' settings
1981         to enable use of SSL and server certificates. This ensures a
1982         data encryption preventing compromise of authentication
1983         credentials.
1984
1985     ``disable-ticketing=on|off``
1986         Allow client connects without authentication.
1987
1988     ``disable-copy-paste=on|off``
1989         Disable copy paste between the client and the guest.
1990
1991     ``disable-agent-file-xfer=on|off``
1992         Disable spice-vdagent based file-xfer between the client and the
1993         guest.
1994
1995     ``tls-port=<nr>``
1996         Set the TCP port spice is listening on for encrypted channels.
1997
1998     ``x509-dir=<dir>``
1999         Set the x509 file directory. Expects same filenames as -vnc
2000         $display,x509=$dir
2001
2002     ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>``
2003         The x509 file names can also be configured individually.
2004
2005     ``tls-ciphers=<list>``
2006         Specify which ciphers to use.
2007
2008     ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]``
2009         Force specific channel to be used with or without TLS
2010         encryption. The options can be specified multiple times to
2011         configure multiple channels. The special name "default" can be
2012         used to set the default mode. For channels which are not
2013         explicitly forced into one mode the spice client is allowed to
2014         pick tls/plaintext as he pleases.
2015
2016     ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]``
2017         Configure image compression (lossless). Default is auto\_glz.
2018
2019     ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]``
2020         Configure wan image compression (lossy for slow links). Default
2021         is auto.
2022
2023     ``streaming-video=[off|all|filter]``
2024         Configure video stream detection. Default is off.
2025
2026     ``agent-mouse=[on|off]``
2027         Enable/disable passing mouse events via vdagent. Default is on.
2028
2029     ``playback-compression=[on|off]``
2030         Enable/disable audio stream compression (using celt 0.5.1).
2031         Default is on.
2032
2033     ``seamless-migration=[on|off]``
2034         Enable/disable spice seamless migration. Default is off.
2035
2036     ``gl=[on|off]``
2037         Enable/disable OpenGL context. Default is off.
2038
2039     ``rendernode=<file>``
2040         DRM render node for OpenGL rendering. If not specified, it will
2041         pick the first available. (Since 2.9)
2042 ERST
2043
2044 DEF("portrait", 0, QEMU_OPTION_portrait,
2045     "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
2046     QEMU_ARCH_ALL)
2047 SRST
2048 ``-portrait``
2049     Rotate graphical output 90 deg left (only PXA LCD).
2050 ERST
2051
2052 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
2053     "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
2054     QEMU_ARCH_ALL)
2055 SRST
2056 ``-rotate deg``
2057     Rotate graphical output some deg left (only PXA LCD).
2058 ERST
2059
2060 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
2061     "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
2062     "                select video card type\n", QEMU_ARCH_ALL)
2063 SRST
2064 ``-vga type``
2065     Select type of VGA card to emulate. Valid values for type are
2066
2067     ``cirrus``
2068         Cirrus Logic GD5446 Video card. All Windows versions starting
2069         from Windows 95 should recognize and use this graphic card. For
2070         optimal performances, use 16 bit color depth in the guest and
2071         the host OS. (This card was the default before QEMU 2.2)
2072
2073     ``std``
2074         Standard VGA card with Bochs VBE extensions. If your guest OS
2075         supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
2076         you want to use high resolution modes (>= 1280x1024x16) then you
2077         should use this option. (This card is the default since QEMU
2078         2.2)
2079
2080     ``vmware``
2081         VMWare SVGA-II compatible adapter. Use it if you have
2082         sufficiently recent XFree86/XOrg server or Windows guest with a
2083         driver for this card.
2084
2085     ``qxl``
2086         QXL paravirtual graphic card. It is VGA compatible (including
2087         VESA 2.0 VBE support). Works best with qxl guest drivers
2088         installed though. Recommended choice when using the spice
2089         protocol.
2090
2091     ``tcx``
2092         (sun4m only) Sun TCX framebuffer. This is the default
2093         framebuffer for sun4m machines and offers both 8-bit and 24-bit
2094         colour depths at a fixed resolution of 1024x768.
2095
2096     ``cg3``
2097         (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
2098         framebuffer for sun4m machines available in both 1024x768
2099         (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
2100         wishing to run older Solaris versions.
2101
2102     ``virtio``
2103         Virtio VGA card.
2104
2105     ``none``
2106         Disable VGA card.
2107 ERST
2108
2109 DEF("full-screen", 0, QEMU_OPTION_full_screen,
2110     "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
2111 SRST
2112 ``-full-screen``
2113     Start in full screen.
2114 ERST
2115
2116 DEF("g", HAS_ARG, QEMU_OPTION_g ,
2117     "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
2118     QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
2119 SRST
2120 ``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]``
2121     Set the initial graphical resolution and depth (PPC, SPARC only).
2122
2123     For PPC the default is 800x600x32.
2124
2125     For SPARC with the TCX graphics device, the default is 1024x768x8
2126     with the option of 1024x768x24. For cgthree, the default is
2127     1024x768x8 with the option of 1152x900x8 for people who wish to use
2128     OBP.
2129 ERST
2130
2131 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
2132     "-vnc <display>  shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
2133 SRST
2134 ``-vnc display[,option[,option[,...]]]``
2135     Normally, if QEMU is compiled with graphical window support, it
2136     displays output such as guest graphics, guest console, and the QEMU
2137     monitor in a window. With this option, you can have QEMU listen on
2138     VNC display display and redirect the VGA display over the VNC
2139     session. It is very useful to enable the usb tablet device when
2140     using this option (option ``-device usb-tablet``). When using the
2141     VNC display, you must use the ``-k`` parameter to set the keyboard
2142     layout if you are not using en-us. Valid syntax for the display is
2143
2144     ``to=L``
2145         With this option, QEMU will try next available VNC displays,
2146         until the number L, if the origianlly defined "-vnc display" is
2147         not available, e.g. port 5900+display is already used by another
2148         application. By default, to=0.
2149
2150     ``host:d``
2151         TCP connections will only be allowed from host on display d. By
2152         convention the TCP port is 5900+d. Optionally, host can be
2153         omitted in which case the server will accept connections from
2154         any host.
2155
2156     ``unix:path``
2157         Connections will be allowed over UNIX domain sockets where path
2158         is the location of a unix socket to listen for connections on.
2159
2160     ``none``
2161         VNC is initialized but not started. The monitor ``change``
2162         command can be used to later start the VNC server.
2163
2164     Following the display value there may be one or more option flags
2165     separated by commas. Valid options are
2166
2167     ``reverse=on|off``
2168         Connect to a listening VNC client via a "reverse" connection.
2169         The client is specified by the display. For reverse network
2170         connections (host:d,``reverse``), the d argument is a TCP port
2171         number, not a display number.
2172
2173     ``websocket=on|off``
2174         Opens an additional TCP listening port dedicated to VNC
2175         Websocket connections. If a bare websocket option is given, the
2176         Websocket port is 5700+display. An alternative port can be
2177         specified with the syntax ``websocket``\ =port.
2178
2179         If host is specified connections will only be allowed from this
2180         host. It is possible to control the websocket listen address
2181         independently, using the syntax ``websocket``\ =host:port.
2182
2183         If no TLS credentials are provided, the websocket connection
2184         runs in unencrypted mode. If TLS credentials are provided, the
2185         websocket connection requires encrypted client connections.
2186
2187     ``password=on|off``
2188         Require that password based authentication is used for client
2189         connections.
2190
2191         The password must be set separately using the ``set_password``
2192         command in the :ref:`QEMU monitor`. The
2193         syntax to change your password is:
2194         ``set_password <protocol> <password>`` where <protocol> could be
2195         either "vnc" or "spice".
2196
2197         If you would like to change <protocol> password expiration, you
2198         should use ``expire_password <protocol> <expiration-time>``
2199         where expiration time could be one of the following options:
2200         now, never, +seconds or UNIX time of expiration, e.g. +60 to
2201         make password expire in 60 seconds, or 1335196800 to make
2202         password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for
2203         this date and time).
2204
2205         You can also use keywords "now" or "never" for the expiration
2206         time to allow <protocol> password to expire immediately or never
2207         expire.
2208
2209     ``password-secret=<secret-id>``
2210         Require that password based authentication is used for client
2211         connections, using the password provided by the ``secret``
2212         object identified by ``secret-id``.
2213
2214     ``tls-creds=ID``
2215         Provides the ID of a set of TLS credentials to use to secure the
2216         VNC server. They will apply to both the normal VNC server socket
2217         and the websocket socket (if enabled). Setting TLS credentials
2218         will cause the VNC server socket to enable the VeNCrypt auth
2219         mechanism. The credentials should have been previously created
2220         using the ``-object tls-creds`` argument.
2221
2222     ``tls-authz=ID``
2223         Provides the ID of the QAuthZ authorization object against which
2224         the client's x509 distinguished name will validated. This object
2225         is only resolved at time of use, so can be deleted and recreated
2226         on the fly while the VNC server is active. If missing, it will
2227         default to denying access.
2228
2229     ``sasl=on|off``
2230         Require that the client use SASL to authenticate with the VNC
2231         server. The exact choice of authentication method used is
2232         controlled from the system / user's SASL configuration file for
2233         the 'qemu' service. This is typically found in
2234         /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
2235         an environment variable SASL\_CONF\_PATH can be used to make it
2236         search alternate locations for the service config. While some
2237         SASL auth methods can also provide data encryption (eg GSSAPI),
2238         it is recommended that SASL always be combined with the 'tls'
2239         and 'x509' settings to enable use of SSL and server
2240         certificates. This ensures a data encryption preventing
2241         compromise of authentication credentials. See the
2242         :ref:`VNC security` section in the System Emulation Users Guide
2243         for details on using SASL authentication.
2244
2245     ``sasl-authz=ID``
2246         Provides the ID of the QAuthZ authorization object against which
2247         the client's SASL username will validated. This object is only
2248         resolved at time of use, so can be deleted and recreated on the
2249         fly while the VNC server is active. If missing, it will default
2250         to denying access.
2251
2252     ``acl=on|off``
2253         Legacy method for enabling authorization of clients against the
2254         x509 distinguished name and SASL username. It results in the
2255         creation of two ``authz-list`` objects with IDs of
2256         ``vnc.username`` and ``vnc.x509dname``. The rules for these
2257         objects must be configured with the HMP ACL commands.
2258
2259         This option is deprecated and should no longer be used. The new
2260         ``sasl-authz`` and ``tls-authz`` options are a replacement.
2261
2262     ``lossy=on|off``
2263         Enable lossy compression methods (gradient, JPEG, ...). If this
2264         option is set, VNC client may receive lossy framebuffer updates
2265         depending on its encoding settings. Enabling this option can
2266         save a lot of bandwidth at the expense of quality.
2267
2268     ``non-adaptive=on|off``
2269         Disable adaptive encodings. Adaptive encodings are enabled by
2270         default. An adaptive encoding will try to detect frequently
2271         updated screen regions, and send updates in these regions using
2272         a lossy encoding (like JPEG). This can be really helpful to save
2273         bandwidth when playing videos. Disabling adaptive encodings
2274         restores the original static behavior of encodings like Tight.
2275
2276     ``share=[allow-exclusive|force-shared|ignore]``
2277         Set display sharing policy. 'allow-exclusive' allows clients to
2278         ask for exclusive access. As suggested by the rfb spec this is
2279         implemented by dropping other connections. Connecting multiple
2280         clients in parallel requires all clients asking for a shared
2281         session (vncviewer: -shared switch). This is the default.
2282         'force-shared' disables exclusive client access. Useful for
2283         shared desktop sessions, where you don't want someone forgetting
2284         specify -shared disconnect everybody else. 'ignore' completely
2285         ignores the shared flag and allows everybody connect
2286         unconditionally. Doesn't conform to the rfb spec but is
2287         traditional QEMU behavior.
2288
2289     ``key-delay-ms``
2290         Set keyboard delay, for key down and key up events, in
2291         milliseconds. Default is 10. Keyboards are low-bandwidth
2292         devices, so this slowdown can help the device and guest to keep
2293         up and not lose events in case events are arriving in bulk.
2294         Possible causes for the latter are flaky network connections, or
2295         scripts for automated testing.
2296
2297     ``audiodev=audiodev``
2298         Use the specified audiodev when the VNC client requests audio
2299         transmission. When not using an -audiodev argument, this option
2300         must be omitted, otherwise is must be present and specify a
2301         valid audiodev.
2302
2303     ``power-control=on|off``
2304         Permit the remote client to issue shutdown, reboot or reset power
2305         control requests.
2306 ERST
2307
2308 ARCHHEADING(, QEMU_ARCH_I386)
2309
2310 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
2311
2312 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
2313     "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
2314     QEMU_ARCH_I386)
2315 SRST
2316 ``-win2k-hack``
2317     Use it when installing Windows 2000 to avoid a disk full bug. After
2318     Windows 2000 is installed, you no longer need this option (this
2319     option slows down the IDE transfers).
2320 ERST
2321
2322 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
2323     "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
2324     QEMU_ARCH_I386)
2325 SRST
2326 ``-no-fd-bootchk``
2327     Disable boot signature checking for floppy disks in BIOS. May be
2328     needed to boot from old floppy disks.
2329 ERST
2330
2331 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
2332            "-no-acpi        disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2333 SRST
2334 ``-no-acpi``
2335     Disable ACPI (Advanced Configuration and Power Interface) support.
2336     Use it if your guest OS complains about ACPI problems (PC target
2337     machine only).
2338 ERST
2339
2340 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
2341     "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
2342 SRST
2343 ``-no-hpet``
2344     Disable HPET support.
2345 ERST
2346
2347 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
2348     "-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"
2349     "                ACPI table description\n", QEMU_ARCH_I386)
2350 SRST
2351 ``-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]...]``
2352     Add ACPI table with specified header fields and context from
2353     specified files. For file=, take whole ACPI table from the specified
2354     files, including all ACPI headers (possible overridden by other
2355     options). For data=, only data portion of the table is used, all
2356     header information is specified in the command line. If a SLIC table
2357     is supplied to QEMU, then the SLIC's oem\_id and oem\_table\_id
2358     fields will override the same in the RSDT and the FADT (a.k.a.
2359     FACP), in order to ensure the field matches required by the
2360     Microsoft SLIC spec and the ACPI spec.
2361 ERST
2362
2363 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2364     "-smbios file=binary\n"
2365     "                load SMBIOS entry from binary file\n"
2366     "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2367     "              [,uefi=on|off]\n"
2368     "                specify SMBIOS type 0 fields\n"
2369     "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2370     "              [,uuid=uuid][,sku=str][,family=str]\n"
2371     "                specify SMBIOS type 1 fields\n"
2372     "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2373     "              [,asset=str][,location=str]\n"
2374     "                specify SMBIOS type 2 fields\n"
2375     "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2376     "              [,sku=str]\n"
2377     "                specify SMBIOS type 3 fields\n"
2378     "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2379     "              [,asset=str][,part=str][,max-speed=%d][,current-speed=%d]\n"
2380     "                specify SMBIOS type 4 fields\n"
2381     "-smbios type=11[,value=str][,path=filename]\n"
2382     "                specify SMBIOS type 11 fields\n"
2383     "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
2384     "               [,asset=str][,part=str][,speed=%d]\n"
2385     "                specify SMBIOS type 17 fields\n"
2386     "-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]\n"
2387     "                specify SMBIOS type 41 fields\n",
2388     QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2389 SRST
2390 ``-smbios file=binary``
2391     Load SMBIOS entry from binary file.
2392
2393 ``-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]``
2394     Specify SMBIOS type 0 fields
2395
2396 ``-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]``
2397     Specify SMBIOS type 1 fields
2398
2399 ``-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]``
2400     Specify SMBIOS type 2 fields
2401
2402 ``-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]``
2403     Specify SMBIOS type 3 fields
2404
2405 ``-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str]``
2406     Specify SMBIOS type 4 fields
2407
2408 ``-smbios type=11[,value=str][,path=filename]``
2409     Specify SMBIOS type 11 fields
2410
2411     This argument can be repeated multiple times, and values are added in the order they are parsed.
2412     Applications intending to use OEM strings data are encouraged to use their application name as
2413     a prefix for the value string. This facilitates passing information for multiple applications
2414     concurrently.
2415
2416     The ``value=str`` syntax provides the string data inline, while the ``path=filename`` syntax
2417     loads data from a file on disk. Note that the file is not permitted to contain any NUL bytes.
2418
2419     Both the ``value`` and ``path`` options can be repeated multiple times and will be added to
2420     the SMBIOS table in the order in which they appear.
2421
2422     Note that on the x86 architecture, the total size of all SMBIOS tables is limited to 65535
2423     bytes. Thus the OEM strings data is not suitable for passing large amounts of data into the
2424     guest. Instead it should be used as a indicator to inform the guest where to locate the real
2425     data set, for example, by specifying the serial ID of a block device.
2426
2427     An example passing three strings is
2428
2429     .. parsed-literal::
2430
2431         -smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\\
2432                         value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\\
2433                         path=/some/file/with/oemstringsdata.txt
2434
2435     In the guest OS this is visible with the ``dmidecode`` command
2436
2437      .. parsed-literal::
2438
2439          $ dmidecode -t 11
2440          Handle 0x0E00, DMI type 11, 5 bytes
2441          OEM Strings
2442               String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/
2443               String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os
2444               String 3: myapp:some extra data
2445
2446
2447 ``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]``
2448     Specify SMBIOS type 17 fields
2449
2450 ``-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]``
2451     Specify SMBIOS type 41 fields
2452
2453     This argument can be repeated multiple times.  Its main use is to allow network interfaces be created
2454     as ``enoX`` on Linux, with X being the instance number, instead of the name depending on the interface
2455     position on the PCI bus.
2456
2457     Here is an example of use:
2458
2459     .. parsed-literal::
2460
2461         -netdev user,id=internet \\
2462         -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \\
2463         -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev
2464
2465     In the guest OS, the device should then appear as ``eno1``:
2466
2467     ..parsed-literal::
2468
2469          $ ip -brief l
2470          lo               UNKNOWN        00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
2471          eno1             UP             50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP>
2472
2473     Currently, the PCI device has to be attached to the root bus.
2474
2475 ERST
2476
2477 DEFHEADING()
2478
2479 DEFHEADING(Network options:)
2480
2481 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
2482 #ifdef CONFIG_SLIRP
2483     "-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]\n"
2484     "         [,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2485     "         [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
2486     "         [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
2487     "         [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
2488 #ifndef _WIN32
2489                                              "[,smb=dir[,smbserver=addr]]\n"
2490 #endif
2491     "                configure a user mode network backend with ID 'str',\n"
2492     "                its DHCP server and optional services\n"
2493 #endif
2494 #ifdef _WIN32
2495     "-netdev tap,id=str,ifname=name\n"
2496     "                configure a host TAP network backend with ID 'str'\n"
2497 #else
2498     "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
2499     "         [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
2500     "         [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
2501     "         [,poll-us=n]\n"
2502     "                configure a host TAP network backend with ID 'str'\n"
2503     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2504     "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2505     "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2506     "                to deconfigure it\n"
2507     "                use '[down]script=no' to disable script execution\n"
2508     "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2509     "                configure it\n"
2510     "                use 'fd=h' to connect to an already opened TAP interface\n"
2511     "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
2512     "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
2513     "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
2514     "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2515     "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
2516     "                use vhost=on to enable experimental in kernel accelerator\n"
2517     "                    (only has effect for virtio guests which use MSIX)\n"
2518     "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
2519     "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
2520     "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
2521     "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
2522     "                use 'poll-us=n' to specify the maximum number of microseconds that could be\n"
2523     "                spent on busy polling for vhost net\n"
2524     "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2525     "                configure a host TAP network backend with ID 'str' that is\n"
2526     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2527     "                using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
2528 #endif
2529 #ifdef __linux__
2530     "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2531     "         [,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]\n"
2532     "         [,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]\n"
2533     "         [,rxcookie=rxcookie][,offset=offset]\n"
2534     "                configure a network backend with ID 'str' connected to\n"
2535     "                an Ethernet over L2TPv3 pseudowire.\n"
2536     "                Linux kernel 3.3+ as well as most routers can talk\n"
2537     "                L2TPv3. This transport allows connecting a VM to a VM,\n"
2538     "                VM to a router and even VM to Host. It is a nearly-universal\n"
2539     "                standard (RFC3931). Note - this implementation uses static\n"
2540     "                pre-configured tunnels (same as the Linux kernel).\n"
2541     "                use 'src=' to specify source address\n"
2542     "                use 'dst=' to specify destination address\n"
2543     "                use 'udp=on' to specify udp encapsulation\n"
2544     "                use 'srcport=' to specify source udp port\n"
2545     "                use 'dstport=' to specify destination udp port\n"
2546     "                use 'ipv6=on' to force v6\n"
2547     "                L2TPv3 uses cookies to prevent misconfiguration as\n"
2548     "                well as a weak security measure\n"
2549     "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
2550     "                use 'txcookie=0x012345678' to specify a txcookie\n"
2551     "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2552     "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2553     "                use 'pincounter=on' to work around broken counter handling in peer\n"
2554     "                use 'offset=X' to add an extra offset between header and data\n"
2555 #endif
2556     "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2557     "                configure a network backend to connect to another network\n"
2558     "                using a socket connection\n"
2559     "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2560     "                configure a network backend to connect to a multicast maddr and port\n"
2561     "                use 'localaddr=addr' to specify the host address to send packets from\n"
2562     "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2563     "                configure a network backend to connect to another network\n"
2564     "                using an UDP tunnel\n"
2565 #ifdef CONFIG_VDE
2566     "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2567     "                configure a network backend to connect to port 'n' of a vde switch\n"
2568     "                running on host and listening for incoming connections on 'socketpath'.\n"
2569     "                Use group 'groupname' and mode 'octalmode' to change default\n"
2570     "                ownership and permissions for communication port.\n"
2571 #endif
2572 #ifdef CONFIG_NETMAP
2573     "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
2574     "                attach to the existing netmap-enabled network interface 'name', or to a\n"
2575     "                VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2576     "                netmap device, defaults to '/dev/netmap')\n"
2577 #endif
2578 #ifdef CONFIG_POSIX
2579     "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2580     "                configure a vhost-user network, backed by a chardev 'dev'\n"
2581 #endif
2582 #ifdef __linux__
2583     "-netdev vhost-vdpa,id=str,vhostdev=/path/to/dev\n"
2584     "                configure a vhost-vdpa network,Establish a vhost-vdpa netdev\n"
2585 #endif
2586     "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
2587     "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
2588 DEF("nic", HAS_ARG, QEMU_OPTION_nic,
2589     "-nic [tap|bridge|"
2590 #ifdef CONFIG_SLIRP
2591     "user|"
2592 #endif
2593 #ifdef __linux__
2594     "l2tpv3|"
2595 #endif
2596 #ifdef CONFIG_VDE
2597     "vde|"
2598 #endif
2599 #ifdef CONFIG_NETMAP
2600     "netmap|"
2601 #endif
2602 #ifdef CONFIG_POSIX
2603     "vhost-user|"
2604 #endif
2605     "socket][,option][,...][mac=macaddr]\n"
2606     "                initialize an on-board / default host NIC (using MAC address\n"
2607     "                macaddr) and connect it to the given host network backend\n"
2608     "-nic none       use it alone to have zero network devices (the default is to\n"
2609     "                provided a 'user' network connection)\n",
2610     QEMU_ARCH_ALL)
2611 DEF("net", HAS_ARG, QEMU_OPTION_net,
2612     "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2613     "                configure or create an on-board (or machine default) NIC and\n"
2614     "                connect it to hub 0 (please use -nic unless you need a hub)\n"
2615     "-net ["
2616 #ifdef CONFIG_SLIRP
2617     "user|"
2618 #endif
2619     "tap|"
2620     "bridge|"
2621 #ifdef CONFIG_VDE
2622     "vde|"
2623 #endif
2624 #ifdef CONFIG_NETMAP
2625     "netmap|"
2626 #endif
2627     "socket][,option][,option][,...]\n"
2628     "                old way to initialize a host network interface\n"
2629     "                (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2630 SRST
2631 ``-nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]``
2632     This option is a shortcut for configuring both the on-board
2633     (default) guest NIC hardware and the host network backend in one go.
2634     The host backend options are the same as with the corresponding
2635     ``-netdev`` options below. The guest NIC model can be set with
2636     ``model=modelname``. Use ``model=help`` to list the available device
2637     types. The hardware MAC address can be set with ``mac=macaddr``.
2638
2639     The following two example do exactly the same, to show how ``-nic``
2640     can be used to shorten the command line length:
2641
2642     .. parsed-literal::
2643
2644         |qemu_system| -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2645         |qemu_system| -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2646
2647 ``-nic none``
2648     Indicate that no network devices should be configured. It is used to
2649     override the default configuration (default NIC with "user" host
2650     network backend) which is activated if no other networking options
2651     are provided.
2652
2653 ``-netdev user,id=id[,option][,option][,...]``
2654     Configure user mode host network backend which requires no
2655     administrator privilege to run. Valid options are:
2656
2657     ``id=id``
2658         Assign symbolic name for use in monitor commands.
2659
2660     ``ipv4=on|off and ipv6=on|off``
2661         Specify that either IPv4 or IPv6 must be enabled. If neither is
2662         specified both protocols are enabled.
2663
2664     ``net=addr[/mask]``
2665         Set IP network address the guest will see. Optionally specify
2666         the netmask, either in the form a.b.c.d or as number of valid
2667         top-most bits. Default is 10.0.2.0/24.
2668
2669     ``host=addr``
2670         Specify the guest-visible address of the host. Default is the
2671         2nd IP in the guest network, i.e. x.x.x.2.
2672
2673     ``ipv6-net=addr[/int]``
2674         Set IPv6 network address the guest will see (default is
2675         fec0::/64). The network prefix is given in the usual hexadecimal
2676         IPv6 address notation. The prefix size is optional, and is given
2677         as the number of valid top-most bits (default is 64).
2678
2679     ``ipv6-host=addr``
2680         Specify the guest-visible IPv6 address of the host. Default is
2681         the 2nd IPv6 in the guest network, i.e. xxxx::2.
2682
2683     ``restrict=on|off``
2684         If this option is enabled, the guest will be isolated, i.e. it
2685         will not be able to contact the host and no guest IP packets
2686         will be routed over the host to the outside. This option does
2687         not affect any explicitly set forwarding rules.
2688
2689     ``hostname=name``
2690         Specifies the client hostname reported by the built-in DHCP
2691         server.
2692
2693     ``dhcpstart=addr``
2694         Specify the first of the 16 IPs the built-in DHCP server can
2695         assign. Default is the 15th to 31st IP in the guest network,
2696         i.e. x.x.x.15 to x.x.x.31.
2697
2698     ``dns=addr``
2699         Specify the guest-visible address of the virtual nameserver. The
2700         address must be different from the host address. Default is the
2701         3rd IP in the guest network, i.e. x.x.x.3.
2702
2703     ``ipv6-dns=addr``
2704         Specify the guest-visible address of the IPv6 virtual
2705         nameserver. The address must be different from the host address.
2706         Default is the 3rd IP in the guest network, i.e. xxxx::3.
2707
2708     ``dnssearch=domain``
2709         Provides an entry for the domain-search list sent by the
2710         built-in DHCP server. More than one domain suffix can be
2711         transmitted by specifying this option multiple times. If
2712         supported, this will cause the guest to automatically try to
2713         append the given domain suffix(es) in case a domain name can not
2714         be resolved.
2715
2716         Example:
2717
2718         .. parsed-literal::
2719
2720             |qemu_system| -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2721
2722     ``domainname=domain``
2723         Specifies the client domain name reported by the built-in DHCP
2724         server.
2725
2726     ``tftp=dir``
2727         When using the user mode network stack, activate a built-in TFTP
2728         server. The files in dir will be exposed as the root of a TFTP
2729         server. The TFTP client on the guest must be configured in
2730         binary mode (use the command ``bin`` of the Unix TFTP client).
2731
2732     ``tftp-server-name=name``
2733         In BOOTP reply, broadcast name as the "TFTP server name"
2734         (RFC2132 option 66). This can be used to advise the guest to
2735         load boot files or configurations from a different server than
2736         the host address.
2737
2738     ``bootfile=file``
2739         When using the user mode network stack, broadcast file as the
2740         BOOTP filename. In conjunction with ``tftp``, this can be used
2741         to network boot a guest from a local directory.
2742
2743         Example (using pxelinux):
2744
2745         .. parsed-literal::
2746
2747             |qemu_system| -hda linux.img -boot n -device e1000,netdev=n1 \\
2748                 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2749
2750     ``smb=dir[,smbserver=addr]``
2751         When using the user mode network stack, activate a built-in SMB
2752         server so that Windows OSes can access to the host files in
2753         ``dir`` transparently. The IP address of the SMB server can be
2754         set to addr. By default the 4th IP in the guest network is used,
2755         i.e. x.x.x.4.
2756
2757         In the guest Windows OS, the line:
2758
2759         ::
2760
2761             10.0.2.4 smbserver
2762
2763         must be added in the file ``C:\WINDOWS\LMHOSTS`` (for windows
2764         9x/Me) or ``C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS`` (Windows
2765         NT/2000).
2766
2767         Then ``dir`` can be accessed in ``\\smbserver\qemu``.
2768
2769         Note that a SAMBA server must be installed on the host OS.
2770
2771     ``hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport``
2772         Redirect incoming TCP or UDP connections to the host port
2773         hostport to the guest IP address guestaddr on guest port
2774         guestport. If guestaddr is not specified, its value is x.x.x.15
2775         (default first address given by the built-in DHCP server). By
2776         specifying hostaddr, the rule can be bound to a specific host
2777         interface. If no connection type is set, TCP is used. This
2778         option can be given multiple times.
2779
2780         For example, to redirect host X11 connection from screen 1 to
2781         guest screen 0, use the following:
2782
2783         .. parsed-literal::
2784
2785             # on the host
2786             |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2787             # this host xterm should open in the guest X11 server
2788             xterm -display :1
2789
2790         To redirect telnet connections from host port 5555 to telnet
2791         port on the guest, use the following:
2792
2793         .. parsed-literal::
2794
2795             # on the host
2796             |qemu_system| -nic user,hostfwd=tcp::5555-:23
2797             telnet localhost 5555
2798
2799         Then when you use on the host ``telnet localhost 5555``, you
2800         connect to the guest telnet server.
2801
2802     ``guestfwd=[tcp]:server:port-dev``; \ ``guestfwd=[tcp]:server:port-cmd:command``
2803         Forward guest TCP connections to the IP address server on port
2804         port to the character device dev or to a program executed by
2805         cmd:command which gets spawned for each connection. This option
2806         can be given multiple times.
2807
2808         You can either use a chardev directly and have that one used
2809         throughout QEMU's lifetime, like in the following example:
2810
2811         .. parsed-literal::
2812
2813             # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2814             # the guest accesses it
2815             |qemu_system| -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2816
2817         Or you can execute a command on every TCP connection established
2818         by the guest, so that QEMU behaves similar to an inetd process
2819         for that virtual server:
2820
2821         .. parsed-literal::
2822
2823             # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2824             # and connect the TCP stream to its stdin/stdout
2825             |qemu_system| -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2826
2827 ``-netdev tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]``
2828     Configure a host TAP network backend with ID id.
2829
2830     Use the network script file to configure it and the network script
2831     dfile to deconfigure it. If name is not provided, the OS
2832     automatically provides one. The default network configure script is
2833     ``/etc/qemu-ifup`` and the default network deconfigure script is
2834     ``/etc/qemu-ifdown``. Use ``script=no`` or ``downscript=no`` to
2835     disable script execution.
2836
2837     If running QEMU as an unprivileged user, use the network helper
2838     to configure the TAP interface and attach it to the bridge.
2839     The default network helper executable is
2840     ``/path/to/qemu-bridge-helper`` and the default bridge device is
2841     ``br0``.
2842
2843     ``fd``\ =h can be used to specify the handle of an already opened
2844     host TAP interface.
2845
2846     Examples:
2847
2848     .. parsed-literal::
2849
2850         #launch a QEMU instance with the default network script
2851         |qemu_system| linux.img -nic tap
2852
2853     .. parsed-literal::
2854
2855         #launch a QEMU instance with two NICs, each one connected
2856         #to a TAP device
2857         |qemu_system| linux.img \\
2858                 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \\
2859                 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2860
2861     .. parsed-literal::
2862
2863         #launch a QEMU instance with the default network helper to
2864         #connect a TAP device to bridge br0
2865         |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\
2866                 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2867
2868 ``-netdev bridge,id=id[,br=bridge][,helper=helper]``
2869     Connect a host TAP network interface to a host bridge device.
2870
2871     Use the network helper helper to configure the TAP interface and
2872     attach it to the bridge. The default network helper executable is
2873     ``/path/to/qemu-bridge-helper`` and the default bridge device is
2874     ``br0``.
2875
2876     Examples:
2877
2878     .. parsed-literal::
2879
2880         #launch a QEMU instance with the default network helper to
2881         #connect a TAP device to bridge br0
2882         |qemu_system| linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2883
2884     .. parsed-literal::
2885
2886         #launch a QEMU instance with the default network helper to
2887         #connect a TAP device to bridge qemubr0
2888         |qemu_system| linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2889
2890 ``-netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]``
2891     This host network backend can be used to connect the guest's network
2892     to another QEMU virtual machine using a TCP socket connection. If
2893     ``listen`` is specified, QEMU waits for incoming connections on port
2894     (host is optional). ``connect`` is used to connect to another QEMU
2895     instance using the ``listen`` option. ``fd``\ =h specifies an
2896     already opened TCP socket.
2897
2898     Example:
2899
2900     .. parsed-literal::
2901
2902         # launch a first QEMU instance
2903         |qemu_system| linux.img \\
2904                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
2905                          -netdev socket,id=n1,listen=:1234
2906         # connect the network of this instance to the network of the first instance
2907         |qemu_system| linux.img \\
2908                          -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\
2909                          -netdev socket,id=n2,connect=127.0.0.1:1234
2910
2911 ``-netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]``
2912     Configure a socket host network backend to share the guest's network
2913     traffic with another QEMU virtual machines using a UDP multicast
2914     socket, effectively making a bus for every QEMU with same multicast
2915     address maddr and port. NOTES:
2916
2917     1. Several QEMU can be running on different hosts and share same bus
2918        (assuming correct multicast setup for these hosts).
2919
2920     2. mcast support is compatible with User Mode Linux (argument
2921        ``ethN=mcast``), see http://user-mode-linux.sf.net.
2922
2923     3. Use ``fd=h`` to specify an already opened UDP multicast socket.
2924
2925     Example:
2926
2927     .. parsed-literal::
2928
2929         # launch one QEMU instance
2930         |qemu_system| linux.img \\
2931                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
2932                          -netdev socket,id=n1,mcast=230.0.0.1:1234
2933         # launch another QEMU instance on same "bus"
2934         |qemu_system| linux.img \\
2935                          -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\
2936                          -netdev socket,id=n2,mcast=230.0.0.1:1234
2937         # launch yet another QEMU instance on same "bus"
2938         |qemu_system| linux.img \\
2939                          -device e1000,netdev=n3,mac=52:54:00:12:34:58 \\
2940                          -netdev socket,id=n3,mcast=230.0.0.1:1234
2941
2942     Example (User Mode Linux compat.):
2943
2944     .. parsed-literal::
2945
2946         # launch QEMU instance (note mcast address selected is UML's default)
2947         |qemu_system| linux.img \\
2948                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
2949                          -netdev socket,id=n1,mcast=239.192.168.1:1102
2950         # launch UML
2951         /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2952
2953     Example (send packets from host's 1.2.3.4):
2954
2955     .. parsed-literal::
2956
2957         |qemu_system| linux.img \\
2958                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
2959                          -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2960
2961 ``-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]``
2962     Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
2963     is a popular protocol to transport Ethernet (and other Layer 2) data
2964     frames between two systems. It is present in routers, firewalls and
2965     the Linux kernel (from version 3.3 onwards).
2966
2967     This transport allows a VM to communicate to another VM, router or
2968     firewall directly.
2969
2970     ``src=srcaddr``
2971         source address (mandatory)
2972
2973     ``dst=dstaddr``
2974         destination address (mandatory)
2975
2976     ``udp``
2977         select udp encapsulation (default is ip).
2978
2979     ``srcport=srcport``
2980         source udp port.
2981
2982     ``dstport=dstport``
2983         destination udp port.
2984
2985     ``ipv6``
2986         force v6, otherwise defaults to v4.
2987
2988     ``rxcookie=rxcookie``; \ ``txcookie=txcookie``
2989         Cookies are a weak form of security in the l2tpv3 specification.
2990         Their function is mostly to prevent misconfiguration. By default
2991         they are 32 bit.
2992
2993     ``cookie64``
2994         Set cookie size to 64 bit instead of the default 32
2995
2996     ``counter=off``
2997         Force a 'cut-down' L2TPv3 with no counter as in
2998         draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2999
3000     ``pincounter=on``
3001         Work around broken counter handling in peer. This may also help
3002         on networks which have packet reorder.
3003
3004     ``offset=offset``
3005         Add an extra offset between header and data
3006
3007     For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
3008     the bridge br-lan on the remote Linux host 1.2.3.4:
3009
3010     .. parsed-literal::
3011
3012         # Setup tunnel on linux host using raw ip as encapsulation
3013         # on 1.2.3.4
3014         ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \\
3015             encap udp udp_sport 16384 udp_dport 16384
3016         ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \\
3017             0xFFFFFFFF peer_session_id 0xFFFFFFFF
3018         ifconfig vmtunnel0 mtu 1500
3019         ifconfig vmtunnel0 up
3020         brctl addif br-lan vmtunnel0
3021
3022
3023         # on 4.3.2.1
3024         # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
3025
3026         |qemu_system| linux.img -device e1000,netdev=n1 \\
3027             -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
3028
3029 ``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]``
3030     Configure VDE backend to connect to PORT n of a vde switch running
3031     on host and listening for incoming connections on socketpath. Use
3032     GROUP groupname and MODE octalmode to change default ownership and
3033     permissions for communication port. This option is only available if
3034     QEMU has been compiled with vde support enabled.
3035
3036     Example:
3037
3038     .. parsed-literal::
3039
3040         # launch vde switch
3041         vde_switch -F -sock /tmp/myswitch
3042         # launch QEMU instance
3043         |qemu_system| linux.img -nic vde,sock=/tmp/myswitch
3044
3045 ``-netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]``
3046     Establish a vhost-user netdev, backed by a chardev id. The chardev
3047     should be a unix domain socket backed one. The vhost-user uses a
3048     specifically defined protocol to pass vhost ioctl replacement
3049     messages to an application on the other end of the socket. On
3050     non-MSIX guests, the feature can be forced with vhostforce. Use
3051     'queues=n' to specify the number of queues to be created for
3052     multiqueue vhost-user.
3053
3054     Example:
3055
3056     ::
3057
3058         qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
3059              -numa node,memdev=mem \
3060              -chardev socket,id=chr0,path=/path/to/socket \
3061              -netdev type=vhost-user,id=net0,chardev=chr0 \
3062              -device virtio-net-pci,netdev=net0
3063
3064 ``-netdev vhost-vdpa,vhostdev=/path/to/dev``
3065     Establish a vhost-vdpa netdev.
3066
3067     vDPA device is a device that uses a datapath which complies with
3068     the virtio specifications with a vendor specific control path.
3069     vDPA devices can be both physically located on the hardware or
3070     emulated by software.
3071
3072 ``-netdev hubport,id=id,hubid=hubid[,netdev=nd]``
3073     Create a hub port on the emulated hub with ID hubid.
3074
3075     The hubport netdev lets you connect a NIC to a QEMU emulated hub
3076     instead of a single netdev. Alternatively, you can also connect the
3077     hubport to another netdev with ID nd by using the ``netdev=nd``
3078     option.
3079
3080 ``-net nic[,netdev=nd][,macaddr=mac][,model=type] [,name=name][,addr=addr][,vectors=v]``
3081     Legacy option to configure or create an on-board (or machine
3082     default) Network Interface Card(NIC) and connect it either to the
3083     emulated hub with ID 0 (i.e. the default hub), or to the netdev nd.
3084     If model is omitted, then the default NIC model associated with the
3085     machine type is used. Note that the default NIC model may change in
3086     future QEMU releases, so it is highly recommended to always specify
3087     a model. Optionally, the MAC address can be changed to mac, the
3088     device address set to addr (PCI cards only), and a name can be
3089     assigned for use in monitor commands. Optionally, for PCI cards, you
3090     can specify the number v of MSI-X vectors that the card should have;
3091     this option currently only affects virtio cards; set v = 0 to
3092     disable MSI-X. If no ``-net`` option is specified, a single NIC is
3093     created. QEMU can emulate several different models of network card.
3094     Use ``-net nic,model=help`` for a list of available devices for your
3095     target.
3096
3097 ``-net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]``
3098     Configure a host network backend (with the options corresponding to
3099     the same ``-netdev`` option) and connect it to the emulated hub 0
3100     (the default hub). Use name to specify the name of the hub port.
3101 ERST
3102
3103 DEFHEADING()
3104
3105 DEFHEADING(Character device options:)
3106
3107 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
3108     "-chardev help\n"
3109     "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3110     "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off][,reconnect=seconds]\n"
3111     "         [,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]\n"
3112     "         [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
3113     "-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]\n"
3114     "         [,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)\n"
3115     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
3116     "         [,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]\n"
3117     "         [,logfile=PATH][,logappend=on|off]\n"
3118     "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3119     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
3120     "         [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3121     "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
3122     "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3123     "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3124 #ifdef _WIN32
3125     "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3126     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3127 #else
3128     "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3129     "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
3130 #endif
3131 #ifdef CONFIG_BRLAPI
3132     "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3133 #endif
3134 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
3135         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
3136     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3137     "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3138 #endif
3139 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
3140     "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3141     "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3142 #endif
3143 #if defined(CONFIG_SPICE)
3144     "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
3145     "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
3146 #endif
3147     , QEMU_ARCH_ALL
3148 )
3149
3150 SRST
3151 The general form of a character device option is:
3152
3153 ``-chardev backend,id=id[,mux=on|off][,options]``
3154     Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``,
3155     ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``,
3156     ``pty``, ``stdio``, ``braille``, ``tty``, ``parallel``, ``parport``,
3157     ``spicevmc``, ``spiceport``. The specific backend will determine the
3158     applicable options.
3159
3160     Use ``-chardev help`` to print all available chardev backend types.
3161
3162     All devices must have an id, which can be any string up to 127
3163     characters long. It is used to uniquely identify this device in
3164     other command line directives.
3165
3166     A character device may be used in multiplexing mode by multiple
3167     front-ends. Specify ``mux=on`` to enable this mode. A multiplexer is
3168     a "1:N" device, and here the "1" end is your specified chardev
3169     backend, and the "N" end is the various parts of QEMU that can talk
3170     to a chardev. If you create a chardev with ``id=myid`` and
3171     ``mux=on``, QEMU will create a multiplexer with your specified ID,
3172     and you can then configure multiple front ends to use that chardev
3173     ID for their input/output. Up to four different front ends can be
3174     connected to a single multiplexed chardev. (Without multiplexing
3175     enabled, a chardev can only be used by a single front end.) For
3176     instance you could use this to allow a single stdio chardev to be
3177     used by two serial ports and the QEMU monitor:
3178
3179     ::
3180
3181         -chardev stdio,mux=on,id=char0 \
3182         -mon chardev=char0,mode=readline \
3183         -serial chardev:char0 \
3184         -serial chardev:char0
3185
3186     You can have more than one multiplexer in a system configuration;
3187     for instance you could have a TCP port multiplexed between UART 0
3188     and UART 1, and stdio multiplexed between the QEMU monitor and a
3189     parallel port:
3190
3191     ::
3192
3193         -chardev stdio,mux=on,id=char0 \
3194         -mon chardev=char0,mode=readline \
3195         -parallel chardev:char0 \
3196         -chardev tcp,...,mux=on,id=char1 \
3197         -serial chardev:char1 \
3198         -serial chardev:char1
3199
3200     When you're using a multiplexed character device, some escape
3201     sequences are interpreted in the input. See the chapter about
3202     :ref:`keys in the character backend multiplexer` in the
3203     System Emulation Users Guide for more details.
3204
3205     Note that some other command line options may implicitly create
3206     multiplexed character backends; for instance ``-serial mon:stdio``
3207     creates a multiplexed stdio backend connected to the serial port and
3208     the QEMU monitor, and ``-nographic`` also multiplexes the console
3209     and the monitor to stdio.
3210
3211     There is currently no support for multiplexing in the other
3212     direction (where a single QEMU front end takes input and output from
3213     multiple chardevs).
3214
3215     Every backend supports the ``logfile`` option, which supplies the
3216     path to a file to record all data transmitted via the backend. The
3217     ``logappend`` option controls whether the log file will be truncated
3218     or appended to when opened.
3219
3220 The available backends are:
3221
3222 ``-chardev null,id=id``
3223     A void device. This device will not emit any data, and will drop any
3224     data it receives. The null backend does not take any options.
3225
3226 ``-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]``
3227     Create a two-way stream socket, which can be either a TCP or a unix
3228     socket. A unix socket will be created if ``path`` is specified.
3229     Behaviour is undefined if TCP options are specified for a unix
3230     socket.
3231
3232     ``server=on|off`` specifies that the socket shall be a listening socket.
3233
3234     ``wait=on|off`` specifies that QEMU should not block waiting for a client
3235     to connect to a listening socket.
3236
3237     ``telnet=on|off`` specifies that traffic on the socket should interpret
3238     telnet escape sequences.
3239
3240     ``websocket=on|off`` specifies that the socket uses WebSocket protocol for
3241     communication.
3242
3243     ``reconnect`` sets the timeout for reconnecting on non-server
3244     sockets when the remote end goes away. qemu will delay this many
3245     seconds and then attempt to reconnect. Zero disables reconnecting,
3246     and is the default.
3247
3248     ``tls-creds`` requests enablement of the TLS protocol for
3249     encryption, and specifies the id of the TLS credentials to use for
3250     the handshake. The credentials must be previously created with the
3251     ``-object tls-creds`` argument.
3252
3253     ``tls-auth`` provides the ID of the QAuthZ authorization object
3254     against which the client's x509 distinguished name will be
3255     validated. This object is only resolved at time of use, so can be
3256     deleted and recreated on the fly while the chardev server is active.
3257     If missing, it will default to denying access.
3258
3259     TCP and unix socket options are given below:
3260
3261     ``TCP options: port=port[,host=host][,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]``
3262         ``host`` for a listening socket specifies the local address to
3263         be bound. For a connecting socket species the remote host to
3264         connect to. ``host`` is optional for listening sockets. If not
3265         specified it defaults to ``0.0.0.0``.
3266
3267         ``port`` for a listening socket specifies the local port to be
3268         bound. For a connecting socket specifies the port on the remote
3269         host to connect to. ``port`` can be given as either a port
3270         number or a service name. ``port`` is required.
3271
3272         ``to`` is only relevant to listening sockets. If it is
3273         specified, and ``port`` cannot be bound, QEMU will attempt to
3274         bind to subsequent ports up to and including ``to`` until it
3275         succeeds. ``to`` must be specified as a port number.
3276
3277         ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4
3278         or IPv6 must be used. If neither is specified the socket may
3279         use either protocol.
3280
3281         ``nodelay=on|off`` disables the Nagle algorithm.
3282
3283     ``unix options: path=path[,abstract=on|off][,tight=on|off]``
3284         ``path`` specifies the local path of the unix socket. ``path``
3285         is required.
3286         ``abstract=on|off`` specifies the use of the abstract socket namespace,
3287         rather than the filesystem.  Optional, defaults to false.
3288         ``tight=on|off`` sets the socket length of abstract sockets to their minimum,
3289         rather than the full sun_path length.  Optional, defaults to true.
3290
3291 ``-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4=on|off][,ipv6=on|off]``
3292     Sends all traffic from the guest to a remote host over UDP.
3293
3294     ``host`` specifies the remote host to connect to. If not specified
3295     it defaults to ``localhost``.
3296
3297     ``port`` specifies the port on the remote host to connect to.
3298     ``port`` is required.
3299
3300     ``localaddr`` specifies the local address to bind to. If not
3301     specified it defaults to ``0.0.0.0``.
3302
3303     ``localport`` specifies the local port to bind to. If not specified
3304     any available local port will be used.
3305
3306     ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4 or IPv6 must be used.
3307     If neither is specified the device may use either protocol.
3308
3309 ``-chardev msmouse,id=id``
3310     Forward QEMU's emulated msmouse events to the guest. ``msmouse``
3311     does not take any options.
3312
3313 ``-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]``
3314     Connect to a QEMU text console. ``vc`` may optionally be given a
3315     specific size.
3316
3317     ``width`` and ``height`` specify the width and height respectively
3318     of the console, in pixels.
3319
3320     ``cols`` and ``rows`` specify that the console be sized to fit a
3321     text console with the given dimensions.
3322
3323 ``-chardev ringbuf,id=id[,size=size]``
3324     Create a ring buffer with fixed size ``size``. size must be a power
3325     of two and defaults to ``64K``.
3326
3327 ``-chardev file,id=id,path=path``
3328     Log all traffic received from the guest to a file.
3329
3330     ``path`` specifies the path of the file to be opened. This file will
3331     be created if it does not already exist, and overwritten if it does.
3332     ``path`` is required.
3333
3334 ``-chardev pipe,id=id,path=path``
3335     Create a two-way connection to the guest. The behaviour differs
3336     slightly between Windows hosts and other hosts:
3337
3338     On Windows, a single duplex pipe will be created at
3339     ``\\.pipe\path``.
3340
3341     On other hosts, 2 pipes will be created called ``path.in`` and
3342     ``path.out``. Data written to ``path.in`` will be received by the
3343     guest. Data written by the guest can be read from ``path.out``. QEMU
3344     will not create these fifos, and requires them to be present.
3345
3346     ``path`` forms part of the pipe path as described above. ``path`` is
3347     required.
3348
3349 ``-chardev console,id=id``
3350     Send traffic from the guest to QEMU's standard output. ``console``
3351     does not take any options.
3352
3353     ``console`` is only available on Windows hosts.
3354
3355 ``-chardev serial,id=id,path=path``
3356     Send traffic from the guest to a serial device on the host.
3357
3358     On Unix hosts serial will actually accept any tty device, not only
3359     serial lines.
3360
3361     ``path`` specifies the name of the serial device to open.
3362
3363 ``-chardev pty,id=id``
3364     Create a new pseudo-terminal on the host and connect to it. ``pty``
3365     does not take any options.
3366
3367     ``pty`` is not available on Windows hosts.
3368
3369 ``-chardev stdio,id=id[,signal=on|off]``
3370     Connect to standard input and standard output of the QEMU process.
3371
3372     ``signal`` controls if signals are enabled on the terminal, that
3373     includes exiting QEMU with the key sequence Control-c. This option
3374     is enabled by default, use ``signal=off`` to disable it.
3375
3376 ``-chardev braille,id=id``
3377     Connect to a local BrlAPI server. ``braille`` does not take any
3378     options.
3379
3380 ``-chardev tty,id=id,path=path``
3381     ``tty`` is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD
3382     and DragonFlyBSD hosts. It is an alias for ``serial``.
3383
3384     ``path`` specifies the path to the tty. ``path`` is required.
3385
3386 ``-chardev parallel,id=id,path=path``
3387   \
3388 ``-chardev parport,id=id,path=path``
3389     ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD
3390     hosts.
3391
3392     Connect to a local parallel port.
3393
3394     ``path`` specifies the path to the parallel port device. ``path`` is
3395     required.
3396
3397 ``-chardev spicevmc,id=id,debug=debug,name=name``
3398     ``spicevmc`` is only available when spice support is built in.
3399
3400     ``debug`` debug level for spicevmc
3401
3402     ``name`` name of spice channel to connect to
3403
3404     Connect to a spice virtual machine channel, such as vdiport.
3405
3406 ``-chardev spiceport,id=id,debug=debug,name=name``
3407     ``spiceport`` is only available when spice support is built in.
3408
3409     ``debug`` debug level for spicevmc
3410
3411     ``name`` name of spice port to connect to
3412
3413     Connect to a spice port, allowing a Spice client to handle the
3414     traffic identified by a name (preferably a fqdn).
3415 ERST
3416
3417 DEFHEADING()
3418
3419 #ifdef CONFIG_TPM
3420 DEFHEADING(TPM device options:)
3421
3422 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3423     "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3424     "                use path to provide path to a character device; default is /dev/tpm0\n"
3425     "                use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3426     "                not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3427     "-tpmdev emulator,id=id,chardev=dev\n"
3428     "                configure the TPM device using chardev backend\n",
3429     QEMU_ARCH_ALL)
3430 SRST
3431 The general form of a TPM device option is:
3432
3433 ``-tpmdev backend,id=id[,options]``
3434     The specific backend type will determine the applicable options. The
3435     ``-tpmdev`` option creates the TPM backend and requires a
3436     ``-device`` option that specifies the TPM frontend interface model.
3437
3438     Use ``-tpmdev help`` to print all available TPM backend types.
3439
3440 The available backends are:
3441
3442 ``-tpmdev passthrough,id=id,path=path,cancel-path=cancel-path``
3443     (Linux-host only) Enable access to the host's TPM using the
3444     passthrough driver.
3445
3446     ``path`` specifies the path to the host's TPM device, i.e., on a
3447     Linux host this would be ``/dev/tpm0``. ``path`` is optional and by
3448     default ``/dev/tpm0`` is used.
3449
3450     ``cancel-path`` specifies the path to the host TPM device's sysfs
3451     entry allowing for cancellation of an ongoing TPM command.
3452     ``cancel-path`` is optional and by default QEMU will search for the
3453     sysfs entry to use.
3454
3455     Some notes about using the host's TPM with the passthrough driver:
3456
3457     The TPM device accessed by the passthrough driver must not be used
3458     by any other application on the host.
3459
3460     Since the host's firmware (BIOS/UEFI) has already initialized the
3461     TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
3462     the TPM again and may therefore not show a TPM-specific menu that
3463     would otherwise allow the user to configure the TPM, e.g., allow the
3464     user to enable/disable or activate/deactivate the TPM. Further, if
3465     TPM ownership is released from within a VM then the host's TPM will
3466     get disabled and deactivated. To enable and activate the TPM again
3467     afterwards, the host has to be rebooted and the user is required to
3468     enter the firmware's menu to enable and activate the TPM. If the TPM
3469     is left disabled and/or deactivated most TPM commands will fail.
3470
3471     To create a passthrough TPM use the following two options:
3472
3473     ::
3474
3475         -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3476
3477     Note that the ``-tpmdev`` id is ``tpm0`` and is referenced by
3478     ``tpmdev=tpm0`` in the device option.
3479
3480 ``-tpmdev emulator,id=id,chardev=dev``
3481     (Linux-host only) Enable access to a TPM emulator using Unix domain
3482     socket based chardev backend.
3483
3484     ``chardev`` specifies the unique ID of a character device backend
3485     that provides connection to the software TPM server.
3486
3487     To create a TPM emulator backend device with chardev socket backend:
3488
3489     ::
3490
3491         -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3492 ERST
3493
3494 DEFHEADING()
3495
3496 #endif
3497
3498 DEFHEADING(Linux/Multiboot boot specific:)
3499 SRST
3500 When using these options, you can use a given Linux or Multiboot kernel
3501 without installing it in the disk image. It can be useful for easier
3502 testing of various kernels.
3503
3504
3505 ERST
3506
3507 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3508     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3509 SRST
3510 ``-kernel bzImage``
3511     Use bzImage as kernel image. The kernel can be either a Linux kernel
3512     or in multiboot format.
3513 ERST
3514
3515 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3516     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3517 SRST
3518 ``-append cmdline``
3519     Use cmdline as kernel command line
3520 ERST
3521
3522 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3523            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3524 SRST
3525 ``-initrd file``
3526     Use file as initial ram disk.
3527
3528 ``-initrd "file1 arg=foo,file2"``
3529     This syntax is only available with multiboot.
3530
3531     Use file1 and file2 as modules and pass arg=foo as parameter to the
3532     first module.
3533 ERST
3534
3535 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3536     "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
3537 SRST
3538 ``-dtb file``
3539     Use file as a device tree binary (dtb) image and pass it to the
3540     kernel on boot.
3541 ERST
3542
3543 DEFHEADING()
3544
3545 DEFHEADING(Debug/Expert options:)
3546
3547 DEF("compat", HAS_ARG, QEMU_OPTION_compat,
3548     "-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]\n"
3549     "                Policy for handling deprecated management interfaces\n",
3550     QEMU_ARCH_ALL)
3551 SRST
3552 ``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
3553     Set policy for handling deprecated management interfaces (experimental):
3554
3555     ``deprecated-input=accept`` (default)
3556         Accept deprecated commands and arguments
3557     ``deprecated-input=reject``
3558         Reject deprecated commands and arguments
3559     ``deprecated-input=crash``
3560         Crash on deprecated commands and arguments
3561     ``deprecated-output=accept`` (default)
3562         Emit deprecated command results and events
3563     ``deprecated-output=hide``
3564         Suppress deprecated command results and events
3565
3566     Limitation: covers only syntactic aspects of QMP.
3567 ERST
3568
3569 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3570     "-fw_cfg [name=]<name>,file=<file>\n"
3571     "                add named fw_cfg entry with contents from file\n"
3572     "-fw_cfg [name=]<name>,string=<str>\n"
3573     "                add named fw_cfg entry with contents from string\n",
3574     QEMU_ARCH_ALL)
3575 SRST
3576 ``-fw_cfg [name=]name,file=file``
3577     Add named fw\_cfg entry with contents from file file.
3578
3579 ``-fw_cfg [name=]name,string=str``
3580     Add named fw\_cfg entry with contents from string str.
3581
3582     The terminating NUL character of the contents of str will not be
3583     included as part of the fw\_cfg item data. To insert contents with
3584     embedded NUL characters, you have to use the file parameter.
3585
3586     The fw\_cfg entries are passed by QEMU through to the guest.
3587
3588     Example:
3589
3590     ::
3591
3592             -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3593
3594     creates an fw\_cfg entry named opt/com.mycompany/blob with contents
3595     from ./my\_blob.bin.
3596 ERST
3597
3598 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3599     "-serial dev     redirect the serial port to char device 'dev'\n",
3600     QEMU_ARCH_ALL)
3601 SRST
3602 ``-serial dev``
3603     Redirect the virtual serial port to host character device dev. The
3604     default device is ``vc`` in graphical mode and ``stdio`` in non
3605     graphical mode.
3606
3607     This option can be used several times to simulate up to 4 serial
3608     ports.
3609
3610     Use ``-serial none`` to disable all serial ports.
3611
3612     Available character devices are:
3613
3614     ``vc[:WxH]``
3615         Virtual console. Optionally, a width and height can be given in
3616         pixel with
3617
3618         ::
3619
3620             vc:800x600
3621
3622         It is also possible to specify width or height in characters:
3623
3624         ::
3625
3626             vc:80Cx24C
3627
3628     ``pty``
3629         [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3630
3631     ``none``
3632         No device is allocated.
3633
3634     ``null``
3635         void device
3636
3637     ``chardev:id``
3638         Use a named character device defined with the ``-chardev``
3639         option.
3640
3641     ``/dev/XXX``
3642         [Linux only] Use host tty, e.g. ``/dev/ttyS0``. The host serial
3643         port parameters are set according to the emulated ones.
3644
3645     ``/dev/parportN``
3646         [Linux only, parallel port only] Use host parallel port N.
3647         Currently SPP and EPP parallel port features can be used.
3648
3649     ``file:filename``
3650         Write output to filename. No character can be read.
3651
3652     ``stdio``
3653         [Unix only] standard input/output
3654
3655     ``pipe:filename``
3656         name pipe filename
3657
3658     ``COMn``
3659         [Windows only] Use host serial port n
3660
3661     ``udp:[remote_host]:remote_port[@[src_ip]:src_port]``
3662         This implements UDP Net Console. When remote\_host or src\_ip
3663         are not specified they default to ``0.0.0.0``. When not using a
3664         specified src\_port a random port is automatically chosen.
3665
3666         If you just want a simple readonly console you can use
3667         ``netcat`` or ``nc``, by starting QEMU with:
3668         ``-serial udp::4555`` and nc as: ``nc -u -l -p 4555``. Any time
3669         QEMU writes something to that port it will appear in the
3670         netconsole session.
3671
3672         If you plan to send characters back via netconsole or you want
3673         to stop and start QEMU a lot of times, you should have QEMU use
3674         the same source port each time by using something like ``-serial
3675         udp::4555@:4556`` to QEMU. Another approach is to use a patched
3676         version of netcat which can listen to a TCP port and send and
3677         receive characters via udp. If you have a patched version of
3678         netcat which activates telnet remote echo and single char
3679         transfer, then you can use the following options to set up a
3680         netcat redirector to allow telnet on port 5555 to access the
3681         QEMU port.
3682
3683         ``QEMU Options:``
3684             -serial udp::4555@:4556
3685
3686         ``netcat options:``
3687             -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3688
3689         ``telnet options:``
3690             localhost 5555
3691
3692     ``tcp:[host]:port[,server=on|off][,wait=on|off][,nodelay=on|off][,reconnect=seconds]``
3693         The TCP Net Console has two modes of operation. It can send the
3694         serial I/O to a location or wait for a connection from a
3695         location. By default the TCP Net Console is sent to host at the
3696         port. If you use the ``server=on`` option QEMU will wait for a client
3697         socket application to connect to the port before continuing,
3698         unless the ``wait=on|off`` option was specified. The ``nodelay=on|off``
3699         option disables the Nagle buffering algorithm. The ``reconnect=on``
3700         option only applies if ``server=no`` is set, if the connection goes
3701         down it will attempt to reconnect at the given interval. If host
3702         is omitted, 0.0.0.0 is assumed. Only one TCP connection at a
3703         time is accepted. You can use ``telnet=on`` to connect to the
3704         corresponding character device.
3705
3706         ``Example to send tcp console to 192.168.0.2 port 4444``
3707             -serial tcp:192.168.0.2:4444
3708
3709         ``Example to listen and wait on port 4444 for connection``
3710             -serial tcp::4444,server=on
3711
3712         ``Example to not wait and listen on ip 192.168.0.100 port 4444``
3713             -serial tcp:192.168.0.100:4444,server=on,wait=off
3714
3715     ``telnet:host:port[,server=on|off][,wait=on|off][,nodelay=on|off]``
3716         The telnet protocol is used instead of raw tcp sockets. The
3717         options work the same as if you had specified ``-serial tcp``.
3718         The difference is that the port acts like a telnet server or
3719         client using telnet option negotiation. This will also allow you
3720         to send the MAGIC\_SYSRQ sequence if you use a telnet that
3721         supports sending the break sequence. Typically in unix telnet
3722         you do it with Control-] and then type "send break" followed by
3723         pressing the enter key.
3724
3725     ``websocket:host:port,server=on[,wait=on|off][,nodelay=on|off]``
3726         The WebSocket protocol is used instead of raw tcp socket. The
3727         port acts as a WebSocket server. Client mode is not supported.
3728
3729     ``unix:path[,server=on|off][,wait=on|off][,reconnect=seconds]``
3730         A unix domain socket is used instead of a tcp socket. The option
3731         works the same as if you had specified ``-serial tcp`` except
3732         the unix domain socket path is used for connections.
3733
3734     ``mon:dev_string``
3735         This is a special option to allow the monitor to be multiplexed
3736         onto another serial port. The monitor is accessed with key
3737         sequence of Control-a and then pressing c. dev\_string should be
3738         any one of the serial devices specified above. An example to
3739         multiplex the monitor onto a telnet server listening on port
3740         4444 would be:
3741
3742         ``-serial mon:telnet::4444,server=on,wait=off``
3743
3744         When the monitor is multiplexed to stdio in this way, Ctrl+C
3745         will not terminate QEMU any more but will be passed to the guest
3746         instead.
3747
3748     ``braille``
3749         Braille device. This will use BrlAPI to display the braille
3750         output on a real or fake device.
3751
3752     ``msmouse``
3753         Three button serial mouse. Configure the guest to use Microsoft
3754         protocol.
3755 ERST
3756
3757 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3758     "-parallel dev   redirect the parallel port to char device 'dev'\n",
3759     QEMU_ARCH_ALL)
3760 SRST
3761 ``-parallel dev``
3762     Redirect the virtual parallel port to host device dev (same devices
3763     as the serial port). On Linux hosts, ``/dev/parportN`` can be used
3764     to use hardware devices connected on the corresponding host parallel
3765     port.
3766
3767     This option can be used several times to simulate up to 3 parallel
3768     ports.
3769
3770     Use ``-parallel none`` to disable all parallel ports.
3771 ERST
3772
3773 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3774     "-monitor dev    redirect the monitor to char device 'dev'\n",
3775     QEMU_ARCH_ALL)
3776 SRST
3777 ``-monitor dev``
3778     Redirect the monitor to host device dev (same devices as the serial
3779     port). The default device is ``vc`` in graphical mode and ``stdio``
3780     in non graphical mode. Use ``-monitor none`` to disable the default
3781     monitor.
3782 ERST
3783 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3784     "-qmp dev        like -monitor but opens in 'control' mode\n",
3785     QEMU_ARCH_ALL)
3786 SRST
3787 ``-qmp dev``
3788     Like -monitor but opens in 'control' mode.
3789 ERST
3790 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3791     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3792     QEMU_ARCH_ALL)
3793 SRST
3794 ``-qmp-pretty dev``
3795     Like -qmp but uses pretty JSON formatting.
3796 ERST
3797
3798 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3799     "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
3800 SRST
3801 ``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
3802     Setup monitor on chardev name. ``mode=control`` configures 
3803     a QMP monitor (a JSON RPC-style protocol) and it is not the
3804     same as HMP, the human monitor that has a "(qemu)" prompt.
3805     ``pretty`` is only valid when ``mode=control``, 
3806     turning on JSON pretty printing to ease
3807     human reading and debugging.
3808 ERST
3809
3810 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3811     "-debugcon dev   redirect the debug console to char device 'dev'\n",
3812     QEMU_ARCH_ALL)
3813 SRST
3814 ``-debugcon dev``
3815     Redirect the debug console to host device dev (same devices as the
3816     serial port). The debug console is an I/O port which is typically
3817     port 0xe9; writing to that I/O port sends output to this device. The
3818     default device is ``vc`` in graphical mode and ``stdio`` in non
3819     graphical mode.
3820 ERST
3821
3822 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3823     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
3824 SRST
3825 ``-pidfile file``
3826     Store the QEMU process PID in file. It is useful if you launch QEMU
3827     from a script.
3828 ERST
3829
3830 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3831     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
3832 SRST
3833 ``-singlestep``
3834     Run the emulation in single step mode.
3835 ERST
3836
3837 DEF("preconfig", 0, QEMU_OPTION_preconfig, \
3838     "--preconfig     pause QEMU before machine is initialized (experimental)\n",
3839     QEMU_ARCH_ALL)
3840 SRST
3841 ``--preconfig``
3842     Pause QEMU for interactive configuration before the machine is
3843     created, which allows querying and configuring properties that will
3844     affect machine initialization. Use QMP command 'x-exit-preconfig' to
3845     exit the preconfig state and move to the next state (i.e. run guest
3846     if -S isn't used or pause the second time if -S is used). This
3847     option is experimental.
3848 ERST
3849
3850 DEF("S", 0, QEMU_OPTION_S, \
3851     "-S              freeze CPU at startup (use 'c' to start execution)\n",
3852     QEMU_ARCH_ALL)
3853 SRST
3854 ``-S``
3855     Do not start CPU at startup (you must type 'c' in the monitor).
3856 ERST
3857
3858 DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
3859     "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
3860     "                run qemu with overcommit hints\n"
3861     "                mem-lock=on|off controls memory lock support (default: off)\n"
3862     "                cpu-pm=on|off controls cpu power management (default: off)\n",
3863     QEMU_ARCH_ALL)
3864 SRST
3865 ``-overcommit mem-lock=on|off``
3866   \ 
3867 ``-overcommit cpu-pm=on|off``
3868     Run qemu with hints about host resource overcommit. The default is
3869     to assume that host overcommits all resources.
3870
3871     Locking qemu and guest memory can be enabled via ``mem-lock=on``
3872     (disabled by default). This works when host memory is not
3873     overcommitted and reduces the worst-case latency for guest.
3874
3875     Guest ability to manage power state of host cpus (increasing latency
3876     for other processes on the same host cpu, but decreasing latency for
3877     guest) can be enabled via ``cpu-pm=on`` (disabled by default). This
3878     works best when host CPU is not overcommitted. When used, host
3879     estimates of CPU cycle and power utilization will be incorrect, not
3880     taking into account guest idle time.
3881 ERST
3882
3883 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3884     "-gdb dev        accept gdb connection on 'dev'. (QEMU defaults to starting\n"
3885     "                the guest without waiting for gdb to connect; use -S too\n"
3886     "                if you want it to not start execution.)\n",
3887     QEMU_ARCH_ALL)
3888 SRST
3889 ``-gdb dev``
3890     Accept a gdb connection on device dev (see the :ref:`GDB usage` chapter
3891     in the System Emulation Users Guide). Note that this option does not pause QEMU
3892     execution -- if you want QEMU to not start the guest until you
3893     connect with gdb and issue a ``continue`` command, you will need to
3894     also pass the ``-S`` option to QEMU.
3895
3896     The most usual configuration is to listen on a local TCP socket::
3897
3898         -gdb tcp::3117
3899
3900     but you can specify other backends; UDP, pseudo TTY, or even stdio
3901     are all reasonable use cases. For example, a stdio connection
3902     allows you to start QEMU from within gdb and establish the
3903     connection via a pipe:
3904
3905     .. parsed-literal::
3906
3907         (gdb) target remote | exec |qemu_system| -gdb stdio ...
3908 ERST
3909
3910 DEF("s", 0, QEMU_OPTION_s, \
3911     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3912     QEMU_ARCH_ALL)
3913 SRST
3914 ``-s``
3915     Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3916     (see the :ref:`GDB usage` chapter in the System Emulation Users Guide).
3917 ERST
3918
3919 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3920     "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
3921     QEMU_ARCH_ALL)
3922 SRST
3923 ``-d item1[,...]``
3924     Enable logging of specified items. Use '-d help' for a list of log
3925     items.
3926 ERST
3927
3928 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3929     "-D logfile      output log to logfile (default stderr)\n",
3930     QEMU_ARCH_ALL)
3931 SRST
3932 ``-D logfile``
3933     Output log in logfile instead of to stderr
3934 ERST
3935
3936 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3937     "-dfilter range,..  filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3938     QEMU_ARCH_ALL)
3939 SRST
3940 ``-dfilter range1[,...]``
3941     Filter debug output to that relevant to a range of target addresses.
3942     The filter spec can be either start+size, start-size or start..end
3943     where start end and size are the addresses and sizes required. For
3944     example:
3945
3946     ::
3947
3948             -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3949
3950     Will dump output for any code in the 0x1000 sized block starting at
3951     0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and
3952     another 0x1000 sized block starting at 0xffffffc00005f000.
3953 ERST
3954
3955 DEF("seed", HAS_ARG, QEMU_OPTION_seed, \
3956     "-seed number       seed the pseudo-random number generator\n",
3957     QEMU_ARCH_ALL)
3958 SRST
3959 ``-seed number``
3960     Force the guest to use a deterministic pseudo-random number
3961     generator, seeded with number. This does not affect crypto routines
3962     within the host.
3963 ERST
3964
3965 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3966     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
3967     QEMU_ARCH_ALL)
3968 SRST
3969 ``-L  path``
3970     Set the directory for the BIOS, VGA BIOS and keymaps.
3971
3972     To list all the data directories, use ``-L help``.
3973 ERST
3974
3975 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3976     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
3977 SRST
3978 ``-bios file``
3979     Set the filename for the BIOS.
3980 ERST
3981
3982 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3983     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3984 SRST
3985 ``-enable-kvm``
3986     Enable KVM full virtualization support. This option is only
3987     available if KVM support is enabled when compiling.
3988 ERST
3989
3990 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3991     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
3992 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3993     "-xen-attach     attach to existing xen domain\n"
3994     "                libxl will use this when starting QEMU\n",
3995     QEMU_ARCH_ALL)
3996 DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3997     "-xen-domid-restrict     restrict set of available xen operations\n"
3998     "                        to specified domain id. (Does not affect\n"
3999     "                        xenpv machine type).\n",
4000     QEMU_ARCH_ALL)
4001 SRST
4002 ``-xen-domid id``
4003     Specify xen guest domain id (XEN only).
4004
4005 ``-xen-attach``
4006     Attach to existing xen domain. libxl will use this when starting
4007     QEMU (XEN only). Restrict set of available xen operations to
4008     specified domain id (XEN only).
4009 ERST
4010
4011 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
4012     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
4013 SRST
4014 ``-no-reboot``
4015     Exit instead of rebooting.
4016 ERST
4017
4018 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
4019     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
4020 SRST
4021 ``-no-shutdown``
4022     Don't exit QEMU on guest shutdown, but instead only stop the
4023     emulation. This allows for instance switching to monitor to commit
4024     changes to the disk image.
4025 ERST
4026
4027 DEF("action", HAS_ARG, QEMU_OPTION_action,
4028     "-action reboot=reset|shutdown\n"
4029     "                   action when guest reboots [default=reset]\n"
4030     "-action shutdown=poweroff|pause\n"
4031     "                   action when guest shuts down [default=poweroff]\n"
4032     "-action panic=pause|shutdown|none\n"
4033     "                   action when guest panics [default=shutdown]\n"
4034     "-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none\n"
4035     "                   action when watchdog fires [default=reset]\n",
4036     QEMU_ARCH_ALL)
4037 SRST
4038 ``-action event=action``
4039     The action parameter serves to modify QEMU's default behavior when
4040     certain guest events occur. It provides a generic method for specifying the
4041     same behaviors that are modified by the ``-no-reboot`` and ``-no-shutdown``
4042     parameters.
4043
4044     Examples:
4045
4046     ``-action panic=none``
4047     ``-action reboot=shutdown,shutdown=pause``
4048     ``-watchdog i6300esb -action watchdog=pause``
4049
4050 ERST
4051
4052 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
4053     "-loadvm [tag|id]\n" \
4054     "                start right away with a saved state (loadvm in monitor)\n",
4055     QEMU_ARCH_ALL)
4056 SRST
4057 ``-loadvm file``
4058     Start right away with a saved state (``loadvm`` in monitor)
4059 ERST
4060
4061 #ifndef _WIN32
4062 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
4063     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
4064 #endif
4065 SRST
4066 ``-daemonize``
4067     Daemonize the QEMU process after initialization. QEMU will not
4068     detach from standard IO until it is ready to receive connections on
4069     any of its devices. This option is a useful way for external
4070     programs to launch QEMU without having to cope with initialization
4071     race conditions.
4072 ERST
4073
4074 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
4075     "-option-rom rom load a file, rom, into the option ROM space\n",
4076     QEMU_ARCH_ALL)
4077 SRST
4078 ``-option-rom file``
4079     Load the contents of file as an option ROM. This option is useful to
4080     load things like EtherBoot.
4081 ERST
4082
4083 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
4084     "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
4085     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
4086     QEMU_ARCH_ALL)
4087
4088 SRST
4089 ``-rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]``
4090     Specify ``base`` as ``utc`` or ``localtime`` to let the RTC start at
4091     the current UTC or local time, respectively. ``localtime`` is
4092     required for correct date in MS-DOS or Windows. To start at a
4093     specific point in time, provide datetime in the format
4094     ``2006-06-17T16:01:21`` or ``2006-06-17``. The default base is UTC.
4095
4096     By default the RTC is driven by the host system time. This allows
4097     using of the RTC as accurate reference clock inside the guest,
4098     specifically if the host time is smoothly following an accurate
4099     external reference clock, e.g. via NTP. If you want to isolate the
4100     guest time from the host, you can set ``clock`` to ``rt`` instead,
4101     which provides a host monotonic clock if host support it. To even
4102     prevent the RTC from progressing during suspension, you can set
4103     ``clock`` to ``vm`` (virtual clock). '\ ``clock=vm``\ ' is
4104     recommended especially in icount mode in order to preserve
4105     determinism; however, note that in icount mode the speed of the
4106     virtual clock is variable and can in general differ from the host
4107     clock.
4108
4109     Enable ``driftfix`` (i386 targets only) if you experience time drift
4110     problems, specifically with Windows' ACPI HAL. This option will try
4111     to figure out how many timer interrupts were not processed by the
4112     Windows guest and will re-inject them.
4113 ERST
4114
4115 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
4116     "-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]\n" \
4117     "                enable virtual instruction counter with 2^N clock ticks per\n" \
4118     "                instruction, enable aligning the host and virtual clocks\n" \
4119     "                or disable real time cpu sleeping, and optionally enable\n" \
4120     "                record-and-replay mode\n", QEMU_ARCH_ALL)
4121 SRST
4122 ``-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=filename[,rrsnapshot=snapshot]]``
4123     Enable virtual instruction counter. The virtual cpu will execute one
4124     instruction every 2^N ns of virtual time. If ``auto`` is specified
4125     then the virtual cpu speed will be automatically adjusted to keep
4126     virtual time within a few seconds of real time.
4127
4128     Note that while this option can give deterministic behavior, it does
4129     not provide cycle accurate emulation. Modern CPUs contain
4130     superscalar out of order cores with complex cache hierarchies. The
4131     number of instructions executed often has little or no correlation
4132     with actual performance.
4133
4134     When the virtual cpu is sleeping, the virtual time will advance at
4135     default speed unless ``sleep=on`` is specified. With
4136     ``sleep=on``, the virtual time will jump to the next timer
4137     deadline instantly whenever the virtual cpu goes to sleep mode and
4138     will not advance if no timer is enabled. This behavior gives
4139     deterministic execution times from the guest point of view.
4140     The default if icount is enabled is ``sleep=off``.
4141     ``sleep=on`` cannot be used together with either ``shift=auto``
4142     or ``align=on``.
4143
4144     ``align=on`` will activate the delay algorithm which will try to
4145     synchronise the host clock and the virtual clock. The goal is to
4146     have a guest running at the real frequency imposed by the shift
4147     option. Whenever the guest clock is behind the host clock and if
4148     ``align=on`` is specified then we print a message to the user to
4149     inform about the delay. Currently this option does not work when
4150     ``shift`` is ``auto``. Note: The sync algorithm will work for those
4151     shift values for which the guest clock runs ahead of the host clock.
4152     Typically this happens when the shift value is high (how high
4153     depends on the host machine). The default if icount is enabled
4154     is ``align=off``.