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