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