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