]>
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" |
f844cdb9 | 2090 | #endif |
88b40c68 TH |
2091 | #if defined(CONFIG_OPENGL) |
2092 | "-display egl-headless[,rendernode=<file>]\n" | |
142ca628 MAL |
2093 | #endif |
2094 | #if defined(CONFIG_DBUS_DISPLAY) | |
2095 | "-display dbus[,addr=<dbusaddr>]\n" | |
2096 | " [,gl=on|core|es|off][,rendernode=<file>]\n" | |
48941a52 CE |
2097 | #endif |
2098 | #if defined(CONFIG_COCOA) | |
2099 | "-display cocoa[,show-cursor=on|off][,left-command-key=on|off]\n" | |
88b40c68 | 2100 | #endif |
144aaa99 | 2101 | "-display none\n" |
88b40c68 TH |
2102 | " select display backend type\n" |
2103 | " The default display is equivalent to\n " | |
f04ec5af | 2104 | #if defined(CONFIG_GTK) |
88b40c68 | 2105 | "\"-display gtk\"\n" |
f04ec5af | 2106 | #elif defined(CONFIG_SDL) |
88b40c68 | 2107 | "\"-display sdl\"\n" |
f04ec5af | 2108 | #elif defined(CONFIG_COCOA) |
88b40c68 | 2109 | "\"-display cocoa\"\n" |
f04ec5af | 2110 | #elif defined(CONFIG_VNC) |
88b40c68 | 2111 | "\"-vnc localhost:0,to=99,id=default\"\n" |
f04ec5af | 2112 | #else |
88b40c68 | 2113 | "\"-display none\"\n" |
f04ec5af RH |
2114 | #endif |
2115 | , QEMU_ARCH_ALL) | |
e2fcbf42 PM |
2116 | SRST |
2117 | ``-display type`` | |
707d93d4 TH |
2118 | Select type of display to use. Use ``-display help`` to list the available |
2119 | display types. Valid values for type are | |
e2fcbf42 | 2120 | |
ddc71758 AA |
2121 | ``spice-app[,gl=on|off]`` |
2122 | Start QEMU as a Spice server and launch the default Spice client | |
2123 | application. The Spice server will redirect the serial consoles | |
2124 | and QEMU monitors. (Since 4.0) | |
2125 | ||
142ca628 MAL |
2126 | ``dbus`` |
2127 | Export the display over D-Bus interfaces. (Since 7.0) | |
2128 | ||
2129 | The connection is registered with the "org.qemu" name (and queued when | |
2130 | already owned). | |
2131 | ||
2132 | ``addr=<dbusaddr>`` : D-Bus bus address to connect to. | |
2133 | ||
99997823 MAL |
2134 | ``p2p=yes|no`` : Use peer-to-peer connection, accepted via QMP ``add_client``. |
2135 | ||
2136 | ``gl=on|off|core|es`` : Use OpenGL for rendering (the D-Bus interface | |
2137 | will share framebuffers with DMABUF file descriptors). | |
142ca628 | 2138 | |
95f439bd | 2139 | ``sdl`` |
e2fcbf42 PM |
2140 | Display video output via SDL (usually in a separate graphics |
2141 | window; see the SDL documentation for other possibilities). | |
95f439bd TH |
2142 | Valid parameters are: |
2143 | ||
8e8e844b | 2144 | ``grab-mod=<mods>`` : Used to select the modifier keys for toggling |
450e0f28 JS |
2145 | the mouse grabbing in conjunction with the "g" key. ``<mods>`` can be |
2146 | either ``lshift-lctrl-lalt`` or ``rctrl``. | |
8e8e844b | 2147 | |
95f439bd | 2148 | ``gl=on|off|core|es`` : Use OpenGL for displaying |
e2fcbf42 | 2149 | |
95f439bd TH |
2150 | ``show-cursor=on|off`` : Force showing the mouse cursor |
2151 | ||
2152 | ``window-close=on|off`` : Allow to quit qemu with window close button | |
2153 | ||
2154 | ``gtk`` | |
ddc71758 AA |
2155 | Display video output in a GTK window. This interface provides |
2156 | drop-down menus and other UI elements to configure and control | |
95f439bd TH |
2157 | the VM during runtime. Valid parameters are: |
2158 | ||
2159 | ``full-screen=on|off`` : Start in fullscreen mode | |
2160 | ||
2161 | ``gl=on|off`` : Use OpenGL for displaying | |
ddc71758 | 2162 | |
95f439bd TH |
2163 | ``grab-on-hover=on|off`` : Grab keyboard input on mouse hover |
2164 | ||
c34a9338 FQ |
2165 | ``show-tabs=on|off`` : Display the tab bar for switching between the |
2166 | various graphical interfaces (e.g. VGA and | |
2167 | virtual console character devices) by default. | |
2168 | ||
95f439bd TH |
2169 | ``show-cursor=on|off`` : Force showing the mouse cursor |
2170 | ||
2171 | ``window-close=on|off`` : Allow to quit qemu with window close button | |
2172 | ||
dbccb1a5 BM |
2173 | ``show-menubar=on|off`` : Display the main window menubar, defaults to "on" |
2174 | ||
c35d9373 JK |
2175 | ``zoom-to-fit=on|off`` : Expand video output to the window size, |
2176 | defaults to "off" | |
2177 | ||
95f439bd | 2178 | ``curses[,charset=<encoding>]`` |
e2fcbf42 PM |
2179 | Display video output via curses. For graphics device models |
2180 | which support a text mode, QEMU can display this output using a | |
2181 | curses/ncurses interface. Nothing is displayed when the graphics | |
2182 | device is in graphical mode or if the graphics device does not | |
2183 | support a text mode. Generally only the VGA device models | |
2184 | support text mode. The font charset used by the guest can be | |
2185 | specified with the ``charset`` option, for example | |
2186 | ``charset=CP850`` for IBM CP850 encoding. The default is | |
2187 | ``CP437``. | |
2188 | ||
48941a52 CE |
2189 | ``cocoa`` |
2190 | Display video output in a Cocoa window. Mac only. This interface | |
2191 | provides drop-down menus and other UI elements to configure and | |
2192 | control the VM during runtime. Valid parameters are: | |
2193 | ||
2194 | ``show-cursor=on|off`` : Force showing the mouse cursor | |
2195 | ||
2196 | ``left-command-key=on|off`` : Disable forwarding left command key to host | |
2197 | ||
95f439bd | 2198 | ``egl-headless[,rendernode=<file>]`` |
ddc71758 AA |
2199 | Offload all OpenGL operations to a local DRI device. For any |
2200 | graphical display, this display needs to be paired with either | |
2201 | VNC or SPICE displays. | |
2202 | ||
95f439bd TH |
2203 | ``vnc=<display>`` |
2204 | Start a VNC server on display <display> | |
2205 | ||
e2fcbf42 PM |
2206 | ``none`` |
2207 | Do not display video output. The guest will still see an | |
2208 | emulated graphics card, but its output will not be displayed to | |
2209 | the QEMU user. This option differs from the -nographic option in | |
2210 | that it only affects what is done with video output; -nographic | |
2211 | also changes the destination of the serial and parallel port | |
2212 | data. | |
e2fcbf42 | 2213 | ERST |
1472a95b | 2214 | |
5824d651 | 2215 | DEF("nographic", 0, QEMU_OPTION_nographic, |
ad96090a BS |
2216 | "-nographic disable graphical output and redirect serial I/Os to console\n", |
2217 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
2218 | SRST |
2219 | ``-nographic`` | |
2220 | Normally, if QEMU is compiled with graphical window support, it | |
2221 | displays output such as guest graphics, guest console, and the QEMU | |
2222 | monitor in a window. With this option, you can totally disable | |
2223 | graphical output so that QEMU is a simple command line application. | |
2224 | The emulated serial port is redirected on the console and muxed with | |
2225 | the monitor (unless redirected elsewhere explicitly). Therefore, you | |
2226 | can still use QEMU to debug a Linux kernel with a serial console. | |
2227 | Use C-a h for help on switching between the console and monitor. | |
2228 | ERST | |
5824d651 | 2229 | |
5324e3e9 | 2230 | #ifdef CONFIG_SPICE |
29b0040b | 2231 | DEF("spice", HAS_ARG, QEMU_OPTION_spice, |
27af7788 YH |
2232 | "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" |
2233 | " [,x509-key-file=<file>][,x509-key-password=<file>]\n" | |
2234 | " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" | |
a9daa36a DB |
2235 | " [,x509-dh-key-file=<file>][,addr=addr]\n" |
2236 | " [,ipv4=on|off][,ipv6=on|off][,unix=on|off]\n" | |
27af7788 YH |
2237 | " [,tls-ciphers=<list>]\n" |
2238 | " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" | |
2239 | " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" | |
99522f69 | 2240 | " [,sasl=on|off][,disable-ticketing=on|off]\n" |
36debafd | 2241 | " [,password-secret=<secret-id>]\n" |
27af7788 YH |
2242 | " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" |
2243 | " [,jpeg-wan-compression=[auto|never|always]]\n" | |
2244 | " [,zlib-glz-wan-compression=[auto|never|always]]\n" | |
a9daa36a DB |
2245 | " [,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]\n" |
2246 | " [,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]\n" | |
5ad24e5f | 2247 | " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" |
7b525508 | 2248 | " [,gl=[on|off]][,rendernode=<file>]\n" |
a635bcfc TH |
2249 | " enable spice\n" |
2250 | " at least one of {port, tls-port} is mandatory\n", | |
27af7788 | 2251 | QEMU_ARCH_ALL) |
5324e3e9 | 2252 | #endif |
e2fcbf42 PM |
2253 | SRST |
2254 | ``-spice option[,option[,...]]`` | |
2255 | Enable the spice remote desktop protocol. Valid options are | |
2256 | ||
2257 | ``port=<nr>`` | |
2258 | Set the TCP port spice is listening on for plaintext channels. | |
2259 | ||
2260 | ``addr=<addr>`` | |
2261 | Set the IP address spice is listening on. Default is any | |
2262 | address. | |
2263 | ||
a9daa36a | 2264 | ``ipv4=on|off``; \ ``ipv6=on|off``; \ ``unix=on|off`` |
e2fcbf42 PM |
2265 | Force using the specified IP version. |
2266 | ||
99522f69 DB |
2267 | ``password-secret=<secret-id>`` |
2268 | Set the ID of the ``secret`` object containing the password | |
2269 | you need to authenticate. | |
2270 | ||
a9daa36a | 2271 | ``sasl=on|off`` |
e2fcbf42 PM |
2272 | Require that the client use SASL to authenticate with the spice. |
2273 | The exact choice of authentication method used is controlled | |
2274 | from the system / user's SASL configuration file for the 'qemu' | |
2275 | service. This is typically found in /etc/sasl2/qemu.conf. If | |
2276 | running QEMU as an unprivileged user, an environment variable | |
2277 | SASL\_CONF\_PATH can be used to make it search alternate | |
2278 | locations for the service config. While some SASL auth methods | |
2279 | can also provide data encryption (eg GSSAPI), it is recommended | |
2280 | that SASL always be combined with the 'tls' and 'x509' settings | |
2281 | to enable use of SSL and server certificates. This ensures a | |
2282 | data encryption preventing compromise of authentication | |
2283 | credentials. | |
2284 | ||
a9daa36a | 2285 | ``disable-ticketing=on|off`` |
e2fcbf42 PM |
2286 | Allow client connects without authentication. |
2287 | ||
a9daa36a | 2288 | ``disable-copy-paste=on|off`` |
e2fcbf42 PM |
2289 | Disable copy paste between the client and the guest. |
2290 | ||
a9daa36a | 2291 | ``disable-agent-file-xfer=on|off`` |
e2fcbf42 PM |
2292 | Disable spice-vdagent based file-xfer between the client and the |
2293 | guest. | |
2294 | ||
2295 | ``tls-port=<nr>`` | |
2296 | Set the TCP port spice is listening on for encrypted channels. | |
2297 | ||
2298 | ``x509-dir=<dir>`` | |
2299 | Set the x509 file directory. Expects same filenames as -vnc | |
2300 | $display,x509=$dir | |
2301 | ||
2302 | ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>`` | |
2303 | The x509 file names can also be configured individually. | |
2304 | ||
2305 | ``tls-ciphers=<list>`` | |
2306 | Specify which ciphers to use. | |
2307 | ||
2308 | ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]`` | |
2309 | Force specific channel to be used with or without TLS | |
2310 | encryption. The options can be specified multiple times to | |
2311 | configure multiple channels. The special name "default" can be | |
2312 | used to set the default mode. For channels which are not | |
2313 | explicitly forced into one mode the spice client is allowed to | |
2314 | pick tls/plaintext as he pleases. | |
2315 | ||
2316 | ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]`` | |
2317 | Configure image compression (lossless). Default is auto\_glz. | |
2318 | ||
2319 | ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]`` | |
2320 | Configure wan image compression (lossy for slow links). Default | |
2321 | is auto. | |
2322 | ||
2323 | ``streaming-video=[off|all|filter]`` | |
2324 | Configure video stream detection. Default is off. | |
2325 | ||
2326 | ``agent-mouse=[on|off]`` | |
2327 | Enable/disable passing mouse events via vdagent. Default is on. | |
2328 | ||
2329 | ``playback-compression=[on|off]`` | |
2330 | Enable/disable audio stream compression (using celt 0.5.1). | |
2331 | Default is on. | |
2332 | ||
2333 | ``seamless-migration=[on|off]`` | |
2334 | Enable/disable spice seamless migration. Default is off. | |
2335 | ||
2336 | ``gl=[on|off]`` | |
2337 | Enable/disable OpenGL context. Default is off. | |
2338 | ||
2339 | ``rendernode=<file>`` | |
2340 | DRM render node for OpenGL rendering. If not specified, it will | |
2341 | pick the first available. (Since 2.9) | |
2342 | ERST | |
29b0040b | 2343 | |
5824d651 | 2344 | DEF("portrait", 0, QEMU_OPTION_portrait, |
ad96090a BS |
2345 | "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", |
2346 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
2347 | SRST |
2348 | ``-portrait`` | |
2349 | Rotate graphical output 90 deg left (only PXA LCD). | |
2350 | ERST | |
5824d651 | 2351 | |
9312805d VK |
2352 | DEF("rotate", HAS_ARG, QEMU_OPTION_rotate, |
2353 | "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", | |
2354 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
2355 | SRST |
2356 | ``-rotate deg`` | |
2357 | Rotate graphical output some deg left (only PXA LCD). | |
2358 | ERST | |
9312805d | 2359 | |
5824d651 | 2360 | DEF("vga", HAS_ARG, QEMU_OPTION_vga, |
a94f0c5c | 2361 | "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" |
ad96090a | 2362 | " select video card type\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
2363 | SRST |
2364 | ``-vga type`` | |
2365 | Select type of VGA card to emulate. Valid values for type are | |
2366 | ||
2367 | ``cirrus`` | |
2368 | Cirrus Logic GD5446 Video card. All Windows versions starting | |
2369 | from Windows 95 should recognize and use this graphic card. For | |
2370 | optimal performances, use 16 bit color depth in the guest and | |
2371 | the host OS. (This card was the default before QEMU 2.2) | |
2372 | ||
2373 | ``std`` | |
2374 | Standard VGA card with Bochs VBE extensions. If your guest OS | |
2375 | supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if | |
2376 | you want to use high resolution modes (>= 1280x1024x16) then you | |
2377 | should use this option. (This card is the default since QEMU | |
2378 | 2.2) | |
2379 | ||
2380 | ``vmware`` | |
2381 | VMWare SVGA-II compatible adapter. Use it if you have | |
2382 | sufficiently recent XFree86/XOrg server or Windows guest with a | |
2383 | driver for this card. | |
2384 | ||
2385 | ``qxl`` | |
2386 | QXL paravirtual graphic card. It is VGA compatible (including | |
2387 | VESA 2.0 VBE support). Works best with qxl guest drivers | |
2388 | installed though. Recommended choice when using the spice | |
2389 | protocol. | |
2390 | ||
2391 | ``tcx`` | |
2392 | (sun4m only) Sun TCX framebuffer. This is the default | |
2393 | framebuffer for sun4m machines and offers both 8-bit and 24-bit | |
2394 | colour depths at a fixed resolution of 1024x768. | |
2395 | ||
2396 | ``cg3`` | |
2397 | (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit | |
2398 | framebuffer for sun4m machines available in both 1024x768 | |
2399 | (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people | |
2400 | wishing to run older Solaris versions. | |
2401 | ||
2402 | ``virtio`` | |
2403 | Virtio VGA card. | |
2404 | ||
2405 | ``none`` | |
2406 | Disable VGA card. | |
2407 | ERST | |
5824d651 BS |
2408 | |
2409 | DEF("full-screen", 0, QEMU_OPTION_full_screen, | |
ad96090a | 2410 | "-full-screen start in full screen\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
2411 | SRST |
2412 | ``-full-screen`` | |
2413 | Start in full screen. | |
2414 | ERST | |
5824d651 | 2415 | |
60f9a4ef | 2416 | DEF("g", HAS_ARG, QEMU_OPTION_g , |
ad96090a | 2417 | "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", |
8ac919a0 | 2418 | QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K) |
e2fcbf42 | 2419 | SRST |
09ce5f2d | 2420 | ``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]`` |
e2fcbf42 PM |
2421 | Set the initial graphical resolution and depth (PPC, SPARC only). |
2422 | ||
2423 | For PPC the default is 800x600x32. | |
2424 | ||
2425 | For SPARC with the TCX graphics device, the default is 1024x768x8 | |
2426 | with the option of 1024x768x24. For cgthree, the default is | |
2427 | 1024x768x8 with the option of 1152x900x8 for people who wish to use | |
2428 | OBP. | |
2429 | ERST | |
5824d651 | 2430 | |
6261164b | 2431 | #ifdef CONFIG_VNC |
5824d651 | 2432 | DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , |
f04ec5af | 2433 | "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) |
6261164b | 2434 | #endif |
e2fcbf42 PM |
2435 | SRST |
2436 | ``-vnc display[,option[,option[,...]]]`` | |
2437 | Normally, if QEMU is compiled with graphical window support, it | |
2438 | displays output such as guest graphics, guest console, and the QEMU | |
2439 | monitor in a window. With this option, you can have QEMU listen on | |
2440 | VNC display display and redirect the VGA display over the VNC | |
2441 | session. It is very useful to enable the usb tablet device when | |
2442 | using this option (option ``-device usb-tablet``). When using the | |
2443 | VNC display, you must use the ``-k`` parameter to set the keyboard | |
2444 | layout if you are not using en-us. Valid syntax for the display is | |
2445 | ||
2446 | ``to=L`` | |
2447 | With this option, QEMU will try next available VNC displays, | |
2448 | until the number L, if the origianlly defined "-vnc display" is | |
2449 | not available, e.g. port 5900+display is already used by another | |
2450 | application. By default, to=0. | |
2451 | ||
2452 | ``host:d`` | |
2453 | TCP connections will only be allowed from host on display d. By | |
2454 | convention the TCP port is 5900+d. Optionally, host can be | |
2455 | omitted in which case the server will accept connections from | |
2456 | any host. | |
2457 | ||
2458 | ``unix:path`` | |
2459 | Connections will be allowed over UNIX domain sockets where path | |
2460 | is the location of a unix socket to listen for connections on. | |
2461 | ||
2462 | ``none`` | |
2463 | VNC is initialized but not started. The monitor ``change`` | |
2464 | command can be used to later start the VNC server. | |
2465 | ||
2466 | Following the display value there may be one or more option flags | |
2467 | separated by commas. Valid options are | |
2468 | ||
82a17d1d | 2469 | ``reverse=on|off`` |
e2fcbf42 PM |
2470 | Connect to a listening VNC client via a "reverse" connection. |
2471 | The client is specified by the display. For reverse network | |
2472 | connections (host:d,``reverse``), the d argument is a TCP port | |
2473 | number, not a display number. | |
2474 | ||
82a17d1d | 2475 | ``websocket=on|off`` |
e2fcbf42 PM |
2476 | Opens an additional TCP listening port dedicated to VNC |
2477 | Websocket connections. If a bare websocket option is given, the | |
2478 | Websocket port is 5700+display. An alternative port can be | |
2479 | specified with the syntax ``websocket``\ =port. | |
2480 | ||
2481 | If host is specified connections will only be allowed from this | |
2482 | host. It is possible to control the websocket listen address | |
2483 | independently, using the syntax ``websocket``\ =host:port. | |
2484 | ||
2485 | If no TLS credentials are provided, the websocket connection | |
2486 | runs in unencrypted mode. If TLS credentials are provided, the | |
2487 | websocket connection requires encrypted client connections. | |
2488 | ||
82a17d1d | 2489 | ``password=on|off`` |
e2fcbf42 PM |
2490 | Require that password based authentication is used for client |
2491 | connections. | |
2492 | ||
2493 | The password must be set separately using the ``set_password`` | |
923e9311 | 2494 | command in the :ref:`QEMU monitor`. The |
e2fcbf42 PM |
2495 | syntax to change your password is: |
2496 | ``set_password <protocol> <password>`` where <protocol> could be | |
2497 | either "vnc" or "spice". | |
2498 | ||
2499 | If you would like to change <protocol> password expiration, you | |
2500 | should use ``expire_password <protocol> <expiration-time>`` | |
2501 | where expiration time could be one of the following options: | |
2502 | now, never, +seconds or UNIX time of expiration, e.g. +60 to | |
2503 | make password expire in 60 seconds, or 1335196800 to make | |
2504 | password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for | |
2505 | this date and time). | |
2506 | ||
2507 | You can also use keywords "now" or "never" for the expiration | |
2508 | time to allow <protocol> password to expire immediately or never | |
2509 | expire. | |
2510 | ||
6c6840e9 DB |
2511 | ``password-secret=<secret-id>`` |
2512 | Require that password based authentication is used for client | |
2513 | connections, using the password provided by the ``secret`` | |
2514 | object identified by ``secret-id``. | |
2515 | ||
e2fcbf42 PM |
2516 | ``tls-creds=ID`` |
2517 | Provides the ID of a set of TLS credentials to use to secure the | |
2518 | VNC server. They will apply to both the normal VNC server socket | |
2519 | and the websocket socket (if enabled). Setting TLS credentials | |
2520 | will cause the VNC server socket to enable the VeNCrypt auth | |
2521 | mechanism. The credentials should have been previously created | |
2522 | using the ``-object tls-creds`` argument. | |
2523 | ||
2524 | ``tls-authz=ID`` | |
2525 | Provides the ID of the QAuthZ authorization object against which | |
2526 | the client's x509 distinguished name will validated. This object | |
2527 | is only resolved at time of use, so can be deleted and recreated | |
2528 | on the fly while the VNC server is active. If missing, it will | |
2529 | default to denying access. | |
2530 | ||
82a17d1d | 2531 | ``sasl=on|off`` |
e2fcbf42 PM |
2532 | Require that the client use SASL to authenticate with the VNC |
2533 | server. The exact choice of authentication method used is | |
2534 | controlled from the system / user's SASL configuration file for | |
2535 | the 'qemu' service. This is typically found in | |
2536 | /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user, | |
2537 | an environment variable SASL\_CONF\_PATH can be used to make it | |
2538 | search alternate locations for the service config. While some | |
2539 | SASL auth methods can also provide data encryption (eg GSSAPI), | |
2540 | it is recommended that SASL always be combined with the 'tls' | |
2541 | and 'x509' settings to enable use of SSL and server | |
2542 | certificates. This ensures a data encryption preventing | |
2543 | compromise of authentication credentials. See the | |
923e9311 TH |
2544 | :ref:`VNC security` section in the System Emulation Users Guide |
2545 | for details on using SASL authentication. | |
e2fcbf42 PM |
2546 | |
2547 | ``sasl-authz=ID`` | |
2548 | Provides the ID of the QAuthZ authorization object against which | |
2549 | the client's SASL username will validated. This object is only | |
2550 | resolved at time of use, so can be deleted and recreated on the | |
2551 | fly while the VNC server is active. If missing, it will default | |
2552 | to denying access. | |
2553 | ||
82a17d1d | 2554 | ``acl=on|off`` |
e2fcbf42 PM |
2555 | Legacy method for enabling authorization of clients against the |
2556 | x509 distinguished name and SASL username. It results in the | |
2557 | creation of two ``authz-list`` objects with IDs of | |
2558 | ``vnc.username`` and ``vnc.x509dname``. The rules for these | |
2559 | objects must be configured with the HMP ACL commands. | |
2560 | ||
2561 | This option is deprecated and should no longer be used. The new | |
2562 | ``sasl-authz`` and ``tls-authz`` options are a replacement. | |
2563 | ||
82a17d1d | 2564 | ``lossy=on|off`` |
e2fcbf42 PM |
2565 | Enable lossy compression methods (gradient, JPEG, ...). If this |
2566 | option is set, VNC client may receive lossy framebuffer updates | |
2567 | depending on its encoding settings. Enabling this option can | |
2568 | save a lot of bandwidth at the expense of quality. | |
2569 | ||
82a17d1d | 2570 | ``non-adaptive=on|off`` |
e2fcbf42 PM |
2571 | Disable adaptive encodings. Adaptive encodings are enabled by |
2572 | default. An adaptive encoding will try to detect frequently | |
2573 | updated screen regions, and send updates in these regions using | |
2574 | a lossy encoding (like JPEG). This can be really helpful to save | |
2575 | bandwidth when playing videos. Disabling adaptive encodings | |
2576 | restores the original static behavior of encodings like Tight. | |
2577 | ||
2578 | ``share=[allow-exclusive|force-shared|ignore]`` | |
2579 | Set display sharing policy. 'allow-exclusive' allows clients to | |
2580 | ask for exclusive access. As suggested by the rfb spec this is | |
2581 | implemented by dropping other connections. Connecting multiple | |
2582 | clients in parallel requires all clients asking for a shared | |
2583 | session (vncviewer: -shared switch). This is the default. | |
2584 | 'force-shared' disables exclusive client access. Useful for | |
2585 | shared desktop sessions, where you don't want someone forgetting | |
2586 | specify -shared disconnect everybody else. 'ignore' completely | |
2587 | ignores the shared flag and allows everybody connect | |
2588 | unconditionally. Doesn't conform to the rfb spec but is | |
2589 | traditional QEMU behavior. | |
2590 | ||
2591 | ``key-delay-ms`` | |
2592 | Set keyboard delay, for key down and key up events, in | |
2593 | milliseconds. Default is 10. Keyboards are low-bandwidth | |
2594 | devices, so this slowdown can help the device and guest to keep | |
2595 | up and not lose events in case events are arriving in bulk. | |
2596 | Possible causes for the latter are flaky network connections, or | |
2597 | scripts for automated testing. | |
2598 | ||
2599 | ``audiodev=audiodev`` | |
2600 | Use the specified audiodev when the VNC client requests audio | |
2601 | transmission. When not using an -audiodev argument, this option | |
2602 | must be omitted, otherwise is must be present and specify a | |
2603 | valid audiodev. | |
7b5fa0b5 | 2604 | |
82a17d1d | 2605 | ``power-control=on|off`` |
7b5fa0b5 DB |
2606 | Permit the remote client to issue shutdown, reboot or reset power |
2607 | control requests. | |
e2fcbf42 | 2608 | ERST |
5824d651 | 2609 | |
a3adb7ad | 2610 | ARCHHEADING(, QEMU_ARCH_I386) |
5824d651 | 2611 | |
de6b4f90 | 2612 | ARCHHEADING(i386 target only:, QEMU_ARCH_I386) |
5824d651 | 2613 | |
5824d651 | 2614 | DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, |
ad96090a BS |
2615 | "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", |
2616 | QEMU_ARCH_I386) | |
e2fcbf42 PM |
2617 | SRST |
2618 | ``-win2k-hack`` | |
2619 | Use it when installing Windows 2000 to avoid a disk full bug. After | |
2620 | Windows 2000 is installed, you no longer need this option (this | |
2621 | option slows down the IDE transfers). | |
2622 | ERST | |
5824d651 | 2623 | |
5824d651 | 2624 | DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, |
ad96090a BS |
2625 | "-no-fd-bootchk disable boot signature checking for floppy disks\n", |
2626 | QEMU_ARCH_I386) | |
e2fcbf42 PM |
2627 | SRST |
2628 | ``-no-fd-bootchk`` | |
2629 | Disable boot signature checking for floppy disks in BIOS. May be | |
2630 | needed to boot from old floppy disks. | |
2631 | ERST | |
5824d651 | 2632 | |
5824d651 | 2633 | DEF("no-acpi", 0, QEMU_OPTION_no_acpi, |
f5d8c8cd | 2634 | "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) |
e2fcbf42 PM |
2635 | SRST |
2636 | ``-no-acpi`` | |
2637 | Disable ACPI (Advanced Configuration and Power Interface) support. | |
2638 | Use it if your guest OS complains about ACPI problems (PC target | |
2639 | machine only). | |
2640 | ERST | |
5824d651 | 2641 | |
5824d651 | 2642 | DEF("no-hpet", 0, QEMU_OPTION_no_hpet, |
ad96090a | 2643 | "-no-hpet disable HPET\n", QEMU_ARCH_I386) |
e2fcbf42 PM |
2644 | SRST |
2645 | ``-no-hpet`` | |
df37330c | 2646 | Disable HPET support. Deprecated, use '-machine hpet=off' instead. |
e2fcbf42 | 2647 | ERST |
5824d651 | 2648 | |
5824d651 | 2649 | DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, |
104bf02e | 2650 | "-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 | 2651 | " ACPI table description\n", QEMU_ARCH_I386) |
e2fcbf42 PM |
2652 | SRST |
2653 | ``-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]...]`` | |
2654 | Add ACPI table with specified header fields and context from | |
2655 | specified files. For file=, take whole ACPI table from the specified | |
2656 | files, including all ACPI headers (possible overridden by other | |
2657 | options). For data=, only data portion of the table is used, all | |
2658 | header information is specified in the command line. If a SLIC table | |
2659 | is supplied to QEMU, then the SLIC's oem\_id and oem\_table\_id | |
2660 | fields will override the same in the RSDT and the FADT (a.k.a. | |
2661 | FACP), in order to ensure the field matches required by the | |
2662 | Microsoft SLIC spec and the ACPI spec. | |
2663 | ERST | |
5824d651 | 2664 | |
b6f6e3d3 AL |
2665 | DEF("smbios", HAS_ARG, QEMU_OPTION_smbios, |
2666 | "-smbios file=binary\n" | |
ca1a8a06 | 2667 | " load SMBIOS entry from binary file\n" |
b155eb1d GS |
2668 | "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" |
2669 | " [,uefi=on|off]\n" | |
ca1a8a06 | 2670 | " specify SMBIOS type 0 fields\n" |
b6f6e3d3 AL |
2671 | "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" |
2672 | " [,uuid=uuid][,sku=str][,family=str]\n" | |
b155eb1d GS |
2673 | " specify SMBIOS type 1 fields\n" |
2674 | "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" | |
2675 | " [,asset=str][,location=str]\n" | |
2676 | " specify SMBIOS type 2 fields\n" | |
2677 | "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" | |
2678 | " [,sku=str]\n" | |
2679 | " specify SMBIOS type 3 fields\n" | |
2680 | "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" | |
c906e039 | 2681 | " [,asset=str][,part=str][,max-speed=%d][,current-speed=%d]\n" |
cb5fb04f | 2682 | " [,processor-id=%d]\n" |
b155eb1d | 2683 | " specify SMBIOS type 4 fields\n" |
fd8caa25 HM |
2684 | "-smbios type=8[,external_reference=str][,internal_reference=str][,connector_type=%d][,port_type=%d]\n" |
2685 | " specify SMBIOS type 8 fields\n" | |
48a7ff4d DB |
2686 | "-smbios type=11[,value=str][,path=filename]\n" |
2687 | " specify SMBIOS type 11 fields\n" | |
b155eb1d | 2688 | "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" |
3ebd6cc8 | 2689 | " [,asset=str][,part=str][,speed=%d]\n" |
05dfb447 VB |
2690 | " specify SMBIOS type 17 fields\n" |
2691 | "-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]\n" | |
2692 | " specify SMBIOS type 41 fields\n", | |
4934cc58 | 2693 | QEMU_ARCH_I386 | QEMU_ARCH_ARM | QEMU_ARCH_LOONGARCH) |
e2fcbf42 PM |
2694 | SRST |
2695 | ``-smbios file=binary`` | |
2696 | Load SMBIOS entry from binary file. | |
2697 | ||
2698 | ``-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]`` | |
2699 | Specify SMBIOS type 0 fields | |
2700 | ||
2701 | ``-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]`` | |
2702 | Specify SMBIOS type 1 fields | |
2703 | ||
2704 | ``-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]`` | |
2705 | Specify SMBIOS type 2 fields | |
2706 | ||
2707 | ``-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]`` | |
2708 | Specify SMBIOS type 3 fields | |
2709 | ||
cb5fb04f | 2710 | ``-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str][,processor-id=%d]`` |
e2fcbf42 PM |
2711 | Specify SMBIOS type 4 fields |
2712 | ||
48a7ff4d DB |
2713 | ``-smbios type=11[,value=str][,path=filename]`` |
2714 | Specify SMBIOS type 11 fields | |
2715 | ||
2716 | This argument can be repeated multiple times, and values are added in the order they are parsed. | |
2717 | Applications intending to use OEM strings data are encouraged to use their application name as | |
2718 | a prefix for the value string. This facilitates passing information for multiple applications | |
2719 | concurrently. | |
2720 | ||
2721 | The ``value=str`` syntax provides the string data inline, while the ``path=filename`` syntax | |
2722 | loads data from a file on disk. Note that the file is not permitted to contain any NUL bytes. | |
2723 | ||
2724 | Both the ``value`` and ``path`` options can be repeated multiple times and will be added to | |
2725 | the SMBIOS table in the order in which they appear. | |
2726 | ||
2727 | Note that on the x86 architecture, the total size of all SMBIOS tables is limited to 65535 | |
2728 | bytes. Thus the OEM strings data is not suitable for passing large amounts of data into the | |
2729 | guest. Instead it should be used as a indicator to inform the guest where to locate the real | |
2730 | data set, for example, by specifying the serial ID of a block device. | |
2731 | ||
2732 | An example passing three strings is | |
2733 | ||
2734 | .. parsed-literal:: | |
2735 | ||
2736 | -smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\\ | |
2737 | value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\\ | |
2738 | path=/some/file/with/oemstringsdata.txt | |
2739 | ||
2740 | In the guest OS this is visible with the ``dmidecode`` command | |
2741 | ||
2742 | .. parsed-literal:: | |
2743 | ||
2744 | $ dmidecode -t 11 | |
2745 | Handle 0x0E00, DMI type 11, 5 bytes | |
2746 | OEM Strings | |
2747 | String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/ | |
2748 | String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os | |
2749 | String 3: myapp:some extra data | |
2750 | ||
2751 | ||
e2fcbf42 PM |
2752 | ``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]`` |
2753 | Specify SMBIOS type 17 fields | |
05dfb447 VB |
2754 | |
2755 | ``-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]`` | |
2756 | Specify SMBIOS type 41 fields | |
2757 | ||
2758 | This argument can be repeated multiple times. Its main use is to allow network interfaces be created | |
2759 | as ``enoX`` on Linux, with X being the instance number, instead of the name depending on the interface | |
2760 | position on the PCI bus. | |
2761 | ||
2762 | Here is an example of use: | |
2763 | ||
2764 | .. parsed-literal:: | |
2765 | ||
2766 | -netdev user,id=internet \\ | |
2767 | -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \\ | |
2768 | -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev | |
2769 | ||
2770 | In the guest OS, the device should then appear as ``eno1``: | |
2771 | ||
2772 | ..parsed-literal:: | |
2773 | ||
2774 | $ ip -brief l | |
2775 | lo UNKNOWN 00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP> | |
2776 | eno1 UP 50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP> | |
2777 | ||
2778 | Currently, the PCI device has to be attached to the root bus. | |
2779 | ||
e2fcbf42 | 2780 | ERST |
b6f6e3d3 | 2781 | |
c70a01e4 | 2782 | DEFHEADING() |
5824d651 | 2783 | |
de6b4f90 | 2784 | DEFHEADING(Network options:) |
5824d651 | 2785 | |
6a8b4a5b | 2786 | DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, |
5824d651 | 2787 | #ifdef CONFIG_SLIRP |
8b0dc246 DB |
2788 | "-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]\n" |
2789 | " [,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" | |
0b11c036 | 2790 | " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" |
f18d1375 | 2791 | " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" |
0fca92b9 | 2792 | " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" |
ad196a9d | 2793 | #ifndef _WIN32 |
c92ef6a2 | 2794 | "[,smb=dir[,smbserver=addr]]\n" |
ad196a9d | 2795 | #endif |
6a8b4a5b TH |
2796 | " configure a user mode network backend with ID 'str',\n" |
2797 | " its DHCP server and optional services\n" | |
5824d651 BS |
2798 | #endif |
2799 | #ifdef _WIN32 | |
6a8b4a5b TH |
2800 | "-netdev tap,id=str,ifname=name\n" |
2801 | " configure a host TAP network backend with ID 'str'\n" | |
5824d651 | 2802 | #else |
6a8b4a5b | 2803 | "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" |
584613ea | 2804 | " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" |
6a8b4a5b | 2805 | " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" |
69e87b32 | 2806 | " [,poll-us=n]\n" |
6a8b4a5b | 2807 | " configure a host TAP network backend with ID 'str'\n" |
584613ea | 2808 | " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" |
a7c36ee4 CB |
2809 | " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" |
2810 | " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" | |
2811 | " to deconfigure it\n" | |
ca1a8a06 | 2812 | " use '[down]script=no' to disable script execution\n" |
a7c36ee4 CB |
2813 | " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" |
2814 | " configure it\n" | |
5824d651 | 2815 | " use 'fd=h' to connect to an already opened TAP interface\n" |
2ca81baa | 2816 | " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" |
ca1a8a06 | 2817 | " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" |
f157ed20 | 2818 | " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" |
ca1a8a06 BR |
2819 | " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" |
2820 | " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" | |
82b0d80e | 2821 | " use vhost=on to enable experimental in kernel accelerator\n" |
5430a28f MT |
2822 | " (only has effect for virtio guests which use MSIX)\n" |
2823 | " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" | |
82b0d80e | 2824 | " use 'vhostfd=h' to connect to an already opened vhost net device\n" |
2ca81baa | 2825 | " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" |
ec396014 | 2826 | " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" |
cba42d61 | 2827 | " use 'poll-us=n' to specify the maximum number of microseconds that could be\n" |
69e87b32 | 2828 | " spent on busy polling for vhost net\n" |
6a8b4a5b TH |
2829 | "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" |
2830 | " configure a host TAP network backend with ID 'str' that is\n" | |
2831 | " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" | |
2832 | " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" | |
3fb69aa1 AI |
2833 | #endif |
2834 | #ifdef __linux__ | |
6a8b4a5b | 2835 | "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" |
8b0dc246 DB |
2836 | " [,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]\n" |
2837 | " [,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]\n" | |
6a8b4a5b TH |
2838 | " [,rxcookie=rxcookie][,offset=offset]\n" |
2839 | " configure a network backend with ID 'str' connected to\n" | |
2840 | " an Ethernet over L2TPv3 pseudowire.\n" | |
3fb69aa1 | 2841 | " Linux kernel 3.3+ as well as most routers can talk\n" |
2f47b403 | 2842 | " L2TPv3. This transport allows connecting a VM to a VM,\n" |
3fb69aa1 | 2843 | " VM to a router and even VM to Host. It is a nearly-universal\n" |
21843dc4 | 2844 | " standard (RFC3931). Note - this implementation uses static\n" |
3fb69aa1 AI |
2845 | " pre-configured tunnels (same as the Linux kernel).\n" |
2846 | " use 'src=' to specify source address\n" | |
2847 | " use 'dst=' to specify destination address\n" | |
2848 | " use 'udp=on' to specify udp encapsulation\n" | |
3952651a | 2849 | " use 'srcport=' to specify source udp port\n" |
3fb69aa1 AI |
2850 | " use 'dstport=' to specify destination udp port\n" |
2851 | " use 'ipv6=on' to force v6\n" | |
2852 | " L2TPv3 uses cookies to prevent misconfiguration as\n" | |
2853 | " well as a weak security measure\n" | |
2854 | " use 'rxcookie=0x012345678' to specify a rxcookie\n" | |
2855 | " use 'txcookie=0x012345678' to specify a txcookie\n" | |
2856 | " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" | |
2857 | " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" | |
2858 | " use 'pincounter=on' to work around broken counter handling in peer\n" | |
2859 | " use 'offset=X' to add an extra offset between header and data\n" | |
5824d651 | 2860 | #endif |
6a8b4a5b TH |
2861 | "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" |
2862 | " configure a network backend to connect to another network\n" | |
2863 | " using a socket connection\n" | |
2864 | "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" | |
2865 | " configure a network backend to connect to a multicast maddr and port\n" | |
3a75e74c | 2866 | " use 'localaddr=addr' to specify the host address to send packets from\n" |
6a8b4a5b TH |
2867 | "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" |
2868 | " configure a network backend to connect to another network\n" | |
2869 | " using an UDP tunnel\n" | |
148fbf0d LV |
2870 | "-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" |
2871 | "-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off][,reconnect=seconds]\n" | |
2872 | "-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor[,reconnect=seconds]\n" | |
5166fe0a LV |
2873 | " configure a network backend to connect to another network\n" |
2874 | " using a socket connection in stream mode.\n" | |
2875 | "-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]\n" | |
2876 | "-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]\n" | |
2877 | " configure a network backend to connect to a multicast maddr and port\n" | |
2878 | " use ``local.host=addr`` to specify the host address to send packets from\n" | |
2879 | "-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]\n" | |
784e7a25 | 2880 | "-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]\n" |
5166fe0a LV |
2881 | "-netdev dgram,id=str,local.type=fd,local.str=file-descriptor\n" |
2882 | " configure a network backend to connect to another network\n" | |
2883 | " using an UDP tunnel\n" | |
5824d651 | 2884 | #ifdef CONFIG_VDE |
6a8b4a5b TH |
2885 | "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" |
2886 | " configure a network backend to connect to port 'n' of a vde switch\n" | |
2887 | " running on host and listening for incoming connections on 'socketpath'.\n" | |
5824d651 BS |
2888 | " Use group 'groupname' and mode 'octalmode' to change default\n" |
2889 | " ownership and permissions for communication port.\n" | |
58952137 VM |
2890 | #endif |
2891 | #ifdef CONFIG_NETMAP | |
6a8b4a5b | 2892 | "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" |
58952137 VM |
2893 | " attach to the existing netmap-enabled network interface 'name', or to a\n" |
2894 | " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" | |
2895 | " netmap device, defaults to '/dev/netmap')\n" | |
5824d651 | 2896 | #endif |
cb039ef3 IM |
2897 | #ifdef CONFIG_AF_XDP |
2898 | "-netdev af-xdp,id=str,ifname=name[,mode=native|skb][,force-copy=on|off]\n" | |
2899 | " [,queues=n][,start-queue=m][,inhibit=on|off][,sock-fds=x:y:...:z]\n" | |
2900 | " attach to the existing network interface 'name' with AF_XDP socket\n" | |
2901 | " use 'mode=MODE' to specify an XDP program attach mode\n" | |
2902 | " use 'force-copy=on|off' to force XDP copy mode even if device supports zero-copy (default: off)\n" | |
2903 | " use 'inhibit=on|off' to inhibit loading of a default XDP program (default: off)\n" | |
2904 | " with inhibit=on,\n" | |
2905 | " use 'sock-fds' to provide file descriptors for already open AF_XDP sockets\n" | |
2906 | " added to a socket map in XDP program. One socket per queue.\n" | |
2907 | " use 'queues=n' to specify how many queues of a multiqueue interface should be used\n" | |
2908 | " use 'start-queue=m' to specify the first queue that should be used\n" | |
2909 | #endif | |
253dc14c | 2910 | #ifdef CONFIG_POSIX |
6a8b4a5b TH |
2911 | "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" |
2912 | " configure a vhost-user network, backed by a chardev 'dev'\n" | |
108a6481 CL |
2913 | #endif |
2914 | #ifdef __linux__ | |
8801ccd0 | 2915 | "-netdev vhost-vdpa,id=str[,vhostdev=/path/to/dev][,vhostfd=h]\n" |
108a6481 | 2916 | " configure a vhost-vdpa network,Establish a vhost-vdpa netdev\n" |
8801ccd0 SWL |
2917 | " use 'vhostdev=/path/to/dev' to open a vhost vdpa device\n" |
2918 | " use 'vhostfd=h' to connect to an already opened vhost vdpa device\n" | |
b0290db1 VY |
2919 | #endif |
2920 | #ifdef CONFIG_VMNET | |
2921 | "-netdev vmnet-host,id=str[,isolated=on|off][,net-uuid=uuid]\n" | |
2922 | " [,start-address=addr,end-address=addr,subnet-mask=mask]\n" | |
2923 | " configure a vmnet network backend in host mode with ID 'str',\n" | |
2924 | " isolate this interface from others with 'isolated',\n" | |
2925 | " configure the address range and choose a subnet mask,\n" | |
2926 | " specify network UUID 'uuid' to disable DHCP and interact with\n" | |
2927 | " vmnet-host interfaces within this isolated network\n" | |
2928 | "-netdev vmnet-shared,id=str[,isolated=on|off][,nat66-prefix=addr]\n" | |
2929 | " [,start-address=addr,end-address=addr,subnet-mask=mask]\n" | |
2930 | " configure a vmnet network backend in shared mode with ID 'str',\n" | |
2931 | " configure the address range and choose a subnet mask,\n" | |
2932 | " set IPv6 ULA prefix (of length 64) to use for internal network,\n" | |
2933 | " isolate this interface from others with 'isolated'\n" | |
2934 | "-netdev vmnet-bridged,id=str,ifname=name[,isolated=on|off]\n" | |
2935 | " configure a vmnet network backend in bridged mode with ID 'str',\n" | |
2936 | " use 'ifname=name' to select a physical network interface to be bridged,\n" | |
2937 | " isolate this interface from others with 'isolated'\n" | |
253dc14c | 2938 | #endif |
18d65d22 | 2939 | "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" |
af1a5c3e | 2940 | " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) |
78cd6f7b | 2941 | DEF("nic", HAS_ARG, QEMU_OPTION_nic, |
dfaa7d50 | 2942 | "-nic [tap|bridge|" |
78cd6f7b TH |
2943 | #ifdef CONFIG_SLIRP |
2944 | "user|" | |
2945 | #endif | |
2946 | #ifdef __linux__ | |
2947 | "l2tpv3|" | |
2948 | #endif | |
2949 | #ifdef CONFIG_VDE | |
2950 | "vde|" | |
2951 | #endif | |
2952 | #ifdef CONFIG_NETMAP | |
2953 | "netmap|" | |
2954 | #endif | |
cb039ef3 IM |
2955 | #ifdef CONFIG_AF_XDP |
2956 | "af-xdp|" | |
2957 | #endif | |
78cd6f7b TH |
2958 | #ifdef CONFIG_POSIX |
2959 | "vhost-user|" | |
b0290db1 VY |
2960 | #endif |
2961 | #ifdef CONFIG_VMNET | |
2962 | "vmnet-host|vmnet-shared|vmnet-bridged|" | |
78cd6f7b TH |
2963 | #endif |
2964 | "socket][,option][,...][mac=macaddr]\n" | |
2965 | " initialize an on-board / default host NIC (using MAC address\n" | |
2966 | " macaddr) and connect it to the given host network backend\n" | |
dfaa7d50 | 2967 | "-nic none use it alone to have zero network devices (the default is to\n" |
78cd6f7b TH |
2968 | " provided a 'user' network connection)\n", |
2969 | QEMU_ARCH_ALL) | |
6a8b4a5b | 2970 | DEF("net", HAS_ARG, QEMU_OPTION_net, |
af1a5c3e | 2971 | "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" |
0e60a82d | 2972 | " configure or create an on-board (or machine default) NIC and\n" |
af1a5c3e | 2973 | " connect it to hub 0 (please use -nic unless you need a hub)\n" |
6a8b4a5b | 2974 | "-net [" |
a1ea458f MM |
2975 | #ifdef CONFIG_SLIRP |
2976 | "user|" | |
2977 | #endif | |
2978 | "tap|" | |
a7c36ee4 | 2979 | "bridge|" |
a1ea458f MM |
2980 | #ifdef CONFIG_VDE |
2981 | "vde|" | |
58952137 VM |
2982 | #endif |
2983 | #ifdef CONFIG_NETMAP | |
2984 | "netmap|" | |
b0290db1 | 2985 | #endif |
cb039ef3 IM |
2986 | #ifdef CONFIG_AF_XDP |
2987 | "af-xdp|" | |
2988 | #endif | |
b0290db1 VY |
2989 | #ifdef CONFIG_VMNET |
2990 | "vmnet-host|vmnet-shared|vmnet-bridged|" | |
a1ea458f | 2991 | #endif |
af1a5c3e | 2992 | "socket][,option][,option][,...]\n" |
6a8b4a5b TH |
2993 | " old way to initialize a host network interface\n" |
2994 | " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) | |
e2fcbf42 | 2995 | SRST |
cb039ef3 | 2996 | ``-nic [tap|bridge|user|l2tpv3|vde|netmap|af-xdp|vhost-user|socket][,...][,mac=macaddr][,model=mn]`` |
e2fcbf42 PM |
2997 | This option is a shortcut for configuring both the on-board |
2998 | (default) guest NIC hardware and the host network backend in one go. | |
2999 | The host backend options are the same as with the corresponding | |
3000 | ``-netdev`` options below. The guest NIC model can be set with | |
3001 | ``model=modelname``. Use ``model=help`` to list the available device | |
3002 | types. The hardware MAC address can be set with ``mac=macaddr``. | |
3003 | ||
3004 | The following two example do exactly the same, to show how ``-nic`` | |
3005 | can be used to shorten the command line length: | |
3006 | ||
3007 | .. parsed-literal:: | |
3008 | ||
3009 | |qemu_system| -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 | |
3010 | |qemu_system| -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 | |
3011 | ||
3012 | ``-nic none`` | |
3013 | Indicate that no network devices should be configured. It is used to | |
3014 | override the default configuration (default NIC with "user" host | |
3015 | network backend) which is activated if no other networking options | |
3016 | are provided. | |
3017 | ||
3018 | ``-netdev user,id=id[,option][,option][,...]`` | |
3019 | Configure user mode host network backend which requires no | |
3020 | administrator privilege to run. Valid options are: | |
3021 | ||
3022 | ``id=id`` | |
3023 | Assign symbolic name for use in monitor commands. | |
3024 | ||
3025 | ``ipv4=on|off and ipv6=on|off`` | |
3026 | Specify that either IPv4 or IPv6 must be enabled. If neither is | |
3027 | specified both protocols are enabled. | |
3028 | ||
3029 | ``net=addr[/mask]`` | |
3030 | Set IP network address the guest will see. Optionally specify | |
3031 | the netmask, either in the form a.b.c.d or as number of valid | |
3032 | top-most bits. Default is 10.0.2.0/24. | |
3033 | ||
3034 | ``host=addr`` | |
3035 | Specify the guest-visible address of the host. Default is the | |
3036 | 2nd IP in the guest network, i.e. x.x.x.2. | |
3037 | ||
3038 | ``ipv6-net=addr[/int]`` | |
3039 | Set IPv6 network address the guest will see (default is | |
3040 | fec0::/64). The network prefix is given in the usual hexadecimal | |
3041 | IPv6 address notation. The prefix size is optional, and is given | |
3042 | as the number of valid top-most bits (default is 64). | |
3043 | ||
3044 | ``ipv6-host=addr`` | |
3045 | Specify the guest-visible IPv6 address of the host. Default is | |
3046 | the 2nd IPv6 in the guest network, i.e. xxxx::2. | |
3047 | ||
3048 | ``restrict=on|off`` | |
3049 | If this option is enabled, the guest will be isolated, i.e. it | |
3050 | will not be able to contact the host and no guest IP packets | |
3051 | will be routed over the host to the outside. This option does | |
3052 | not affect any explicitly set forwarding rules. | |
3053 | ||
3054 | ``hostname=name`` | |
3055 | Specifies the client hostname reported by the built-in DHCP | |
3056 | server. | |
3057 | ||
3058 | ``dhcpstart=addr`` | |
3059 | Specify the first of the 16 IPs the built-in DHCP server can | |
3060 | assign. Default is the 15th to 31st IP in the guest network, | |
3061 | i.e. x.x.x.15 to x.x.x.31. | |
3062 | ||
3063 | ``dns=addr`` | |
3064 | Specify the guest-visible address of the virtual nameserver. The | |
3065 | address must be different from the host address. Default is the | |
3066 | 3rd IP in the guest network, i.e. x.x.x.3. | |
3067 | ||
3068 | ``ipv6-dns=addr`` | |
3069 | Specify the guest-visible address of the IPv6 virtual | |
3070 | nameserver. The address must be different from the host address. | |
3071 | Default is the 3rd IP in the guest network, i.e. xxxx::3. | |
3072 | ||
3073 | ``dnssearch=domain`` | |
3074 | Provides an entry for the domain-search list sent by the | |
3075 | built-in DHCP server. More than one domain suffix can be | |
3076 | transmitted by specifying this option multiple times. If | |
3077 | supported, this will cause the guest to automatically try to | |
3078 | append the given domain suffix(es) in case a domain name can not | |
3079 | be resolved. | |
3080 | ||
3081 | Example: | |
3082 | ||
3083 | .. parsed-literal:: | |
3084 | ||
3085 | |qemu_system| -nic user,dnssearch=mgmt.example.org,dnssearch=example.org | |
3086 | ||
3087 | ``domainname=domain`` | |
3088 | Specifies the client domain name reported by the built-in DHCP | |
3089 | server. | |
3090 | ||
3091 | ``tftp=dir`` | |
3092 | When using the user mode network stack, activate a built-in TFTP | |
3093 | server. The files in dir will be exposed as the root of a TFTP | |
3094 | server. The TFTP client on the guest must be configured in | |
3095 | binary mode (use the command ``bin`` of the Unix TFTP client). | |
3096 | ||
3097 | ``tftp-server-name=name`` | |
3098 | In BOOTP reply, broadcast name as the "TFTP server name" | |
3099 | (RFC2132 option 66). This can be used to advise the guest to | |
3100 | load boot files or configurations from a different server than | |
3101 | the host address. | |
3102 | ||
3103 | ``bootfile=file`` | |
3104 | When using the user mode network stack, broadcast file as the | |
3105 | BOOTP filename. In conjunction with ``tftp``, this can be used | |
3106 | to network boot a guest from a local directory. | |
3107 | ||
3108 | Example (using pxelinux): | |
3109 | ||
3110 | .. parsed-literal:: | |
3111 | ||
353a06b4 | 3112 | |qemu_system| -hda linux.img -boot n -device e1000,netdev=n1 \\ |
e2fcbf42 PM |
3113 | -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 |
3114 | ||
3115 | ``smb=dir[,smbserver=addr]`` | |
3116 | When using the user mode network stack, activate a built-in SMB | |
3117 | server so that Windows OSes can access to the host files in | |
3118 | ``dir`` transparently. The IP address of the SMB server can be | |
3119 | set to addr. By default the 4th IP in the guest network is used, | |
3120 | i.e. x.x.x.4. | |
3121 | ||
3122 | In the guest Windows OS, the line: | |
3123 | ||
3124 | :: | |
3125 | ||
3126 | 10.0.2.4 smbserver | |
3127 | ||
3128 | must be added in the file ``C:\WINDOWS\LMHOSTS`` (for windows | |
3129 | 9x/Me) or ``C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS`` (Windows | |
3130 | NT/2000). | |
3131 | ||
3132 | Then ``dir`` can be accessed in ``\\smbserver\qemu``. | |
3133 | ||
3134 | Note that a SAMBA server must be installed on the host OS. | |
3135 | ||
3136 | ``hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport`` | |
3137 | Redirect incoming TCP or UDP connections to the host port | |
3138 | hostport to the guest IP address guestaddr on guest port | |
3139 | guestport. If guestaddr is not specified, its value is x.x.x.15 | |
3140 | (default first address given by the built-in DHCP server). By | |
3141 | specifying hostaddr, the rule can be bound to a specific host | |
3142 | interface. If no connection type is set, TCP is used. This | |
3143 | option can be given multiple times. | |
3144 | ||
3145 | For example, to redirect host X11 connection from screen 1 to | |
3146 | guest screen 0, use the following: | |
3147 | ||
09ce5f2d | 3148 | .. parsed-literal:: |
e2fcbf42 PM |
3149 | |
3150 | # on the host | |
3151 | |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 | |
3152 | # this host xterm should open in the guest X11 server | |
3153 | xterm -display :1 | |
3154 | ||
3155 | To redirect telnet connections from host port 5555 to telnet | |
3156 | port on the guest, use the following: | |
3157 | ||
09ce5f2d | 3158 | .. parsed-literal:: |
e2fcbf42 PM |
3159 | |
3160 | # on the host | |
3161 | |qemu_system| -nic user,hostfwd=tcp::5555-:23 | |
3162 | telnet localhost 5555 | |
3163 | ||
3164 | Then when you use on the host ``telnet localhost 5555``, you | |
3165 | connect to the guest telnet server. | |
3166 | ||
3167 | ``guestfwd=[tcp]:server:port-dev``; \ ``guestfwd=[tcp]:server:port-cmd:command`` | |
3168 | Forward guest TCP connections to the IP address server on port | |
3169 | port to the character device dev or to a program executed by | |
3170 | cmd:command which gets spawned for each connection. This option | |
3171 | can be given multiple times. | |
3172 | ||
3173 | You can either use a chardev directly and have that one used | |
3174 | throughout QEMU's lifetime, like in the following example: | |
3175 | ||
09ce5f2d | 3176 | .. parsed-literal:: |
e2fcbf42 PM |
3177 | |
3178 | # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever | |
3179 | # the guest accesses it | |
3180 | |qemu_system| -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 | |
3181 | ||
3182 | Or you can execute a command on every TCP connection established | |
3183 | by the guest, so that QEMU behaves similar to an inetd process | |
3184 | for that virtual server: | |
3185 | ||
09ce5f2d | 3186 | .. parsed-literal:: |
e2fcbf42 PM |
3187 | |
3188 | # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 | |
3189 | # and connect the TCP stream to its stdin/stdout | |
3190 | |qemu_system| -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' | |
3191 | ||
3192 | ``-netdev tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]`` | |
3193 | Configure a host TAP network backend with ID id. | |
3194 | ||
3195 | Use the network script file to configure it and the network script | |
3196 | dfile to deconfigure it. If name is not provided, the OS | |
3197 | automatically provides one. The default network configure script is | |
3198 | ``/etc/qemu-ifup`` and the default network deconfigure script is | |
3199 | ``/etc/qemu-ifdown``. Use ``script=no`` or ``downscript=no`` to | |
3200 | disable script execution. | |
3201 | ||
3202 | If running QEMU as an unprivileged user, use the network helper | |
8d73ec89 | 3203 | to configure the TAP interface and attach it to the bridge. |
e2fcbf42 PM |
3204 | The default network helper executable is |
3205 | ``/path/to/qemu-bridge-helper`` and the default bridge device is | |
3206 | ``br0``. | |
3207 | ||
3208 | ``fd``\ =h can be used to specify the handle of an already opened | |
3209 | host TAP interface. | |
3210 | ||
3211 | Examples: | |
3212 | ||
09ce5f2d | 3213 | .. parsed-literal:: |
e2fcbf42 PM |
3214 | |
3215 | #launch a QEMU instance with the default network script | |
3216 | |qemu_system| linux.img -nic tap | |
3217 | ||
09ce5f2d | 3218 | .. parsed-literal:: |
e2fcbf42 PM |
3219 | |
3220 | #launch a QEMU instance with two NICs, each one connected | |
3221 | #to a TAP device | |
353a06b4 LE |
3222 | |qemu_system| linux.img \\ |
3223 | -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \\ | |
e2fcbf42 PM |
3224 | -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 |
3225 | ||
09ce5f2d | 3226 | .. parsed-literal:: |
e2fcbf42 PM |
3227 | |
3228 | #launch a QEMU instance with the default network helper to | |
3229 | #connect a TAP device to bridge br0 | |
353a06b4 | 3230 | |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\ |
e2fcbf42 PM |
3231 | -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" |
3232 | ||
3233 | ``-netdev bridge,id=id[,br=bridge][,helper=helper]`` | |
3234 | Connect a host TAP network interface to a host bridge device. | |
3235 | ||
3236 | Use the network helper helper to configure the TAP interface and | |
3237 | attach it to the bridge. The default network helper executable is | |
3238 | ``/path/to/qemu-bridge-helper`` and the default bridge device is | |
3239 | ``br0``. | |
3240 | ||
3241 | Examples: | |
3242 | ||
09ce5f2d | 3243 | .. parsed-literal:: |
e2fcbf42 PM |
3244 | |
3245 | #launch a QEMU instance with the default network helper to | |
3246 | #connect a TAP device to bridge br0 | |
3247 | |qemu_system| linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 | |
3248 | ||
09ce5f2d | 3249 | .. parsed-literal:: |
e2fcbf42 PM |
3250 | |
3251 | #launch a QEMU instance with the default network helper to | |
3252 | #connect a TAP device to bridge qemubr0 | |
3253 | |qemu_system| linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 | |
3254 | ||
3255 | ``-netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]`` | |
3256 | This host network backend can be used to connect the guest's network | |
3257 | to another QEMU virtual machine using a TCP socket connection. If | |
3258 | ``listen`` is specified, QEMU waits for incoming connections on port | |
3259 | (host is optional). ``connect`` is used to connect to another QEMU | |
3260 | instance using the ``listen`` option. ``fd``\ =h specifies an | |
3261 | already opened TCP socket. | |
3262 | ||
3263 | Example: | |
3264 | ||
09ce5f2d | 3265 | .. parsed-literal:: |
e2fcbf42 PM |
3266 | |
3267 | # launch a first QEMU instance | |
353a06b4 LE |
3268 | |qemu_system| linux.img \\ |
3269 | -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\ | |
e2fcbf42 PM |
3270 | -netdev socket,id=n1,listen=:1234 |
3271 | # connect the network of this instance to the network of the first instance | |
353a06b4 LE |
3272 | |qemu_system| linux.img \\ |
3273 | -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\ | |
e2fcbf42 PM |
3274 | -netdev socket,id=n2,connect=127.0.0.1:1234 |
3275 | ||
3276 | ``-netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]`` | |
3277 | Configure a socket host network backend to share the guest's network | |
3278 | traffic with another QEMU virtual machines using a UDP multicast | |
3279 | socket, effectively making a bus for every QEMU with same multicast | |
3280 | address maddr and port. NOTES: | |
3281 | ||
3282 | 1. Several QEMU can be running on different hosts and share same bus | |
3283 | (assuming correct multicast setup for these hosts). | |
3284 | ||
3285 | 2. mcast support is compatible with User Mode Linux (argument | |
3286 | ``ethN=mcast``), see http://user-mode-linux.sf.net. | |
3287 | ||
3288 | 3. Use ``fd=h`` to specify an already opened UDP multicast socket. | |
3289 | ||
3290 | Example: | |
3291 | ||
09ce5f2d | 3292 | .. parsed-literal:: |
e2fcbf42 PM |
3293 | |
3294 | # launch one QEMU instance | |
353a06b4 LE |
3295 | |qemu_system| linux.img \\ |
3296 | -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\ | |
e2fcbf42 PM |
3297 | -netdev socket,id=n1,mcast=230.0.0.1:1234 |
3298 | # launch another QEMU instance on same "bus" | |
353a06b4 LE |
3299 | |qemu_system| linux.img \\ |
3300 | -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\ | |
e2fcbf42 PM |
3301 | -netdev socket,id=n2,mcast=230.0.0.1:1234 |
3302 | # launch yet another QEMU instance on same "bus" | |
353a06b4 LE |
3303 | |qemu_system| linux.img \\ |
3304 | -device e1000,netdev=n3,mac=52:54:00:12:34:58 \\ | |
e2fcbf42 PM |
3305 | -netdev socket,id=n3,mcast=230.0.0.1:1234 |
3306 | ||
3307 | Example (User Mode Linux compat.): | |
3308 | ||
09ce5f2d | 3309 | .. parsed-literal:: |
e2fcbf42 PM |
3310 | |
3311 | # launch QEMU instance (note mcast address selected is UML's default) | |
353a06b4 LE |
3312 | |qemu_system| linux.img \\ |
3313 | -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\ | |
e2fcbf42 PM |
3314 | -netdev socket,id=n1,mcast=239.192.168.1:1102 |
3315 | # launch UML | |
3316 | /path/to/linux ubd0=/path/to/root_fs eth0=mcast | |
3317 | ||
3318 | Example (send packets from host's 1.2.3.4): | |
3319 | ||
3320 | .. parsed-literal:: | |
3321 | ||
353a06b4 LE |
3322 | |qemu_system| linux.img \\ |
3323 | -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\ | |
e2fcbf42 PM |
3324 | -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 |
3325 | ||
8b0dc246 | 3326 | ``-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 |
3327 | Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931) |
3328 | is a popular protocol to transport Ethernet (and other Layer 2) data | |
3329 | frames between two systems. It is present in routers, firewalls and | |
3330 | the Linux kernel (from version 3.3 onwards). | |
3331 | ||
3332 | This transport allows a VM to communicate to another VM, router or | |
3333 | firewall directly. | |
3334 | ||
3335 | ``src=srcaddr`` | |
3336 | source address (mandatory) | |
3337 | ||
3338 | ``dst=dstaddr`` | |
3339 | destination address (mandatory) | |
3340 | ||
3341 | ``udp`` | |
3342 | select udp encapsulation (default is ip). | |
3343 | ||
3344 | ``srcport=srcport`` | |
3345 | source udp port. | |
3346 | ||
3347 | ``dstport=dstport`` | |
3348 | destination udp port. | |
3349 | ||
3350 | ``ipv6`` | |
3351 | force v6, otherwise defaults to v4. | |
3352 | ||
3353 | ``rxcookie=rxcookie``; \ ``txcookie=txcookie`` | |
3354 | Cookies are a weak form of security in the l2tpv3 specification. | |
3355 | Their function is mostly to prevent misconfiguration. By default | |
3356 | they are 32 bit. | |
3357 | ||
3358 | ``cookie64`` | |
3359 | Set cookie size to 64 bit instead of the default 32 | |
3360 | ||
3361 | ``counter=off`` | |
3362 | Force a 'cut-down' L2TPv3 with no counter as in | |
3363 | draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 | |
3364 | ||
3365 | ``pincounter=on`` | |
3366 | Work around broken counter handling in peer. This may also help | |
3367 | on networks which have packet reorder. | |
3368 | ||
3369 | ``offset=offset`` | |
3370 | Add an extra offset between header and data | |
3371 | ||
3372 | For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to | |
3373 | the bridge br-lan on the remote Linux host 1.2.3.4: | |
3374 | ||
09ce5f2d | 3375 | .. parsed-literal:: |
e2fcbf42 PM |
3376 | |
3377 | # Setup tunnel on linux host using raw ip as encapsulation | |
3378 | # on 1.2.3.4 | |
353a06b4 | 3379 | ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \\ |
e2fcbf42 | 3380 | encap udp udp_sport 16384 udp_dport 16384 |
353a06b4 | 3381 | ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \\ |
e2fcbf42 PM |
3382 | 0xFFFFFFFF peer_session_id 0xFFFFFFFF |
3383 | ifconfig vmtunnel0 mtu 1500 | |
3384 | ifconfig vmtunnel0 up | |
3385 | brctl addif br-lan vmtunnel0 | |
3386 | ||
3387 | ||
3388 | # on 4.3.2.1 | |
3389 | # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter | |
3390 | ||
353a06b4 | 3391 | |qemu_system| linux.img -device e1000,netdev=n1 \\ |
e2fcbf42 PM |
3392 | -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter |
3393 | ||
3394 | ``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]`` | |
3395 | Configure VDE backend to connect to PORT n of a vde switch running | |
3396 | on host and listening for incoming connections on socketpath. Use | |
3397 | GROUP groupname and MODE octalmode to change default ownership and | |
3398 | permissions for communication port. This option is only available if | |
3399 | QEMU has been compiled with vde support enabled. | |
3400 | ||
3401 | Example: | |
3402 | ||
09ce5f2d | 3403 | .. parsed-literal:: |
e2fcbf42 PM |
3404 | |
3405 | # launch vde switch | |
3406 | vde_switch -F -sock /tmp/myswitch | |
3407 | # launch QEMU instance | |
3408 | |qemu_system| linux.img -nic vde,sock=/tmp/myswitch | |
3409 | ||
cb039ef3 IM |
3410 | ``-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]`` |
3411 | Configure AF_XDP backend to connect to a network interface 'name' | |
3412 | using AF_XDP socket. A specific program attach mode for a default | |
3413 | XDP program can be forced with 'mode', defaults to best-effort, | |
3414 | where the likely most performant mode will be in use. Number of queues | |
3415 | 'n' should generally match the number or queues in the interface, | |
3416 | defaults to 1. Traffic arriving on non-configured device queues will | |
3417 | not be delivered to the network backend. | |
3418 | ||
3419 | .. parsed-literal:: | |
3420 | ||
3421 | # set number of queues to 4 | |
3422 | ethtool -L eth0 combined 4 | |
3423 | # launch QEMU instance | |
3424 | |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\ | |
3425 | -netdev af-xdp,id=n1,ifname=eth0,queues=4 | |
3426 | ||
3427 | 'start-queue' option can be specified if a particular range of queues | |
3428 | [m, m + n] should be in use. For example, this is may be necessary in | |
3429 | order to use certain NICs in native mode. Kernel allows the driver to | |
3430 | create a separate set of XDP queues on top of regular ones, and only | |
3431 | these queues can be used for AF_XDP sockets. NICs that work this way | |
3432 | may also require an additional traffic redirection with ethtool to these | |
3433 | special queues. | |
3434 | ||
3435 | .. parsed-literal:: | |
3436 | ||
3437 | # set number of queues to 1 | |
3438 | ethtool -L eth0 combined 1 | |
3439 | # redirect all the traffic to the second queue (id: 1) | |
3440 | # note: drivers may require non-empty key/mask pair. | |
3441 | ethtool -N eth0 flow-type ether \\ | |
3442 | dst 00:00:00:00:00:00 m FF:FF:FF:FF:FF:FE action 1 | |
3443 | ethtool -N eth0 flow-type ether \\ | |
3444 | dst 00:00:00:00:00:01 m FF:FF:FF:FF:FF:FE action 1 | |
3445 | # launch QEMU instance | |
3446 | |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\ | |
3447 | -netdev af-xdp,id=n1,ifname=eth0,queues=1,start-queue=1 | |
3448 | ||
3449 | XDP program can also be loaded externally. In this case 'inhibit' option | |
3450 | should be set to 'on' and 'sock-fds' provided with file descriptors for | |
3451 | already open but not bound XDP sockets already added to a socket map for | |
3452 | corresponding queues. One socket per queue. | |
3453 | ||
3454 | .. parsed-literal:: | |
3455 | ||
3456 | |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\ | |
3457 | -netdev af-xdp,id=n1,ifname=eth0,queues=3,inhibit=on,sock-fds=15:16:17 | |
3458 | ||
e2fcbf42 PM |
3459 | ``-netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]`` |
3460 | Establish a vhost-user netdev, backed by a chardev id. The chardev | |
3461 | should be a unix domain socket backed one. The vhost-user uses a | |
3462 | specifically defined protocol to pass vhost ioctl replacement | |
3463 | messages to an application on the other end of the socket. On | |
3464 | non-MSIX guests, the feature can be forced with vhostforce. Use | |
3465 | 'queues=n' to specify the number of queues to be created for | |
3466 | multiqueue vhost-user. | |
3467 | ||
3468 | Example: | |
3469 | ||
3470 | :: | |
3471 | ||
3472 | qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ | |
3473 | -numa node,memdev=mem \ | |
3474 | -chardev socket,id=chr0,path=/path/to/socket \ | |
3475 | -netdev type=vhost-user,id=net0,chardev=chr0 \ | |
3476 | -device virtio-net-pci,netdev=net0 | |
3477 | ||
8801ccd0 | 3478 | ``-netdev vhost-vdpa[,vhostdev=/path/to/dev][,vhostfd=h]`` |
108a6481 CL |
3479 | Establish a vhost-vdpa netdev. |
3480 | ||
3481 | vDPA device is a device that uses a datapath which complies with | |
3482 | the virtio specifications with a vendor specific control path. | |
3483 | vDPA devices can be both physically located on the hardware or | |
3484 | emulated by software. | |
3485 | ||
e2fcbf42 PM |
3486 | ``-netdev hubport,id=id,hubid=hubid[,netdev=nd]`` |
3487 | Create a hub port on the emulated hub with ID hubid. | |
3488 | ||
3489 | The hubport netdev lets you connect a NIC to a QEMU emulated hub | |
3490 | instead of a single netdev. Alternatively, you can also connect the | |
3491 | hubport to another netdev with ID nd by using the ``netdev=nd`` | |
3492 | option. | |
3493 | ||
3494 | ``-net nic[,netdev=nd][,macaddr=mac][,model=type] [,name=name][,addr=addr][,vectors=v]`` | |
3495 | Legacy option to configure or create an on-board (or machine | |
3496 | default) Network Interface Card(NIC) and connect it either to the | |
3497 | emulated hub with ID 0 (i.e. the default hub), or to the netdev nd. | |
3498 | If model is omitted, then the default NIC model associated with the | |
3499 | machine type is used. Note that the default NIC model may change in | |
3500 | future QEMU releases, so it is highly recommended to always specify | |
3501 | a model. Optionally, the MAC address can be changed to mac, the | |
3502 | device address set to addr (PCI cards only), and a name can be | |
3503 | assigned for use in monitor commands. Optionally, for PCI cards, you | |
3504 | can specify the number v of MSI-X vectors that the card should have; | |
3505 | this option currently only affects virtio cards; set v = 0 to | |
3506 | disable MSI-X. If no ``-net`` option is specified, a single NIC is | |
3507 | created. QEMU can emulate several different models of network card. | |
3508 | Use ``-net nic,model=help`` for a list of available devices for your | |
3509 | target. | |
3510 | ||
3511 | ``-net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]`` | |
3512 | Configure a host network backend (with the options corresponding to | |
3513 | the same ``-netdev`` option) and connect it to the emulated hub 0 | |
3514 | (the default hub). Use name to specify the name of the hub port. | |
3515 | ERST | |
5824d651 | 3516 | |
7273a2db MB |
3517 | DEFHEADING() |
3518 | ||
de6b4f90 | 3519 | DEFHEADING(Character device options:) |
7273a2db MB |
3520 | |
3521 | DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, | |
517b3d40 | 3522 | "-chardev help\n" |
d0d7708b | 3523 | "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
ba858d1f | 3524 | "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]\n" |
bfdc1267 | 3525 | " [,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]\n" |
fd4a5fd4 | 3526 | " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n" |
bfdc1267 | 3527 | "-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]\n" |
e339273b | 3528 | " [,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)\n" |
7273a2db | 3529 | "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" |
bfdc1267 | 3530 | " [,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]\n" |
d0d7708b DB |
3531 | " [,logfile=PATH][,logappend=on|off]\n" |
3532 | "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" | |
7273a2db | 3533 | "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" |
d0d7708b DB |
3534 | " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
3535 | "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" | |
5b18a6bf | 3536 | "-chardev file,id=id,path=path[,input-path=input-file][,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
d0d7708b | 3537 | "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
7273a2db | 3538 | #ifdef _WIN32 |
d0d7708b DB |
3539 | "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
3540 | "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" | |
7273a2db | 3541 | #else |
d0d7708b DB |
3542 | "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
3543 | "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" | |
7273a2db MB |
3544 | #endif |
3545 | #ifdef CONFIG_BRLAPI | |
d0d7708b | 3546 | "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
7273a2db MB |
3547 | #endif |
3548 | #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ | |
3549 | || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) | |
d0d7708b | 3550 | "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
7273a2db MB |
3551 | #endif |
3552 | #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) | |
d0d7708b | 3553 | "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" |
cbcc6336 AL |
3554 | #endif |
3555 | #if defined(CONFIG_SPICE) | |
d0d7708b DB |
3556 | "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" |
3557 | "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" | |
7273a2db | 3558 | #endif |
ad96090a | 3559 | , QEMU_ARCH_ALL |
7273a2db MB |
3560 | ) |
3561 | ||
e2fcbf42 PM |
3562 | SRST |
3563 | The general form of a character device option is: | |
3564 | ||
3565 | ``-chardev backend,id=id[,mux=on|off][,options]`` | |
3566 | Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``, | |
3567 | ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``, | |
6f9f6308 | 3568 | ``pty``, ``stdio``, ``braille``, ``parallel``, |
e2fcbf42 PM |
3569 | ``spicevmc``, ``spiceport``. The specific backend will determine the |
3570 | applicable options. | |
3571 | ||
3572 | Use ``-chardev help`` to print all available chardev backend types. | |
3573 | ||
3574 | All devices must have an id, which can be any string up to 127 | |
3575 | characters long. It is used to uniquely identify this device in | |
3576 | other command line directives. | |
3577 | ||
3578 | A character device may be used in multiplexing mode by multiple | |
3579 | front-ends. Specify ``mux=on`` to enable this mode. A multiplexer is | |
3580 | a "1:N" device, and here the "1" end is your specified chardev | |
3581 | backend, and the "N" end is the various parts of QEMU that can talk | |
3582 | to a chardev. If you create a chardev with ``id=myid`` and | |
3583 | ``mux=on``, QEMU will create a multiplexer with your specified ID, | |
3584 | and you can then configure multiple front ends to use that chardev | |
3585 | ID for their input/output. Up to four different front ends can be | |
3586 | connected to a single multiplexed chardev. (Without multiplexing | |
3587 | enabled, a chardev can only be used by a single front end.) For | |
3588 | instance you could use this to allow a single stdio chardev to be | |
3589 | used by two serial ports and the QEMU monitor: | |
3590 | ||
3591 | :: | |
3592 | ||
3593 | -chardev stdio,mux=on,id=char0 \ | |
3594 | -mon chardev=char0,mode=readline \ | |
3595 | -serial chardev:char0 \ | |
3596 | -serial chardev:char0 | |
3597 | ||
3598 | You can have more than one multiplexer in a system configuration; | |
3599 | for instance you could have a TCP port multiplexed between UART 0 | |
3600 | and UART 1, and stdio multiplexed between the QEMU monitor and a | |
3601 | parallel port: | |
3602 | ||
3603 | :: | |
3604 | ||
3605 | -chardev stdio,mux=on,id=char0 \ | |
3606 | -mon chardev=char0,mode=readline \ | |
3607 | -parallel chardev:char0 \ | |
3608 | -chardev tcp,...,mux=on,id=char1 \ | |
3609 | -serial chardev:char1 \ | |
3610 | -serial chardev:char1 | |
3611 | ||
3612 | When you're using a multiplexed character device, some escape | |
923e9311 TH |
3613 | sequences are interpreted in the input. See the chapter about |
3614 | :ref:`keys in the character backend multiplexer` in the | |
3615 | System Emulation Users Guide for more details. | |
e2fcbf42 PM |
3616 | |
3617 | Note that some other command line options may implicitly create | |
3618 | multiplexed character backends; for instance ``-serial mon:stdio`` | |
3619 | creates a multiplexed stdio backend connected to the serial port and | |
3620 | the QEMU monitor, and ``-nographic`` also multiplexes the console | |
3621 | and the monitor to stdio. | |
3622 | ||
3623 | There is currently no support for multiplexing in the other | |
3624 | direction (where a single QEMU front end takes input and output from | |
3625 | multiple chardevs). | |
3626 | ||
3627 | Every backend supports the ``logfile`` option, which supplies the | |
3628 | path to a file to record all data transmitted via the backend. The | |
3629 | ``logappend`` option controls whether the log file will be truncated | |
3630 | or appended to when opened. | |
3631 | ||
3632 | The available backends are: | |
3633 | ||
3634 | ``-chardev null,id=id`` | |
3635 | A void device. This device will not emit any data, and will drop any | |
3636 | data it receives. The null backend does not take any options. | |
3637 | ||
bfdc1267 | 3638 | ``-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 |
3639 | Create a two-way stream socket, which can be either a TCP or a unix |
3640 | socket. A unix socket will be created if ``path`` is specified. | |
3641 | Behaviour is undefined if TCP options are specified for a unix | |
3642 | socket. | |
3643 | ||
bfdc1267 | 3644 | ``server=on|off`` specifies that the socket shall be a listening socket. |
e2fcbf42 | 3645 | |
bfdc1267 | 3646 | ``wait=on|off`` specifies that QEMU should not block waiting for a client |
e2fcbf42 PM |
3647 | to connect to a listening socket. |
3648 | ||
bfdc1267 | 3649 | ``telnet=on|off`` specifies that traffic on the socket should interpret |
e2fcbf42 PM |
3650 | telnet escape sequences. |
3651 | ||
bfdc1267 | 3652 | ``websocket=on|off`` specifies that the socket uses WebSocket protocol for |
e2fcbf42 PM |
3653 | communication. |
3654 | ||
3655 | ``reconnect`` sets the timeout for reconnecting on non-server | |
3656 | sockets when the remote end goes away. qemu will delay this many | |
3657 | seconds and then attempt to reconnect. Zero disables reconnecting, | |
3658 | and is the default. | |
3659 | ||
3660 | ``tls-creds`` requests enablement of the TLS protocol for | |
3661 | encryption, and specifies the id of the TLS credentials to use for | |
3662 | the handshake. The credentials must be previously created with the | |
3663 | ``-object tls-creds`` argument. | |
3664 | ||
3665 | ``tls-auth`` provides the ID of the QAuthZ authorization object | |
3666 | against which the client's x509 distinguished name will be | |
3667 | validated. This object is only resolved at time of use, so can be | |
3668 | deleted and recreated on the fly while the chardev server is active. | |
3669 | If missing, it will default to denying access. | |
3670 | ||
3671 | TCP and unix socket options are given below: | |
3672 | ||
a9b1315f | 3673 | ``TCP options: port=port[,host=host][,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]`` |
e2fcbf42 PM |
3674 | ``host`` for a listening socket specifies the local address to |
3675 | be bound. For a connecting socket species the remote host to | |
3676 | connect to. ``host`` is optional for listening sockets. If not | |
3677 | specified it defaults to ``0.0.0.0``. | |
3678 | ||
3679 | ``port`` for a listening socket specifies the local port to be | |
3680 | bound. For a connecting socket specifies the port on the remote | |
3681 | host to connect to. ``port`` can be given as either a port | |
3682 | number or a service name. ``port`` is required. | |
3683 | ||
3684 | ``to`` is only relevant to listening sockets. If it is | |
3685 | specified, and ``port`` cannot be bound, QEMU will attempt to | |
3686 | bind to subsequent ports up to and including ``to`` until it | |
3687 | succeeds. ``to`` must be specified as a port number. | |
3688 | ||
bfdc1267 DB |
3689 | ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4 |
3690 | or IPv6 must be used. If neither is specified the socket may | |
3691 | use either protocol. | |
e2fcbf42 | 3692 | |
a9b1315f | 3693 | ``nodelay=on|off`` disables the Nagle algorithm. |
e2fcbf42 | 3694 | |
e339273b | 3695 | ``unix options: path=path[,abstract=on|off][,tight=on|off]`` |
e2fcbf42 PM |
3696 | ``path`` specifies the local path of the unix socket. ``path`` |
3697 | is required. | |
bfdc1267 | 3698 | ``abstract=on|off`` specifies the use of the abstract socket namespace, |
e339273b | 3699 | rather than the filesystem. Optional, defaults to false. |
bfdc1267 | 3700 | ``tight=on|off`` sets the socket length of abstract sockets to their minimum, |
e339273b | 3701 | rather than the full sun_path length. Optional, defaults to true. |
e2fcbf42 | 3702 | |
bfdc1267 | 3703 | ``-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4=on|off][,ipv6=on|off]`` |
e2fcbf42 PM |
3704 | Sends all traffic from the guest to a remote host over UDP. |
3705 | ||
3706 | ``host`` specifies the remote host to connect to. If not specified | |
3707 | it defaults to ``localhost``. | |
3708 | ||
3709 | ``port`` specifies the port on the remote host to connect to. | |
3710 | ``port`` is required. | |
3711 | ||
3712 | ``localaddr`` specifies the local address to bind to. If not | |
3713 | specified it defaults to ``0.0.0.0``. | |
3714 | ||
3715 | ``localport`` specifies the local port to bind to. If not specified | |
3716 | any available local port will be used. | |
3717 | ||
bfdc1267 | 3718 | ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4 or IPv6 must be used. |
e2fcbf42 PM |
3719 | If neither is specified the device may use either protocol. |
3720 | ||
3721 | ``-chardev msmouse,id=id`` | |
3722 | Forward QEMU's emulated msmouse events to the guest. ``msmouse`` | |
3723 | does not take any options. | |
3724 | ||
3725 | ``-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]`` | |
3726 | Connect to a QEMU text console. ``vc`` may optionally be given a | |
3727 | specific size. | |
3728 | ||
3729 | ``width`` and ``height`` specify the width and height respectively | |
3730 | of the console, in pixels. | |
3731 | ||
3732 | ``cols`` and ``rows`` specify that the console be sized to fit a | |
3733 | text console with the given dimensions. | |
3734 | ||
3735 | ``-chardev ringbuf,id=id[,size=size]`` | |
3736 | Create a ring buffer with fixed size ``size``. size must be a power | |
3737 | of two and defaults to ``64K``. | |
3738 | ||
5b18a6bf | 3739 | ``-chardev file,id=id,path=path[,input-path=input-path]`` |
e2fcbf42 PM |
3740 | Log all traffic received from the guest to a file. |
3741 | ||
3742 | ``path`` specifies the path of the file to be opened. This file will | |
3743 | be created if it does not already exist, and overwritten if it does. | |
3744 | ``path`` is required. | |
3745 | ||
5b18a6bf PM |
3746 | If ``input-path`` is specified, this is the path of a second file |
3747 | which will be used for input. If ``input-path`` is not specified, | |
3748 | no input will be available from the chardev. | |
3749 | ||
3750 | Note that ``input-path`` is not supported on Windows hosts. | |
3751 | ||
e2fcbf42 PM |
3752 | ``-chardev pipe,id=id,path=path`` |
3753 | Create a two-way connection to the guest. The behaviour differs | |
3754 | slightly between Windows hosts and other hosts: | |
3755 | ||
3756 | On Windows, a single duplex pipe will be created at | |
3757 | ``\\.pipe\path``. | |
3758 | ||
3759 | On other hosts, 2 pipes will be created called ``path.in`` and | |
3760 | ``path.out``. Data written to ``path.in`` will be received by the | |
3761 | guest. Data written by the guest can be read from ``path.out``. QEMU | |
3762 | will not create these fifos, and requires them to be present. | |
3763 | ||
3764 | ``path`` forms part of the pipe path as described above. ``path`` is | |
3765 | required. | |
3766 | ||
3767 | ``-chardev console,id=id`` | |
3768 | Send traffic from the guest to QEMU's standard output. ``console`` | |
3769 | does not take any options. | |
3770 | ||
3771 | ``console`` is only available on Windows hosts. | |
3772 | ||
3773 | ``-chardev serial,id=id,path=path`` | |
3774 | Send traffic from the guest to a serial device on the host. | |
3775 | ||
3776 | On Unix hosts serial will actually accept any tty device, not only | |
3777 | serial lines. | |
3778 | ||
3779 | ``path`` specifies the name of the serial device to open. | |
3780 | ||
3781 | ``-chardev pty,id=id`` | |
3782 | Create a new pseudo-terminal on the host and connect to it. ``pty`` | |
3783 | does not take any options. | |
3784 | ||
3785 | ``pty`` is not available on Windows hosts. | |
3786 | ||
3787 | ``-chardev stdio,id=id[,signal=on|off]`` | |
3788 | Connect to standard input and standard output of the QEMU process. | |
3789 | ||
3790 | ``signal`` controls if signals are enabled on the terminal, that | |
3791 | includes exiting QEMU with the key sequence Control-c. This option | |
3792 | is enabled by default, use ``signal=off`` to disable it. | |
3793 | ||
3794 | ``-chardev braille,id=id`` | |
3795 | Connect to a local BrlAPI server. ``braille`` does not take any | |
3796 | options. | |
3797 | ||
09ce5f2d PM |
3798 | ``-chardev parallel,id=id,path=path`` |
3799 | \ | |
e2fcbf42 PM |
3800 | ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD |
3801 | hosts. | |
3802 | ||
3803 | Connect to a local parallel port. | |
3804 | ||
3805 | ``path`` specifies the path to the parallel port device. ``path`` is | |
3806 | required. | |
3807 | ||
3808 | ``-chardev spicevmc,id=id,debug=debug,name=name`` | |
3809 | ``spicevmc`` is only available when spice support is built in. | |
3810 | ||
3811 | ``debug`` debug level for spicevmc | |
3812 | ||
3813 | ``name`` name of spice channel to connect to | |
3814 | ||
3815 | Connect to a spice virtual machine channel, such as vdiport. | |
3816 | ||
3817 | ``-chardev spiceport,id=id,debug=debug,name=name`` | |
3818 | ``spiceport`` is only available when spice support is built in. | |
3819 | ||
3820 | ``debug`` debug level for spicevmc | |
3821 | ||
3822 | ``name`` name of spice port to connect to | |
3823 | ||
3824 | Connect to a spice port, allowing a Spice client to handle the | |
3825 | traffic identified by a name (preferably a fqdn). | |
3826 | ERST | |
5a49d3e9 | 3827 | |
7273a2db MB |
3828 | DEFHEADING() |
3829 | ||
d1a0cf73 | 3830 | #ifdef CONFIG_TPM |
de6b4f90 | 3831 | DEFHEADING(TPM device options:) |
d1a0cf73 SB |
3832 | |
3833 | DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ | |
92dcc234 SB |
3834 | "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" |
3835 | " use path to provide path to a character device; default is /dev/tpm0\n" | |
3836 | " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" | |
f4ede81e AV |
3837 | " not provided it will be searched for in /sys/class/misc/tpm?/device\n" |
3838 | "-tpmdev emulator,id=id,chardev=dev\n" | |
3839 | " configure the TPM device using chardev backend\n", | |
d1a0cf73 | 3840 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
3841 | SRST |
3842 | The general form of a TPM device option is: | |
3843 | ||
3844 | ``-tpmdev backend,id=id[,options]`` | |
3845 | The specific backend type will determine the applicable options. The | |
3846 | ``-tpmdev`` option creates the TPM backend and requires a | |
3847 | ``-device`` option that specifies the TPM frontend interface model. | |
3848 | ||
3849 | Use ``-tpmdev help`` to print all available TPM backend types. | |
3850 | ||
3851 | The available backends are: | |
3852 | ||
3853 | ``-tpmdev passthrough,id=id,path=path,cancel-path=cancel-path`` | |
3854 | (Linux-host only) Enable access to the host's TPM using the | |
3855 | passthrough driver. | |
3856 | ||
3857 | ``path`` specifies the path to the host's TPM device, i.e., on a | |
3858 | Linux host this would be ``/dev/tpm0``. ``path`` is optional and by | |
3859 | default ``/dev/tpm0`` is used. | |
3860 | ||
3861 | ``cancel-path`` specifies the path to the host TPM device's sysfs | |
3862 | entry allowing for cancellation of an ongoing TPM command. | |
3863 | ``cancel-path`` is optional and by default QEMU will search for the | |
3864 | sysfs entry to use. | |
3865 | ||
3866 | Some notes about using the host's TPM with the passthrough driver: | |
3867 | ||
3868 | The TPM device accessed by the passthrough driver must not be used | |
3869 | by any other application on the host. | |
3870 | ||
3871 | Since the host's firmware (BIOS/UEFI) has already initialized the | |
3872 | TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize | |
3873 | the TPM again and may therefore not show a TPM-specific menu that | |
3874 | would otherwise allow the user to configure the TPM, e.g., allow the | |
3875 | user to enable/disable or activate/deactivate the TPM. Further, if | |
3876 | TPM ownership is released from within a VM then the host's TPM will | |
3877 | get disabled and deactivated. To enable and activate the TPM again | |
3878 | afterwards, the host has to be rebooted and the user is required to | |
3879 | enter the firmware's menu to enable and activate the TPM. If the TPM | |
3880 | is left disabled and/or deactivated most TPM commands will fail. | |
3881 | ||
3882 | To create a passthrough TPM use the following two options: | |
3883 | ||
3884 | :: | |
3885 | ||
3886 | -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 | |
3887 | ||
3888 | Note that the ``-tpmdev`` id is ``tpm0`` and is referenced by | |
3889 | ``tpmdev=tpm0`` in the device option. | |
3890 | ||
3891 | ``-tpmdev emulator,id=id,chardev=dev`` | |
3892 | (Linux-host only) Enable access to a TPM emulator using Unix domain | |
3893 | socket based chardev backend. | |
3894 | ||
3895 | ``chardev`` specifies the unique ID of a character device backend | |
3896 | that provides connection to the software TPM server. | |
3897 | ||
3898 | To create a TPM emulator backend device with chardev socket backend: | |
3899 | ||
3900 | :: | |
3901 | ||
3902 | -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 | |
3903 | ERST | |
d1a0cf73 SB |
3904 | |
3905 | DEFHEADING() | |
3906 | ||
3907 | #endif | |
3908 | ||
1235cf7d AB |
3909 | DEFHEADING(Boot Image or Kernel specific:) |
3910 | SRST | |
3911 | There are broadly 4 ways you can boot a system with QEMU. | |
3912 | ||
3913 | - specify a firmware and let it control finding a kernel | |
3914 | - specify a firmware and pass a hint to the kernel to boot | |
3915 | - direct kernel image boot | |
3916 | - manually load files into the guest's address space | |
3917 | ||
3918 | The third method is useful for quickly testing kernels but as there is | |
3919 | no firmware to pass configuration information to the kernel the | |
3920 | hardware must either be probeable, the kernel built for the exact | |
3921 | configuration or passed some configuration data (e.g. a DTB blob) | |
3922 | which tells the kernel what drivers it needs. This exact details are | |
3923 | often hardware specific. | |
3924 | ||
3925 | The final method is the most generic way of loading images into the | |
3926 | guest address space and used mostly for ``bare metal`` type | |
3927 | development where the reset vectors of the processor are taken into | |
3928 | account. | |
3929 | ||
3930 | ERST | |
3931 | ||
e2fcbf42 | 3932 | SRST |
e2fcbf42 | 3933 | |
1235cf7d AB |
3934 | For x86 machines and some other architectures ``-bios`` will generally |
3935 | do the right thing with whatever it is given. For other machines the | |
3936 | more strict ``-pflash`` option needs an image that is sized for the | |
3937 | flash device for the given machine type. | |
3938 | ||
3939 | Please see the :ref:`system-targets-ref` section of the manual for | |
3940 | more detailed documentation. | |
3941 | ||
3942 | ERST | |
3943 | ||
3944 | DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ | |
3945 | "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) | |
3946 | SRST | |
3947 | ``-bios file`` | |
3948 | Set the filename for the BIOS. | |
3949 | ERST | |
3950 | ||
3951 | DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, | |
3952 | "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) | |
3953 | SRST | |
3954 | ``-pflash file`` | |
3955 | Use file as a parallel flash image. | |
3956 | ERST | |
3957 | ||
3958 | SRST | |
3959 | ||
3960 | The kernel options were designed to work with Linux kernels although | |
3961 | other things (like hypervisors) can be packaged up as a kernel | |
3962 | executable image. The exact format of a executable image is usually | |
3963 | architecture specific. | |
3964 | ||
3965 | The way in which the kernel is started (what address it is loaded at, | |
3966 | what if any information is passed to it via CPU registers, the state | |
3967 | of the hardware when it is started, and so on) is also architecture | |
3968 | specific. Typically it follows the specification laid down by the | |
3969 | Linux kernel for how kernels for that architecture must be started. | |
e2fcbf42 PM |
3970 | |
3971 | ERST | |
5824d651 BS |
3972 | |
3973 | DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ | |
ad96090a | 3974 | "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
3975 | SRST |
3976 | ``-kernel bzImage`` | |
3977 | Use bzImage as kernel image. The kernel can be either a Linux kernel | |
3978 | or in multiboot format. | |
3979 | ERST | |
5824d651 BS |
3980 | |
3981 | DEF("append", HAS_ARG, QEMU_OPTION_append, \ | |
ad96090a | 3982 | "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
3983 | SRST |
3984 | ``-append cmdline`` | |
3985 | Use cmdline as kernel command line | |
3986 | ERST | |
5824d651 BS |
3987 | |
3988 | DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ | |
ad96090a | 3989 | "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) |
e2fcbf42 | 3990 | SRST |
cc9d10b9 | 3991 | |
e2fcbf42 PM |
3992 | ``-initrd file`` |
3993 | Use file as initial ram disk. | |
3994 | ||
3995 | ``-initrd "file1 arg=foo,file2"`` | |
3996 | This syntax is only available with multiboot. | |
3997 | ||
cc9d10b9 DW |
3998 | Use file1 and file2 as modules and pass ``arg=foo`` as parameter to the |
3999 | first module. Commas can be provided in module parameters by doubling | |
4000 | them on the command line to escape them: | |
4001 | ||
4002 | ``-initrd "bzImage earlyprintk=xen,,keep root=/dev/xvda1,initrd.img"`` | |
4003 | Multiboot only. Use bzImage as the first module with | |
4004 | "``earlyprintk=xen,keep root=/dev/xvda1``" as its command line, | |
4005 | and initrd.img as the second module. | |
4006 | ||
e2fcbf42 | 4007 | ERST |
5824d651 | 4008 | |
412beee6 | 4009 | DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ |
379b5c7c | 4010 | "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4011 | SRST |
4012 | ``-dtb file`` | |
4013 | Use file as a device tree binary (dtb) image and pass it to the | |
4014 | kernel on boot. | |
4015 | ERST | |
412beee6 | 4016 | |
1235cf7d AB |
4017 | SRST |
4018 | ||
4019 | Finally you can also manually load images directly into the address | |
4020 | space of the guest. This is most useful for developers who already | |
4021 | know the layout of their guest and take care to ensure something sane | |
4022 | will happen when the reset vector executes. | |
4023 | ||
4024 | The generic loader can be invoked by using the loader device: | |
4025 | ||
4026 | ``-device loader,addr=<addr>,data=<data>,data-len=<data-len>[,data-be=<data-be>][,cpu-num=<cpu-num>]`` | |
4027 | ||
4028 | there is also the guest loader which operates in a similar way but | |
4029 | tweaks the DTB so a hypervisor loaded via ``-kernel`` can find where | |
4030 | the guest image is: | |
4031 | ||
4032 | ``-device guest-loader,addr=<addr>[,kernel=<path>,[bootargs=<arguments>]][,initrd=<path>]`` | |
4033 | ||
4034 | ERST | |
4035 | ||
5824d651 BS |
4036 | DEFHEADING() |
4037 | ||
de6b4f90 | 4038 | DEFHEADING(Debug/Expert options:) |
5824d651 | 4039 | |
6dd75472 | 4040 | DEF("compat", HAS_ARG, QEMU_OPTION_compat, |
dbb675c1 | 4041 | "-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]\n" |
57df0dff MA |
4042 | " Policy for handling deprecated management interfaces\n" |
4043 | "-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]\n" | |
4044 | " Policy for handling unstable management interfaces\n", | |
6dd75472 MA |
4045 | QEMU_ARCH_ALL) |
4046 | SRST | |
4047 | ``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]`` | |
4048 | Set policy for handling deprecated management interfaces (experimental): | |
4049 | ||
4050 | ``deprecated-input=accept`` (default) | |
4051 | Accept deprecated commands and arguments | |
4052 | ``deprecated-input=reject`` | |
4053 | Reject deprecated commands and arguments | |
dbb675c1 MA |
4054 | ``deprecated-input=crash`` |
4055 | Crash on deprecated commands and arguments | |
6dd75472 MA |
4056 | ``deprecated-output=accept`` (default) |
4057 | Emit deprecated command results and events | |
4058 | ``deprecated-output=hide`` | |
4059 | Suppress deprecated command results and events | |
4060 | ||
4061 | Limitation: covers only syntactic aspects of QMP. | |
57df0dff MA |
4062 | |
4063 | ``-compat [unstable-input=@var{input-policy}][,unstable-output=@var{output-policy}]`` | |
4064 | Set policy for handling unstable management interfaces (experimental): | |
4065 | ||
4066 | ``unstable-input=accept`` (default) | |
4067 | Accept unstable commands and arguments | |
4068 | ``unstable-input=reject`` | |
4069 | Reject unstable commands and arguments | |
4070 | ``unstable-input=crash`` | |
4071 | Crash on unstable commands and arguments | |
4072 | ``unstable-output=accept`` (default) | |
4073 | Emit unstable command results and events | |
4074 | ``unstable-output=hide`` | |
4075 | Suppress unstable command results and events | |
4076 | ||
4077 | Limitation: covers only syntactic aspects of QMP. | |
6dd75472 MA |
4078 | ERST |
4079 | ||
81b2b810 GS |
4080 | DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, |
4081 | "-fw_cfg [name=]<name>,file=<file>\n" | |
63d3145a | 4082 | " add named fw_cfg entry with contents from file\n" |
6407d76e | 4083 | "-fw_cfg [name=]<name>,string=<str>\n" |
63d3145a | 4084 | " add named fw_cfg entry with contents from string\n", |
81b2b810 | 4085 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4086 | SRST |
4087 | ``-fw_cfg [name=]name,file=file`` | |
4088 | Add named fw\_cfg entry with contents from file file. | |
4089 | ||
4090 | ``-fw_cfg [name=]name,string=str`` | |
4091 | Add named fw\_cfg entry with contents from string str. | |
4092 | ||
4093 | The terminating NUL character of the contents of str will not be | |
4094 | included as part of the fw\_cfg item data. To insert contents with | |
4095 | embedded NUL characters, you have to use the file parameter. | |
4096 | ||
4097 | The fw\_cfg entries are passed by QEMU through to the guest. | |
4098 | ||
4099 | Example: | |
4100 | ||
4101 | :: | |
4102 | ||
4103 | -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin | |
4104 | ||
4105 | creates an fw\_cfg entry named opt/com.mycompany/blob with contents | |
4106 | from ./my\_blob.bin. | |
4107 | ERST | |
81b2b810 | 4108 | |
5824d651 | 4109 | DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ |
ad96090a BS |
4110 | "-serial dev redirect the serial port to char device 'dev'\n", |
4111 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4112 | SRST |
4113 | ``-serial dev`` | |
4114 | Redirect the virtual serial port to host character device dev. The | |
4115 | default device is ``vc`` in graphical mode and ``stdio`` in non | |
4116 | graphical mode. | |
4117 | ||
4118 | This option can be used several times to simulate up to 4 serial | |
4119 | ports. | |
4120 | ||
4121 | Use ``-serial none`` to disable all serial ports. | |
4122 | ||
4123 | Available character devices are: | |
4124 | ||
4125 | ``vc[:WxH]`` | |
4126 | Virtual console. Optionally, a width and height can be given in | |
4127 | pixel with | |
4128 | ||
4129 | :: | |
4130 | ||
4131 | vc:800x600 | |
4132 | ||
4133 | It is also possible to specify width or height in characters: | |
4134 | ||
4135 | :: | |
4136 | ||
4137 | vc:80Cx24C | |
4138 | ||
4139 | ``pty`` | |
4140 | [Linux only] Pseudo TTY (a new PTY is automatically allocated) | |
4141 | ||
4142 | ``none`` | |
4143 | No device is allocated. | |
4144 | ||
4145 | ``null`` | |
4146 | void device | |
4147 | ||
4148 | ``chardev:id`` | |
4149 | Use a named character device defined with the ``-chardev`` | |
4150 | option. | |
4151 | ||
4152 | ``/dev/XXX`` | |
4153 | [Linux only] Use host tty, e.g. ``/dev/ttyS0``. The host serial | |
4154 | port parameters are set according to the emulated ones. | |
4155 | ||
4156 | ``/dev/parportN`` | |
4157 | [Linux only, parallel port only] Use host parallel port N. | |
4158 | Currently SPP and EPP parallel port features can be used. | |
4159 | ||
4160 | ``file:filename`` | |
4161 | Write output to filename. No character can be read. | |
4162 | ||
4163 | ``stdio`` | |
4164 | [Unix only] standard input/output | |
4165 | ||
4166 | ``pipe:filename`` | |
4167 | name pipe filename | |
4168 | ||
4169 | ``COMn`` | |
4170 | [Windows only] Use host serial port n | |
4171 | ||
4172 | ``udp:[remote_host]:remote_port[@[src_ip]:src_port]`` | |
4173 | This implements UDP Net Console. When remote\_host or src\_ip | |
4174 | are not specified they default to ``0.0.0.0``. When not using a | |
4175 | specified src\_port a random port is automatically chosen. | |
4176 | ||
4177 | If you just want a simple readonly console you can use | |
4178 | ``netcat`` or ``nc``, by starting QEMU with: | |
4179 | ``-serial udp::4555`` and nc as: ``nc -u -l -p 4555``. Any time | |
4180 | QEMU writes something to that port it will appear in the | |
4181 | netconsole session. | |
4182 | ||
4183 | If you plan to send characters back via netconsole or you want | |
4184 | to stop and start QEMU a lot of times, you should have QEMU use | |
4185 | the same source port each time by using something like ``-serial | |
4186 | udp::4555@:4556`` to QEMU. Another approach is to use a patched | |
4187 | version of netcat which can listen to a TCP port and send and | |
4188 | receive characters via udp. If you have a patched version of | |
4189 | netcat which activates telnet remote echo and single char | |
4190 | transfer, then you can use the following options to set up a | |
4191 | netcat redirector to allow telnet on port 5555 to access the | |
4192 | QEMU port. | |
4193 | ||
4194 | ``QEMU Options:`` | |
4195 | -serial udp::4555@:4556 | |
4196 | ||
4197 | ``netcat options:`` | |
4198 | -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T | |
4199 | ||
4200 | ``telnet options:`` | |
4201 | localhost 5555 | |
4202 | ||
a9b1315f | 4203 | ``tcp:[host]:port[,server=on|off][,wait=on|off][,nodelay=on|off][,reconnect=seconds]`` |
e2fcbf42 PM |
4204 | The TCP Net Console has two modes of operation. It can send the |
4205 | serial I/O to a location or wait for a connection from a | |
4206 | location. By default the TCP Net Console is sent to host at the | |
bfdc1267 | 4207 | port. If you use the ``server=on`` option QEMU will wait for a client |
e2fcbf42 | 4208 | socket application to connect to the port before continuing, |
a9b1315f | 4209 | unless the ``wait=on|off`` option was specified. The ``nodelay=on|off`` |
bfdc1267 DB |
4210 | option disables the Nagle buffering algorithm. The ``reconnect=on`` |
4211 | option only applies if ``server=no`` is set, if the connection goes | |
e2fcbf42 PM |
4212 | down it will attempt to reconnect at the given interval. If host |
4213 | is omitted, 0.0.0.0 is assumed. Only one TCP connection at a | |
bfdc1267 | 4214 | time is accepted. You can use ``telnet=on`` to connect to the |
e2fcbf42 PM |
4215 | corresponding character device. |
4216 | ||
4217 | ``Example to send tcp console to 192.168.0.2 port 4444`` | |
4218 | -serial tcp:192.168.0.2:4444 | |
4219 | ||
4220 | ``Example to listen and wait on port 4444 for connection`` | |
bfdc1267 | 4221 | -serial tcp::4444,server=on |
e2fcbf42 PM |
4222 | |
4223 | ``Example to not wait and listen on ip 192.168.0.100 port 4444`` | |
bfdc1267 | 4224 | -serial tcp:192.168.0.100:4444,server=on,wait=off |
e2fcbf42 | 4225 | |
a9b1315f | 4226 | ``telnet:host:port[,server=on|off][,wait=on|off][,nodelay=on|off]`` |
e2fcbf42 PM |
4227 | The telnet protocol is used instead of raw tcp sockets. The |
4228 | options work the same as if you had specified ``-serial tcp``. | |
4229 | The difference is that the port acts like a telnet server or | |
4230 | client using telnet option negotiation. This will also allow you | |
4231 | to send the MAGIC\_SYSRQ sequence if you use a telnet that | |
4232 | supports sending the break sequence. Typically in unix telnet | |
4233 | you do it with Control-] and then type "send break" followed by | |
4234 | pressing the enter key. | |
4235 | ||
a9b1315f | 4236 | ``websocket:host:port,server=on[,wait=on|off][,nodelay=on|off]`` |
e2fcbf42 PM |
4237 | The WebSocket protocol is used instead of raw tcp socket. The |
4238 | port acts as a WebSocket server. Client mode is not supported. | |
4239 | ||
bfdc1267 | 4240 | ``unix:path[,server=on|off][,wait=on|off][,reconnect=seconds]`` |
e2fcbf42 PM |
4241 | A unix domain socket is used instead of a tcp socket. The option |
4242 | works the same as if you had specified ``-serial tcp`` except | |
4243 | the unix domain socket path is used for connections. | |
4244 | ||
4245 | ``mon:dev_string`` | |
4246 | This is a special option to allow the monitor to be multiplexed | |
4247 | onto another serial port. The monitor is accessed with key | |
4248 | sequence of Control-a and then pressing c. dev\_string should be | |
4249 | any one of the serial devices specified above. An example to | |
4250 | multiplex the monitor onto a telnet server listening on port | |
4251 | 4444 would be: | |
4252 | ||
bfdc1267 | 4253 | ``-serial mon:telnet::4444,server=on,wait=off`` |
e2fcbf42 PM |
4254 | |
4255 | When the monitor is multiplexed to stdio in this way, Ctrl+C | |
4256 | will not terminate QEMU any more but will be passed to the guest | |
4257 | instead. | |
4258 | ||
4259 | ``braille`` | |
4260 | Braille device. This will use BrlAPI to display the braille | |
4261 | output on a real or fake device. | |
4262 | ||
4263 | ``msmouse`` | |
4264 | Three button serial mouse. Configure the guest to use Microsoft | |
4265 | protocol. | |
4266 | ERST | |
5824d651 BS |
4267 | |
4268 | DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ | |
ad96090a BS |
4269 | "-parallel dev redirect the parallel port to char device 'dev'\n", |
4270 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4271 | SRST |
4272 | ``-parallel dev`` | |
4273 | Redirect the virtual parallel port to host device dev (same devices | |
4274 | as the serial port). On Linux hosts, ``/dev/parportN`` can be used | |
4275 | to use hardware devices connected on the corresponding host parallel | |
4276 | port. | |
4277 | ||
4278 | This option can be used several times to simulate up to 3 parallel | |
4279 | ports. | |
4280 | ||
4281 | Use ``-parallel none`` to disable all parallel ports. | |
4282 | ERST | |
5824d651 BS |
4283 | |
4284 | DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ | |
ad96090a BS |
4285 | "-monitor dev redirect the monitor to char device 'dev'\n", |
4286 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4287 | SRST |
4288 | ``-monitor dev`` | |
4289 | Redirect the monitor to host device dev (same devices as the serial | |
4290 | port). The default device is ``vc`` in graphical mode and ``stdio`` | |
4291 | in non graphical mode. Use ``-monitor none`` to disable the default | |
4292 | monitor. | |
4293 | ERST | |
6ca5582d | 4294 | DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ |
ad96090a BS |
4295 | "-qmp dev like -monitor but opens in 'control' mode\n", |
4296 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4297 | SRST |
4298 | ``-qmp dev`` | |
0ec4468f PM |
4299 | Like ``-monitor`` but opens in 'control' mode. For example, to make |
4300 | QMP available on localhost port 4444:: | |
4301 | ||
4302 | -qmp tcp:localhost:4444,server=on,wait=off | |
4303 | ||
4304 | Not all options are configurable via this syntax; for maximum | |
4305 | flexibility use the ``-mon`` option and an accompanying ``-chardev``. | |
4306 | ||
e2fcbf42 | 4307 | ERST |
4821cd4c HR |
4308 | DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ |
4309 | "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", | |
4310 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4311 | SRST |
4312 | ``-qmp-pretty dev`` | |
0ec4468f | 4313 | Like ``-qmp`` but uses pretty JSON formatting. |
e2fcbf42 | 4314 | ERST |
5824d651 | 4315 | |
22a0e04b | 4316 | DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ |
ef670726 | 4317 | "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4318 | SRST |
4319 | ``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]`` | |
0ec4468f PM |
4320 | Set up a monitor connected to the chardev ``name``. |
4321 | QEMU supports two monitors: the Human Monitor Protocol | |
4322 | (HMP; for human interaction), and the QEMU Monitor Protocol | |
4323 | (QMP; a JSON RPC-style protocol). | |
4324 | The default is HMP; ``mode=control`` selects QMP instead. | |
4325 | ``pretty`` is only valid when ``mode=control``, | |
16b3f3bb | 4326 | turning on JSON pretty printing to ease |
283d845c | 4327 | human reading and debugging. |
0ec4468f PM |
4328 | |
4329 | For example:: | |
4330 | ||
4331 | -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \ | |
4332 | -mon chardev=mon1,mode=control,pretty=on | |
4333 | ||
4334 | enables the QMP monitor on localhost port 4444 with pretty-printing. | |
e2fcbf42 | 4335 | ERST |
22a0e04b | 4336 | |
c9f398e5 | 4337 | DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ |
ad96090a BS |
4338 | "-debugcon dev redirect the debug console to char device 'dev'\n", |
4339 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4340 | SRST |
4341 | ``-debugcon dev`` | |
4342 | Redirect the debug console to host device dev (same devices as the | |
4343 | serial port). The debug console is an I/O port which is typically | |
4344 | port 0xe9; writing to that I/O port sends output to this device. The | |
4345 | default device is ``vc`` in graphical mode and ``stdio`` in non | |
4346 | graphical mode. | |
4347 | ERST | |
c9f398e5 | 4348 | |
5824d651 | 4349 | DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ |
ad96090a | 4350 | "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4351 | SRST |
4352 | ``-pidfile file`` | |
4353 | Store the QEMU process PID in file. It is useful if you launch QEMU | |
4354 | from a script. | |
4355 | ERST | |
5824d651 | 4356 | |
1b530a6d | 4357 | DEF("singlestep", 0, QEMU_OPTION_singlestep, \ |
12fd0f41 | 4358 | "-singlestep deprecated synonym for -accel tcg,one-insn-per-tb=on\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4359 | SRST |
4360 | ``-singlestep`` | |
12fd0f41 PM |
4361 | This is a deprecated synonym for the TCG accelerator property |
4362 | ``one-insn-per-tb``. | |
e2fcbf42 | 4363 | ERST |
1b530a6d | 4364 | |
047f7038 | 4365 | DEF("preconfig", 0, QEMU_OPTION_preconfig, \ |
361ac948 | 4366 | "--preconfig pause QEMU before machine is initialized (experimental)\n", |
047f7038 | 4367 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4368 | SRST |
4369 | ``--preconfig`` | |
4370 | Pause QEMU for interactive configuration before the machine is | |
4371 | created, which allows querying and configuring properties that will | |
4372 | affect machine initialization. Use QMP command 'x-exit-preconfig' to | |
4373 | exit the preconfig state and move to the next state (i.e. run guest | |
4374 | if -S isn't used or pause the second time if -S is used). This | |
4375 | option is experimental. | |
4376 | ERST | |
047f7038 | 4377 | |
5824d651 | 4378 | DEF("S", 0, QEMU_OPTION_S, \ |
ad96090a BS |
4379 | "-S freeze CPU at startup (use 'c' to start execution)\n", |
4380 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4381 | SRST |
4382 | ``-S`` | |
4383 | Do not start CPU at startup (you must type 'c' in the monitor). | |
4384 | ERST | |
5824d651 | 4385 | |
6f131f13 | 4386 | DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, |
dfaa7d50 | 4387 | "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" |
6f131f13 MT |
4388 | " run qemu with overcommit hints\n" |
4389 | " mem-lock=on|off controls memory lock support (default: off)\n" | |
4390 | " cpu-pm=on|off controls cpu power management (default: off)\n", | |
4391 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4392 | SRST |
4393 | ``-overcommit mem-lock=on|off`` | |
09ce5f2d | 4394 | \ |
e2fcbf42 PM |
4395 | ``-overcommit cpu-pm=on|off`` |
4396 | Run qemu with hints about host resource overcommit. The default is | |
4397 | to assume that host overcommits all resources. | |
4398 | ||
4399 | Locking qemu and guest memory can be enabled via ``mem-lock=on`` | |
4400 | (disabled by default). This works when host memory is not | |
c8c9dc42 | 4401 | overcommitted and reduces the worst-case latency for guest. |
e2fcbf42 PM |
4402 | |
4403 | Guest ability to manage power state of host cpus (increasing latency | |
4404 | for other processes on the same host cpu, but decreasing latency for | |
4405 | guest) can be enabled via ``cpu-pm=on`` (disabled by default). This | |
4406 | works best when host CPU is not overcommitted. When used, host | |
4407 | estimates of CPU cycle and power utilization will be incorrect, not | |
4408 | taking into account guest idle time. | |
4409 | ERST | |
6f131f13 | 4410 | |
59030a8c | 4411 | DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ |
e5910d42 PM |
4412 | "-gdb dev accept gdb connection on 'dev'. (QEMU defaults to starting\n" |
4413 | " the guest without waiting for gdb to connect; use -S too\n" | |
4414 | " if you want it to not start execution.)\n", | |
4415 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4416 | SRST |
4417 | ``-gdb dev`` | |
923e9311 TH |
4418 | Accept a gdb connection on device dev (see the :ref:`GDB usage` chapter |
4419 | in the System Emulation Users Guide). Note that this option does not pause QEMU | |
e5910d42 PM |
4420 | execution -- if you want QEMU to not start the guest until you |
4421 | connect with gdb and issue a ``continue`` command, you will need to | |
4422 | also pass the ``-S`` option to QEMU. | |
4423 | ||
4424 | The most usual configuration is to listen on a local TCP socket:: | |
4425 | ||
4426 | -gdb tcp::3117 | |
4427 | ||
4428 | but you can specify other backends; UDP, pseudo TTY, or even stdio | |
4429 | are all reasonable use cases. For example, a stdio connection | |
4430 | allows you to start QEMU from within gdb and establish the | |
4431 | connection via a pipe: | |
e2fcbf42 | 4432 | |
09ce5f2d | 4433 | .. parsed-literal:: |
e2fcbf42 PM |
4434 | |
4435 | (gdb) target remote | exec |qemu_system| -gdb stdio ... | |
4436 | ERST | |
5824d651 | 4437 | |
59030a8c | 4438 | DEF("s", 0, QEMU_OPTION_s, \ |
ad96090a BS |
4439 | "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", |
4440 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4441 | SRST |
4442 | ``-s`` | |
4443 | Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 | |
923e9311 | 4444 | (see the :ref:`GDB usage` chapter in the System Emulation Users Guide). |
e2fcbf42 | 4445 | ERST |
5824d651 BS |
4446 | |
4447 | DEF("d", HAS_ARG, QEMU_OPTION_d, \ | |
989b697d | 4448 | "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", |
ad96090a | 4449 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4450 | SRST |
4451 | ``-d item1[,...]`` | |
4452 | Enable logging of specified items. Use '-d help' for a list of log | |
4453 | items. | |
4454 | ERST | |
5824d651 | 4455 | |
c235d738 | 4456 | DEF("D", HAS_ARG, QEMU_OPTION_D, \ |
989b697d | 4457 | "-D logfile output log to logfile (default stderr)\n", |
c235d738 | 4458 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4459 | SRST |
4460 | ``-D logfile`` | |
4461 | Output log in logfile instead of to stderr | |
4462 | ERST | |
c235d738 | 4463 | |
3514552e AB |
4464 | DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ |
4465 | "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", | |
4466 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4467 | SRST |
4468 | ``-dfilter range1[,...]`` | |
4469 | Filter debug output to that relevant to a range of target addresses. | |
4470 | The filter spec can be either start+size, start-size or start..end | |
4471 | where start end and size are the addresses and sizes required. For | |
4472 | example: | |
4473 | ||
4474 | :: | |
4475 | ||
4476 | -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 | |
4477 | ||
4478 | Will dump output for any code in the 0x1000 sized block starting at | |
4479 | 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and | |
4480 | another 0x1000 sized block starting at 0xffffffc00005f000. | |
4481 | ERST | |
3514552e | 4482 | |
9c09a251 RH |
4483 | DEF("seed", HAS_ARG, QEMU_OPTION_seed, \ |
4484 | "-seed number seed the pseudo-random number generator\n", | |
4485 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4486 | SRST |
4487 | ``-seed number`` | |
4488 | Force the guest to use a deterministic pseudo-random number | |
4489 | generator, seeded with number. This does not affect crypto routines | |
4490 | within the host. | |
4491 | ERST | |
9c09a251 | 4492 | |
5824d651 | 4493 | DEF("L", HAS_ARG, QEMU_OPTION_L, \ |
ad96090a BS |
4494 | "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", |
4495 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4496 | SRST |
4497 | ``-L path`` | |
4498 | Set the directory for the BIOS, VGA BIOS and keymaps. | |
4499 | ||
4500 | To list all the data directories, use ``-L help``. | |
4501 | ERST | |
5824d651 | 4502 | |
5824d651 | 4503 | DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ |
21abf010 TH |
4504 | "-enable-kvm enable KVM full virtualization support\n", |
4505 | QEMU_ARCH_ARM | QEMU_ARCH_I386 | QEMU_ARCH_MIPS | QEMU_ARCH_PPC | | |
4506 | QEMU_ARCH_RISCV | QEMU_ARCH_S390X) | |
e2fcbf42 PM |
4507 | SRST |
4508 | ``-enable-kvm`` | |
4509 | Enable KVM full virtualization support. This option is only | |
4510 | available if KVM support is enabled when compiling. | |
4511 | ERST | |
5824d651 | 4512 | |
e37630ca | 4513 | DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, |
eeb3647c TH |
4514 | "-xen-domid id specify xen guest domain id\n", |
4515 | QEMU_ARCH_ARM | QEMU_ARCH_I386) | |
e37630ca AL |
4516 | DEF("xen-attach", 0, QEMU_OPTION_xen_attach, |
4517 | "-xen-attach attach to existing xen domain\n" | |
1077bcac | 4518 | " libxl will use this when starting QEMU\n", |
eeb3647c | 4519 | QEMU_ARCH_ARM | QEMU_ARCH_I386) |
1c599472 PD |
4520 | DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, |
4521 | "-xen-domid-restrict restrict set of available xen operations\n" | |
4522 | " to specified domain id. (Does not affect\n" | |
4523 | " xenpv machine type).\n", | |
eeb3647c | 4524 | QEMU_ARCH_ARM | QEMU_ARCH_I386) |
e2fcbf42 PM |
4525 | SRST |
4526 | ``-xen-domid id`` | |
4527 | Specify xen guest domain id (XEN only). | |
4528 | ||
4529 | ``-xen-attach`` | |
4530 | Attach to existing xen domain. libxl will use this when starting | |
4531 | QEMU (XEN only). Restrict set of available xen operations to | |
4532 | specified domain id (XEN only). | |
4533 | ERST | |
e37630ca | 4534 | |
5824d651 | 4535 | DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ |
ad96090a | 4536 | "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4537 | SRST |
4538 | ``-no-reboot`` | |
4539 | Exit instead of rebooting. | |
4540 | ERST | |
5824d651 BS |
4541 | |
4542 | DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ | |
ad96090a | 4543 | "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4544 | SRST |
4545 | ``-no-shutdown`` | |
4546 | Don't exit QEMU on guest shutdown, but instead only stop the | |
4547 | emulation. This allows for instance switching to monitor to commit | |
4548 | changes to the disk image. | |
4549 | ERST | |
5824d651 | 4550 | |
2a5ad60b | 4551 | DEF("action", HAS_ARG, QEMU_OPTION_action, |
c27025e0 PB |
4552 | "-action reboot=reset|shutdown\n" |
4553 | " action when guest reboots [default=reset]\n" | |
2a5ad60b AJ |
4554 | "-action shutdown=poweroff|pause\n" |
4555 | " action when guest shuts down [default=poweroff]\n" | |
0882caf4 | 4556 | "-action panic=pause|shutdown|exit-failure|none\n" |
c27025e0 | 4557 | " action when guest panics [default=shutdown]\n" |
2a5ad60b AJ |
4558 | "-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" |
4559 | " action when watchdog fires [default=reset]\n", | |
4560 | QEMU_ARCH_ALL) | |
4561 | SRST | |
4562 | ``-action event=action`` | |
4563 | The action parameter serves to modify QEMU's default behavior when | |
4564 | certain guest events occur. It provides a generic method for specifying the | |
4565 | same behaviors that are modified by the ``-no-reboot`` and ``-no-shutdown`` | |
4566 | parameters. | |
4567 | ||
4568 | Examples: | |
4569 | ||
c753e8e7 | 4570 | ``-action panic=none`` |
2a5ad60b | 4571 | ``-action reboot=shutdown,shutdown=pause`` |
5433af76 | 4572 | ``-device i6300esb -action watchdog=pause`` |
2a5ad60b AJ |
4573 | |
4574 | ERST | |
4575 | ||
5824d651 BS |
4576 | DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ |
4577 | "-loadvm [tag|id]\n" \ | |
ad96090a BS |
4578 | " start right away with a saved state (loadvm in monitor)\n", |
4579 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4580 | SRST |
4581 | ``-loadvm file`` | |
4582 | Start right away with a saved state (``loadvm`` in monitor) | |
4583 | ERST | |
5824d651 BS |
4584 | |
4585 | #ifndef _WIN32 | |
4586 | DEF("daemonize", 0, QEMU_OPTION_daemonize, \ | |
ad96090a | 4587 | "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) |
5824d651 | 4588 | #endif |
e2fcbf42 PM |
4589 | SRST |
4590 | ``-daemonize`` | |
4591 | Daemonize the QEMU process after initialization. QEMU will not | |
4592 | detach from standard IO until it is ready to receive connections on | |
4593 | any of its devices. This option is a useful way for external | |
4594 | programs to launch QEMU without having to cope with initialization | |
4595 | race conditions. | |
4596 | ERST | |
5824d651 BS |
4597 | |
4598 | DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ | |
ad96090a BS |
4599 | "-option-rom rom load a file, rom, into the option ROM space\n", |
4600 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4601 | SRST |
4602 | ``-option-rom file`` | |
4603 | Load the contents of file as an option ROM. This option is useful to | |
4604 | load things like EtherBoot. | |
4605 | ERST | |
5824d651 | 4606 | |
1ed2fc1f | 4607 | DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ |
238d1240 | 4608 | "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ |
ad96090a BS |
4609 | " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", |
4610 | QEMU_ARCH_ALL) | |
5824d651 | 4611 | |
e2fcbf42 PM |
4612 | SRST |
4613 | ``-rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]`` | |
4614 | Specify ``base`` as ``utc`` or ``localtime`` to let the RTC start at | |
4615 | the current UTC or local time, respectively. ``localtime`` is | |
4616 | required for correct date in MS-DOS or Windows. To start at a | |
4617 | specific point in time, provide datetime in the format | |
4618 | ``2006-06-17T16:01:21`` or ``2006-06-17``. The default base is UTC. | |
4619 | ||
4620 | By default the RTC is driven by the host system time. This allows | |
4621 | using of the RTC as accurate reference clock inside the guest, | |
4622 | specifically if the host time is smoothly following an accurate | |
4623 | external reference clock, e.g. via NTP. If you want to isolate the | |
4624 | guest time from the host, you can set ``clock`` to ``rt`` instead, | |
4625 | which provides a host monotonic clock if host support it. To even | |
4626 | prevent the RTC from progressing during suspension, you can set | |
4627 | ``clock`` to ``vm`` (virtual clock). '\ ``clock=vm``\ ' is | |
4628 | recommended especially in icount mode in order to preserve | |
4629 | determinism; however, note that in icount mode the speed of the | |
4630 | virtual clock is variable and can in general differ from the host | |
4631 | clock. | |
4632 | ||
4633 | Enable ``driftfix`` (i386 targets only) if you experience time drift | |
4634 | problems, specifically with Windows' ACPI HAL. This option will try | |
4635 | to figure out how many timer interrupts were not processed by the | |
4636 | Windows guest and will re-inject them. | |
4637 | ERST | |
5824d651 BS |
4638 | |
4639 | DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ | |
fa647905 | 4640 | "-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]\n" \ |
bc14ca24 | 4641 | " enable virtual instruction counter with 2^N clock ticks per\n" \ |
f1f4b57e | 4642 | " instruction, enable aligning the host and virtual clocks\n" \ |
fa647905 PM |
4643 | " or disable real time cpu sleeping, and optionally enable\n" \ |
4644 | " record-and-replay mode\n", QEMU_ARCH_ALL) | |
e2fcbf42 | 4645 | SRST |
fa647905 | 4646 | ``-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=filename[,rrsnapshot=snapshot]]`` |
e2fcbf42 PM |
4647 | Enable virtual instruction counter. The virtual cpu will execute one |
4648 | instruction every 2^N ns of virtual time. If ``auto`` is specified | |
4649 | then the virtual cpu speed will be automatically adjusted to keep | |
4650 | virtual time within a few seconds of real time. | |
4651 | ||
e2fcbf42 PM |
4652 | Note that while this option can give deterministic behavior, it does |
4653 | not provide cycle accurate emulation. Modern CPUs contain | |
4654 | superscalar out of order cores with complex cache hierarchies. The | |
4655 | number of instructions executed often has little or no correlation | |
4656 | with actual performance. | |
4657 | ||
fa647905 PM |
4658 | When the virtual cpu is sleeping, the virtual time will advance at |
4659 | default speed unless ``sleep=on`` is specified. With | |
4660 | ``sleep=on``, the virtual time will jump to the next timer | |
4661 | deadline instantly whenever the virtual cpu goes to sleep mode and | |
4662 | will not advance if no timer is enabled. This behavior gives | |
4663 | deterministic execution times from the guest point of view. | |
4664 | The default if icount is enabled is ``sleep=off``. | |
4665 | ``sleep=on`` cannot be used together with either ``shift=auto`` | |
4666 | or ``align=on``. | |
4667 | ||
e2fcbf42 PM |
4668 | ``align=on`` will activate the delay algorithm which will try to |
4669 | synchronise the host clock and the virtual clock. The goal is to | |
4670 | have a guest running at the real frequency imposed by the shift | |
4671 | option. Whenever the guest clock is behind the host clock and if | |
4672 | ``align=on`` is specified then we print a message to the user to | |
4673 | inform about the delay. Currently this option does not work when | |
4674 | ``shift`` is ``auto``. Note: The sync algorithm will work for those | |
4675 | shift values for which the guest clock runs ahead of the host clock. | |
4676 | Typically this happens when the shift value is high (how high | |
fa647905 PM |
4677 | depends on the host machine). The default if icount is enabled |
4678 | is ``align=off``. | |
4679 | ||
4680 | When the ``rr`` option is specified deterministic record/replay is | |
4681 | enabled. The ``rrfile=`` option must also be provided to | |
4682 | specify the path to the replay log. In record mode data is written | |
4683 | to this file, and in replay mode it is read back. | |
4684 | If the ``rrsnapshot`` option is given then it specifies a VM snapshot | |
4685 | name. In record mode, a new VM snapshot with the given name is created | |
4686 | at the start of execution recording. In replay mode this option | |
4687 | specifies the snapshot name used to load the initial VM state. | |
e2fcbf42 | 4688 | ERST |
5824d651 | 4689 | |
9dd986cc | 4690 | DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ |
7ad9270e | 4691 | "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ |
ad96090a BS |
4692 | " action when watchdog fires [default=reset]\n", |
4693 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4694 | SRST |
4695 | ``-watchdog-action action`` | |
4696 | The action controls what QEMU will do when the watchdog timer | |
4697 | expires. The default is ``reset`` (forcefully reset the guest). | |
4698 | Other possible actions are: ``shutdown`` (attempt to gracefully | |
4699 | shutdown the guest), ``poweroff`` (forcefully poweroff the guest), | |
4700 | ``inject-nmi`` (inject a NMI into the guest), ``pause`` (pause the | |
4701 | guest), ``debug`` (print a debug message and continue), or ``none`` | |
4702 | (do nothing). | |
4703 | ||
4704 | Note that the ``shutdown`` action requires that the guest responds | |
4705 | to ACPI signals, which it may not be able to do in the sort of | |
4706 | situations where the watchdog would have expired, and thus | |
4707 | ``-watchdog-action shutdown`` is not recommended for production use. | |
4708 | ||
4709 | Examples: | |
4710 | ||
5433af76 | 4711 | ``-device i6300esb -watchdog-action pause`` |
e2fcbf42 PM |
4712 | |
4713 | ERST | |
9dd986cc | 4714 | |
5824d651 | 4715 | DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ |
ad96090a BS |
4716 | "-echr chr set terminal escape character instead of ctrl-a\n", |
4717 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4718 | SRST |
4719 | ``-echr numeric_ascii_value`` | |
4720 | Change the escape character used for switching to the monitor when | |
4721 | using monitor and serial sharing. The default is ``0x01`` when using | |
4722 | the ``-nographic`` option. ``0x01`` is equal to pressing | |
4723 | ``Control-a``. You can select a different character from the ascii | |
4724 | control keys where 1 through 26 map to Control-a through Control-z. | |
4725 | For instance you could use the either of the following to change the | |
4726 | escape character to Control-t. | |
4727 | ||
4728 | ``-echr 0x14``; \ ``-echr 20`` | |
4729 | ||
4730 | ERST | |
5824d651 | 4731 | |
5824d651 | 4732 | DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ |
bf24095f DB |
4733 | "-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]\n" \ |
4734 | "-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]\n" \ | |
7c601803 MT |
4735 | "-incoming unix:socketpath\n" \ |
4736 | " prepare for incoming migration, listen on\n" \ | |
4737 | " specified protocol and socket address\n" \ | |
4738 | "-incoming fd:fd\n" \ | |
385f510d | 4739 | "-incoming file:filename[,offset=offset]\n" \ |
7c601803 MT |
4740 | "-incoming exec:cmdline\n" \ |
4741 | " accept incoming migration on given file descriptor\n" \ | |
1597051b DDAG |
4742 | " or from given external command\n" \ |
4743 | "-incoming defer\n" \ | |
4744 | " wait for the URI to be specified via migrate_incoming\n", | |
ad96090a | 4745 | QEMU_ARCH_ALL) |
e2fcbf42 | 4746 | SRST |
bf24095f | 4747 | ``-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]`` |
09ce5f2d | 4748 | \ |
bf24095f | 4749 | ``-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]`` |
e2fcbf42 PM |
4750 | Prepare for incoming migration, listen on a given tcp port. |
4751 | ||
4752 | ``-incoming unix:socketpath`` | |
4753 | Prepare for incoming migration, listen on a given unix socket. | |
4754 | ||
4755 | ``-incoming fd:fd`` | |
2a9e2e59 SS |
4756 | Accept incoming migration from a given file descriptor. |
4757 | ||
385f510d SS |
4758 | ``-incoming file:filename[,offset=offset]`` |
4759 | Accept incoming migration from a given file starting at offset. | |
4760 | offset allows the common size suffixes, or a 0x prefix, but not both. | |
e2fcbf42 PM |
4761 | |
4762 | ``-incoming exec:cmdline`` | |
4763 | Accept incoming migration as an output from specified external | |
4764 | command. | |
4765 | ||
4766 | ``-incoming defer`` | |
4767 | Wait for the URI to be specified via migrate\_incoming. The monitor | |
4768 | can be used to change settings (such as migration parameters) prior | |
4769 | to issuing the migrate\_incoming to allow the migration to begin. | |
4770 | ERST | |
5824d651 | 4771 | |
d15c05fc AA |
4772 | DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ |
4773 | "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4774 | SRST |
4775 | ``-only-migratable`` | |
4776 | Only allow migratable devices. Devices will not be allowed to enter | |
4777 | an unmigratable state. | |
4778 | ERST | |
d15c05fc | 4779 | |
d8c208dd | 4780 | DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ |
ad96090a | 4781 | "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) |
e2fcbf42 PM |
4782 | SRST |
4783 | ``-nodefaults`` | |
4784 | Don't create default devices. Normally, QEMU sets the default | |
4785 | devices like serial port, parallel port, virtual console, monitor | |
4786 | device, VGA adapter, floppy and CD-ROM drive and others. The | |
4787 | ``-nodefaults`` option will disable all those default devices. | |
4788 | ERST | |
d8c208dd | 4789 | |
5824d651 BS |
4790 | #ifndef _WIN32 |
4791 | DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ | |
9ffcbe2a | 4792 | "-chroot dir chroot to dir just before starting the VM (deprecated)\n", |
ad96090a | 4793 | QEMU_ARCH_ALL) |
5824d651 | 4794 | #endif |
e2fcbf42 PM |
4795 | SRST |
4796 | ``-chroot dir`` | |
9ffcbe2a | 4797 | Deprecated, use '-run-with chroot=...' instead. |
e2fcbf42 PM |
4798 | Immediately before starting guest execution, chroot to the specified |
4799 | directory. Especially useful in combination with -runas. | |
4800 | ERST | |
5824d651 BS |
4801 | |
4802 | #ifndef _WIN32 | |
4803 | DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ | |
2c42f1e8 IJ |
4804 | "-runas user change to user id user just before starting the VM\n" \ |
4805 | " user can be numeric uid:gid instead\n", | |
ad96090a | 4806 | QEMU_ARCH_ALL) |
5824d651 | 4807 | #endif |
e2fcbf42 PM |
4808 | SRST |
4809 | ``-runas user`` | |
4810 | Immediately before starting guest execution, drop root privileges, | |
4811 | switching to the specified user. | |
4812 | ERST | |
5824d651 | 4813 | |
5824d651 BS |
4814 | DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, |
4815 | "-prom-env variable=value\n" | |
ad96090a BS |
4816 | " set OpenBIOS nvram variables\n", |
4817 | QEMU_ARCH_PPC | QEMU_ARCH_SPARC) | |
e2fcbf42 PM |
4818 | SRST |
4819 | ``-prom-env variable=value`` | |
4820 | Set OpenBIOS nvram variable to given value (PPC, SPARC only). | |
4821 | ||
4822 | :: | |
4823 | ||
4824 | qemu-system-sparc -prom-env 'auto-boot?=false' \ | |
4825 | -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single' | |
4826 | ||
4827 | :: | |
4828 | ||
4829 | qemu-system-ppc -prom-env 'auto-boot?=false' \ | |
4830 | -prom-env 'boot-device=hd:2,\yaboot' \ | |
4831 | -prom-env 'boot-args=conf=hd:2,\yaboot.conf' | |
4832 | ERST | |
5824d651 | 4833 | DEF("semihosting", 0, QEMU_OPTION_semihosting, |
f7bbcfb5 | 4834 | "-semihosting semihosting mode\n", |
9d49bcf6 | 4835 | QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | |
a10b9d93 | 4836 | QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV) |
e2fcbf42 PM |
4837 | SRST |
4838 | ``-semihosting`` | |
2da9d213 | 4839 | Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only). |
e2fcbf42 | 4840 | |
2da9d213 AB |
4841 | .. warning:: |
4842 | Note that this allows guest direct access to the host filesystem, so | |
4843 | should only be used with a trusted guest OS. | |
e2fcbf42 PM |
4844 | |
4845 | See the -semihosting-config option documentation for further | |
4846 | information about the facilities this enables. | |
4847 | ERST | |
a38bb079 | 4848 | DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, |
5202861b | 4849 | "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]\n" \ |
a59d31a1 | 4850 | " semihosting configuration\n", |
9d49bcf6 | 4851 | QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | |
a10b9d93 | 4852 | QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV) |
e2fcbf42 | 4853 | SRST |
5202861b | 4854 | ``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]`` |
2da9d213 | 4855 | Enable and configure :ref:`Semihosting` (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V |
e2fcbf42 PM |
4856 | only). |
4857 | ||
2da9d213 AB |
4858 | .. warning:: |
4859 | Note that this allows guest direct access to the host filesystem, so | |
4860 | should only be used with a trusted guest OS. | |
a10b9d93 | 4861 | |
e2fcbf42 PM |
4862 | ``target=native|gdb|auto`` |
4863 | Defines where the semihosting calls will be addressed, to QEMU | |
4864 | (``native``) or to GDB (``gdb``). The default is ``auto``, which | |
4865 | means ``gdb`` during debug sessions and ``native`` otherwise. | |
4866 | ||
4867 | ``chardev=str1`` | |
4868 | Send the output to a chardev backend output for native or auto | |
4869 | output when not in gdb | |
4870 | ||
5202861b PM |
4871 | ``userspace=on|off`` |
4872 | Allows code running in guest userspace to access the semihosting | |
4873 | interface. The default is that only privileged guest code can | |
4874 | make semihosting calls. Note that setting ``userspace=on`` should | |
4875 | only be used if all guest code is trusted (for example, in | |
4876 | bare-metal test case code). | |
4877 | ||
e2fcbf42 PM |
4878 | ``arg=str1,arg=str2,...`` |
4879 | Allows the user to pass input arguments, and can be used | |
4880 | multiple times to build up a list. The old-style | |
4881 | ``-kernel``/``-append`` method of passing a command line is | |
4882 | still supported for backward compatibility. If both the | |
4883 | ``--semihosting-config arg`` and the ``-kernel``/``-append`` are | |
4884 | specified, the former is passed to semihosting as it always | |
4885 | takes precedence. | |
4886 | ERST | |
5824d651 | 4887 | DEF("old-param", 0, QEMU_OPTION_old_param, |
ad96090a | 4888 | "-old-param old param mode\n", QEMU_ARCH_ARM) |
e2fcbf42 PM |
4889 | SRST |
4890 | ``-old-param`` | |
4891 | Old param mode (ARM only). | |
4892 | ERST | |
95d5f08b | 4893 | |
7d76ad4f | 4894 | DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ |
73a1e647 | 4895 | "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ |
24f8cdc5 | 4896 | " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ |
2b716fa6 EO |
4897 | " Enable seccomp mode 2 system call filter (default 'off').\n" \ |
4898 | " use 'obsolete' to allow obsolete system calls that are provided\n" \ | |
4899 | " by the kernel, but typically no longer used by modern\n" \ | |
73a1e647 | 4900 | " C library implementations.\n" \ |
d42304b1 PMD |
4901 | " use 'elevateprivileges' to allow or deny the QEMU process ability\n" \ |
4902 | " to elevate privileges using set*uid|gid system calls.\n" \ | |
73a1e647 | 4903 | " The value 'children' will deny set*uid|gid system calls for\n" \ |
995a226f EO |
4904 | " main QEMU process but will allow forks and execves to run unprivileged\n" \ |
4905 | " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ | |
d42304b1 | 4906 | " blocking *fork and execve\n" \ |
24f8cdc5 | 4907 | " use 'resourcecontrol' to disable process affinity and schedular priority\n", |
7d76ad4f | 4908 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4909 | SRST |
4910 | ``-sandbox arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]`` | |
4911 | Enable Seccomp mode 2 system call filter. 'on' will enable syscall | |
4912 | filtering and 'off' will disable it. The default is 'off'. | |
4913 | ||
4914 | ``obsolete=string`` | |
4915 | Enable Obsolete system calls | |
4916 | ||
4917 | ``elevateprivileges=string`` | |
4918 | Disable set\*uid\|gid system calls | |
4919 | ||
4920 | ``spawn=string`` | |
4921 | Disable \*fork and execve | |
4922 | ||
4923 | ``resourcecontrol=string`` | |
4924 | Disable process affinity and schedular priority | |
4925 | ERST | |
7d76ad4f | 4926 | |
715a664a | 4927 | DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, |
e960a7ee PB |
4928 | "-readconfig <file>\n" |
4929 | " read config file\n", QEMU_ARCH_ALL) | |
e2fcbf42 PM |
4930 | SRST |
4931 | ``-readconfig file`` | |
4932 | Read device configuration from file. This approach is useful when | |
4933 | you want to spawn QEMU process with many command line options but | |
4934 | you don't want to exceed the command line character limit. | |
4935 | ERST | |
2feac451 | 4936 | |
f29a5614 EH |
4937 | DEF("no-user-config", 0, QEMU_OPTION_nouserconfig, |
4938 | "-no-user-config\n" | |
3478eae9 | 4939 | " do not load default user-provided config files at startup\n", |
f29a5614 | 4940 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4941 | SRST |
4942 | ``-no-user-config`` | |
4943 | The ``-no-user-config`` option makes QEMU not load any of the | |
4944 | user-provided config files on sysconfdir. | |
4945 | ERST | |
2feac451 | 4946 | |
ab6540d5 | 4947 | DEF("trace", HAS_ARG, QEMU_OPTION_trace, |
10578a25 | 4948 | "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" |
23d15e86 | 4949 | " specify tracing options\n", |
ab6540d5 | 4950 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
4951 | SRST |
4952 | ``-trace [[enable=]pattern][,events=file][,file=file]`` | |
09ce5f2d | 4953 | .. include:: ../qemu-option-trace.rst.inc |
e2fcbf42 | 4954 | |
e2fcbf42 | 4955 | ERST |
42229a75 | 4956 | DEF("plugin", HAS_ARG, QEMU_OPTION_plugin, |
3a445acb | 4957 | "-plugin [file=]<file>[,<argname>=<argvalue>]\n" |
42229a75 LV |
4958 | " load a plugin\n", |
4959 | QEMU_ARCH_ALL) | |
e2fcbf42 | 4960 | SRST |
3a445acb | 4961 | ``-plugin file=file[,argname=argvalue]`` |
e2fcbf42 PM |
4962 | Load a plugin. |
4963 | ||
4964 | ``file=file`` | |
4965 | Load the given plugin from a shared library file. | |
4966 | ||
3a445acb MM |
4967 | ``argname=argvalue`` |
4968 | Argument passed to the plugin. (Can be given multiple times.) | |
e2fcbf42 | 4969 | ERST |
3dbf2c7f | 4970 | |
31e70d6c MA |
4971 | HXCOMM Internal use |
4972 | DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) | |
4973 | DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) | |
c7f0f3b1 | 4974 | |
c891c24b CI |
4975 | #ifdef __linux__ |
4976 | DEF("async-teardown", 0, QEMU_OPTION_asyncteardown, | |
4977 | "-async-teardown enable asynchronous teardown\n", | |
4978 | QEMU_ARCH_ALL) | |
c891c24b CI |
4979 | SRST |
4980 | ``-async-teardown`` | |
80bd81ca CI |
4981 | This option is deprecated and should no longer be used. The new option |
4982 | ``-run-with async-teardown=on`` is a replacement. | |
c891c24b | 4983 | ERST |
9ffcbe2a TH |
4984 | #endif |
4985 | #ifdef CONFIG_POSIX | |
80bd81ca | 4986 | DEF("run-with", HAS_ARG, QEMU_OPTION_run_with, |
9ffcbe2a TH |
4987 | "-run-with [async-teardown=on|off][,chroot=dir]\n" |
4988 | " Set miscellaneous QEMU process lifecycle options:\n" | |
4989 | " async-teardown=on enables asynchronous teardown (Linux only)\n" | |
4990 | " chroot=dir chroot to dir just before starting the VM\n", | |
80bd81ca CI |
4991 | QEMU_ARCH_ALL) |
4992 | SRST | |
9ffcbe2a | 4993 | ``-run-with [async-teardown=on|off][,chroot=dir]`` |
80bd81ca CI |
4994 | Set QEMU process lifecycle options. |
4995 | ||
4996 | ``async-teardown=on`` enables asynchronous teardown. A new process called | |
4997 | "cleanup/<QEMU_PID>" will be created at startup sharing the address | |
4998 | space with the main QEMU process, using clone. It will wait for the | |
4999 | main QEMU process to terminate completely, and then exit. This allows | |
5000 | QEMU to terminate very quickly even if the guest was huge, leaving the | |
5001 | teardown of the address space to the cleanup process. Since the cleanup | |
5002 | process shares the same cgroups as the main QEMU process, accounting is | |
5003 | performed correctly. This only works if the cleanup process is not | |
5004 | forcefully killed with SIGKILL before the main QEMU process has | |
5005 | terminated completely. | |
9ffcbe2a TH |
5006 | |
5007 | ``chroot=dir`` can be used for doing a chroot to the specified directory | |
5008 | immediately before starting the guest execution. This is especially useful | |
5009 | in combination with -runas. | |
80bd81ca CI |
5010 | ERST |
5011 | #endif | |
c891c24b | 5012 | |
5e2ac519 | 5013 | DEF("msg", HAS_ARG, QEMU_OPTION_msg, |
2880ffb0 | 5014 | "-msg [timestamp[=on|off]][,guest-name=[on|off]]\n" |
deda497b | 5015 | " control error message format\n" |
2880ffb0 MS |
5016 | " timestamp=on enables timestamps (default: off)\n" |
5017 | " guest-name=on enables guest name prefix but only if\n" | |
5018 | " -name guest option is set (default: off)\n", | |
5e2ac519 | 5019 | QEMU_ARCH_ALL) |
e2fcbf42 | 5020 | SRST |
2880ffb0 | 5021 | ``-msg [timestamp[=on|off]][,guest-name[=on|off]]`` |
e2fcbf42 PM |
5022 | Control error message format. |
5023 | ||
5024 | ``timestamp=on|off`` | |
5025 | Prefix messages with a timestamp. Default is off. | |
2880ffb0 MS |
5026 | |
5027 | ``guest-name=on|off`` | |
5028 | Prefix messages with guest name but only if -name guest option is set | |
5029 | otherwise the option is ignored. Default is off. | |
e2fcbf42 | 5030 | ERST |
5e2ac519 | 5031 | |
abfd9ce3 AS |
5032 | DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, |
5033 | "-dump-vmstate <file>\n" | |
5034 | " Output vmstate information in JSON format to file.\n" | |
5035 | " Use the scripts/vmstate-static-checker.py file to\n" | |
5036 | " check for possible regressions in migration code\n" | |
2382053f | 5037 | " by comparing two such vmstate dumps.\n", |
abfd9ce3 | 5038 | QEMU_ARCH_ALL) |
e2fcbf42 PM |
5039 | SRST |
5040 | ``-dump-vmstate file`` | |
5041 | Dump json-encoded vmstate information for current machine type to | |
5042 | file in file | |
5043 | ERST | |
abfd9ce3 | 5044 | |
12df189d EC |
5045 | DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, |
5046 | "-enable-sync-profile\n" | |
5047 | " enable synchronization profiling\n", | |
5048 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
5049 | SRST |
5050 | ``-enable-sync-profile`` | |
5051 | Enable synchronization profiling. | |
5052 | ERST | |
12df189d | 5053 | |
5584e2db IL |
5054 | #if defined(CONFIG_TCG) && defined(CONFIG_LINUX) |
5055 | DEF("perfmap", 0, QEMU_OPTION_perfmap, | |
5056 | "-perfmap generate a /tmp/perf-${pid}.map file for perf\n", | |
5057 | QEMU_ARCH_ALL) | |
5058 | SRST | |
5059 | ``-perfmap`` | |
5060 | Generate a map file for Linux perf tools that will allow basic profiling | |
5061 | information to be broken down into basic blocks. | |
5062 | ERST | |
5063 | ||
5064 | DEF("jitdump", 0, QEMU_OPTION_jitdump, | |
5065 | "-jitdump generate a jit-${pid}.dump file for perf\n", | |
5066 | QEMU_ARCH_ALL) | |
5067 | SRST | |
5068 | ``-jitdump`` | |
5069 | Generate a dump file for Linux perf tools that maps basic blocks to symbol | |
5070 | names, line numbers and JITted code. | |
5071 | ERST | |
5072 | #endif | |
5073 | ||
43f187a5 | 5074 | DEFHEADING() |
de6b4f90 MA |
5075 | |
5076 | DEFHEADING(Generic object creation:) | |
b9174d4f DB |
5077 | |
5078 | DEF("object", HAS_ARG, QEMU_OPTION_object, | |
5079 | "-object TYPENAME[,PROP1=VALUE1,...]\n" | |
5080 | " create a new object of type TYPENAME setting properties\n" | |
5081 | " in the order they are specified. Note that the 'id'\n" | |
5082 | " property must be set. These objects are placed in the\n" | |
5083 | " '/objects' path.\n", | |
5084 | QEMU_ARCH_ALL) | |
e2fcbf42 PM |
5085 | SRST |
5086 | ``-object typename[,prop1=value1,...]`` | |
5087 | Create a new object of type typename setting properties in the order | |
5088 | they are specified. Note that the 'id' property must be set. These | |
5089 | objects are placed in the '/objects' path. | |
5090 | ||
e92666b0 | 5091 | ``-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 |
5092 | Creates a memory file backend object, which can be used to back |
5093 | the guest RAM with huge pages. | |
5094 | ||
5095 | The ``id`` parameter is a unique ID that will be used to | |
56c9f00e RH |
5096 | reference this memory region in other parameters, e.g. ``-numa``, |
5097 | ``-device nvdimm``, etc. | |
e2fcbf42 PM |
5098 | |
5099 | The ``size`` option provides the size of the memory region, and | |
56c9f00e | 5100 | accepts common suffixes, e.g. ``500M``. |
e2fcbf42 PM |
5101 | |
5102 | The ``mem-path`` provides the path to either a shared memory or | |
5103 | huge page filesystem mount. | |
5104 | ||
5105 | The ``share`` boolean option determines whether the memory | |
5106 | region is marked as private to QEMU, or shared. The latter | |
5107 | allows a co-operating external process to access the QEMU memory | |
5108 | region. | |
5109 | ||
5110 | The ``share`` is also required for pvrdma devices due to | |
5111 | limitations in the RDMA API provided by Linux. | |
5112 | ||
5113 | Setting share=on might affect the ability to configure NUMA | |
5114 | bindings for the memory backend under some circumstances, see | |
5115 | Documentation/vm/numa\_memory\_policy.txt on the Linux kernel | |
5116 | source tree for additional details. | |
5117 | ||
5118 | Setting the ``discard-data`` boolean option to on indicates that | |
5119 | file contents can be destroyed when QEMU exits, to avoid | |
5120 | unnecessarily flushing data to the backing file. Note that | |
5121 | ``discard-data`` is only an optimization, and QEMU might not | |
5122 | discard file contents if it aborts unexpectedly or is terminated | |
5123 | using SIGKILL. | |
5124 | ||
5125 | The ``merge`` boolean option enables memory merge, also known as | |
5126 | MADV\_MERGEABLE, so that Kernel Samepage Merging will consider | |
5127 | the pages for memory deduplication. | |
5128 | ||
5129 | Setting the ``dump`` boolean option to off excludes the memory | |
5130 | from core dumps. This feature is also known as MADV\_DONTDUMP. | |
5131 | ||
5132 | The ``prealloc`` boolean option enables memory preallocation. | |
5133 | ||
5134 | The ``host-nodes`` option binds the memory range to a list of | |
5135 | NUMA host nodes. | |
5136 | ||
5137 | The ``policy`` option sets the NUMA policy to one of the | |
5138 | following values: | |
5139 | ||
5140 | ``default`` | |
5141 | default host policy | |
5142 | ||
5143 | ``preferred`` | |
5144 | prefer the given host node list for allocation | |
5145 | ||
5146 | ``bind`` | |
5147 | restrict memory allocation to the given host node list | |
5148 | ||
5149 | ``interleave`` | |
5150 | interleave memory allocations across the given host node | |
5151 | list | |
5152 | ||
5153 | The ``align`` option specifies the base address alignment when | |
5154 | QEMU mmap(2) ``mem-path``, and accepts common suffixes, eg | |
5155 | ``2M``. Some backend store specified by ``mem-path`` requires an | |
5156 | alignment different than the default one used by QEMU, eg the | |
5157 | device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In | |
5158 | such cases, users can specify the required alignment via this | |
5159 | option. | |
5160 | ||
4b870dc4 AG |
5161 | The ``offset`` option specifies the offset into the target file |
5162 | that the region starts at. You can use this parameter to back | |
5163 | multiple regions with a single file. | |
5164 | ||
e2fcbf42 PM |
5165 | The ``pmem`` option specifies whether the backing file specified |
5166 | by ``mem-path`` is in host persistent memory that can be | |
5167 | accessed using the SNIA NVM programming model (e.g. Intel | |
5168 | NVDIMM). If ``pmem`` is set to 'on', QEMU will take necessary | |
5169 | operations to guarantee the persistence of its own writes to | |
5170 | ``mem-path`` (e.g. in vNVDIMM label emulation and live | |
5171 | migration). Also, we will map the backend-file with MAP\_SYNC | |
5172 | flag, which ensures the file metadata is in sync for | |
5173 | ``mem-path`` in case of host crash or a power failure. MAP\_SYNC | |
5174 | requires support from both the host kernel (since Linux kernel | |
5175 | 4.15) and the filesystem of ``mem-path`` mounted with DAX | |
5176 | option. | |
5177 | ||
86635aa4 SH |
5178 | The ``readonly`` option specifies whether the backing file is opened |
5179 | read-only or read-write (default). | |
e92666b0 DH |
5180 | |
5181 | The ``rom`` option specifies whether to create Read Only Memory | |
5182 | (ROM) that cannot be modified by the VM. Any write attempts to such | |
5183 | ROM will be denied. Most use cases want proper RAM instead of ROM. | |
5184 | However, selected use cases, like R/O NVDIMMs, can benefit from | |
5185 | ROM. If set to ``on``, create ROM; if set to ``off``, create | |
5186 | writable RAM; if set to ``auto`` (default), the value of the | |
5187 | ``readonly`` option is used. This option is primarily helpful when | |
5188 | we want to have writable RAM in configurations that would | |
5189 | traditionally create ROM before the ``rom`` option was introduced: | |
5190 | VM templating, where we want to open a file readonly | |
5191 | (``readonly=on``) and mark the memory to be private for QEMU | |
5192 | (``share=off``). For this use case, we need writable RAM instead | |
5193 | of ROM, and want to also set ``rom=off``. | |
86635aa4 | 5194 | |
e2fcbf42 PM |
5195 | ``-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`` |
5196 | Creates a memory backend object, which can be used to back the | |
5197 | guest RAM. Memory backend objects offer more control than the | |
5198 | ``-m`` option that is traditionally used to define guest RAM. | |
5199 | Please refer to ``memory-backend-file`` for a description of the | |
5200 | options. | |
5201 | ||
5202 | ``-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`` | |
5203 | Creates an anonymous memory file backend object, which allows | |
5204 | QEMU to share the memory with an external process (e.g. when | |
5205 | using vhost-user). The memory is allocated with memfd and | |
5206 | optional sealing. (Linux only) | |
5207 | ||
5208 | The ``seal`` option creates a sealed-file, that will block | |
5209 | further resizing the memory ('on' by default). | |
5210 | ||
5211 | The ``hugetlb`` option specify the file to be created resides in | |
5212 | the hugetlbfs filesystem (since Linux 4.14). Used in conjunction | |
5213 | with the ``hugetlb`` option, the ``hugetlbsize`` option specify | |
5214 | the hugetlb page size on systems that support multiple hugetlb | |
5215 | page sizes (it must be a power of 2 value supported by the | |
5216 | system). | |
5217 | ||
5218 | In some versions of Linux, the ``hugetlb`` option is | |
5219 | incompatible with the ``seal`` option (requires at least Linux | |
5220 | 4.16). | |
5221 | ||
5222 | Please refer to ``memory-backend-file`` for a description of the | |
5223 | other options. | |
5224 | ||
5225 | The ``share`` boolean option is on by default with memfd. | |
5226 | ||
5227 | ``-object rng-builtin,id=id`` | |
5228 | Creates a random number generator backend which obtains entropy | |
5229 | from QEMU builtin functions. The ``id`` parameter is a unique ID | |
5230 | that will be used to reference this entropy backend from the | |
5231 | ``virtio-rng`` device. By default, the ``virtio-rng`` device | |
5232 | uses this RNG backend. | |
5233 | ||
5234 | ``-object rng-random,id=id,filename=/dev/random`` | |
5235 | Creates a random number generator backend which obtains entropy | |
5236 | from a device on the host. The ``id`` parameter is a unique ID | |
5237 | that will be used to reference this entropy backend from the | |
5238 | ``virtio-rng`` device. The ``filename`` parameter specifies | |
5239 | which file to obtain entropy from and if omitted defaults to | |
5240 | ``/dev/urandom``. | |
5241 | ||
5242 | ``-object rng-egd,id=id,chardev=chardevid`` | |
5243 | Creates a random number generator backend which obtains entropy | |
5244 | from an external daemon running on the host. The ``id`` | |
5245 | parameter is a unique ID that will be used to reference this | |
5246 | entropy backend from the ``virtio-rng`` device. The ``chardev`` | |
5247 | parameter is the unique ID of a character device backend that | |
5248 | provides the connection to the RNG daemon. | |
5249 | ||
5250 | ``-object tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off`` | |
5251 | Creates a TLS anonymous credentials object, which can be used to | |
5252 | provide TLS support on network backends. The ``id`` parameter is | |
5253 | a unique ID which network backends will use to access the | |
5254 | credentials. The ``endpoint`` is either ``server`` or ``client`` | |
5255 | depending on whether the QEMU network backend that uses the | |
5256 | credentials will be acting as a client or as a server. If | |
5257 | ``verify-peer`` is enabled (the default) then once the handshake | |
5258 | is completed, the peer credentials will be verified, though this | |
5259 | is a no-op for anonymous credentials. | |
5260 | ||
5261 | The dir parameter tells QEMU where to find the credential files. | |
5262 | For server endpoints, this directory may contain a file | |
5263 | dh-params.pem providing diffie-hellman parameters to use for the | |
5264 | TLS server. If the file is missing, QEMU will generate a set of | |
5265 | DH parameters at startup. This is a computationally expensive | |
5266 | operation that consumes random pool entropy, so it is | |
5267 | recommended that a persistent set of parameters be generated | |
5268 | upfront and saved. | |
5269 | ||
5270 | ``-object tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]`` | |
5271 | Creates a TLS Pre-Shared Keys (PSK) credentials object, which | |
5272 | can be used to provide TLS support on network backends. The | |
5273 | ``id`` parameter is a unique ID which network backends will use | |
5274 | to access the credentials. The ``endpoint`` is either ``server`` | |
5275 | or ``client`` depending on whether the QEMU network backend that | |
5276 | uses the credentials will be acting as a client or as a server. | |
5277 | For clients only, ``username`` is the username which will be | |
5278 | sent to the server. If omitted it defaults to "qemu". | |
5279 | ||
5280 | The dir parameter tells QEMU where to find the keys file. It is | |
5281 | called "dir/keys.psk" and contains "username:key" pairs. This | |
5282 | file can most easily be created using the GnuTLS ``psktool`` | |
5283 | program. | |
5284 | ||
5285 | For server endpoints, dir may also contain a file dh-params.pem | |
5286 | providing diffie-hellman parameters to use for the TLS server. | |
5287 | If the file is missing, QEMU will generate a set of DH | |
5288 | parameters at startup. This is a computationally expensive | |
5289 | operation that consumes random pool entropy, so it is | |
5290 | recommended that a persistent set of parameters be generated up | |
5291 | front and saved. | |
5292 | ||
5293 | ``-object tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id`` | |
5294 | Creates a TLS anonymous credentials object, which can be used to | |
5295 | provide TLS support on network backends. The ``id`` parameter is | |
5296 | a unique ID which network backends will use to access the | |
5297 | credentials. The ``endpoint`` is either ``server`` or ``client`` | |
5298 | depending on whether the QEMU network backend that uses the | |
5299 | credentials will be acting as a client or as a server. If | |
5300 | ``verify-peer`` is enabled (the default) then once the handshake | |
5301 | is completed, the peer credentials will be verified. With x509 | |
5302 | certificates, this implies that the clients must be provided | |
5303 | with valid client certificates too. | |
5304 | ||
5305 | The dir parameter tells QEMU where to find the credential files. | |
5306 | For server endpoints, this directory may contain a file | |
5307 | dh-params.pem providing diffie-hellman parameters to use for the | |
5308 | TLS server. If the file is missing, QEMU will generate a set of | |
5309 | DH parameters at startup. This is a computationally expensive | |
5310 | operation that consumes random pool entropy, so it is | |
5311 | recommended that a persistent set of parameters be generated | |
5312 | upfront and saved. | |
5313 | ||
5314 | For x509 certificate credentials the directory will contain | |
5315 | further files providing the x509 certificates. The certificates | |
5316 | must be stored in PEM format, in filenames ca-cert.pem, | |
5317 | ca-crl.pem (optional), server-cert.pem (only servers), | |
5318 | server-key.pem (only servers), client-cert.pem (only clients), | |
5319 | and client-key.pem (only clients). | |
5320 | ||
5321 | For the server-key.pem and client-key.pem files which contain | |
5322 | sensitive private keys, it is possible to use an encrypted | |
5323 | version by providing the passwordid parameter. This provides the | |
5324 | ID of a previously created ``secret`` object containing the | |
5325 | password for decryption. | |
5326 | ||
5327 | The priority parameter allows to override the global default | |
5328 | priority used by gnutls. This can be useful if the system | |
5329 | administrator needs to use a weaker set of crypto priorities for | |
5330 | QEMU without potentially forcing the weakness onto all | |
5331 | applications. Or conversely if one wants wants a stronger | |
5332 | default for QEMU than for all other applications, they can do | |
5333 | this through this parameter. Its format is a gnutls priority | |
5334 | string as described at | |
5335 | https://gnutls.org/manual/html_node/Priority-Strings.html. | |
5336 | ||
993aec27 PMD |
5337 | ``-object tls-cipher-suites,id=id,priority=priority`` |
5338 | Creates a TLS cipher suites object, which can be used to control | |
5339 | the TLS cipher/protocol algorithms that applications are permitted | |
5340 | to use. | |
5341 | ||
5342 | The ``id`` parameter is a unique ID which frontends will use to | |
5343 | access the ordered list of permitted TLS cipher suites from the | |
5344 | host. | |
5345 | ||
5346 | The ``priority`` parameter allows to override the global default | |
5347 | priority used by gnutls. This can be useful if the system | |
e2fcbf42 PM |
5348 | administrator needs to use a weaker set of crypto priorities for |
5349 | QEMU without potentially forcing the weakness onto all | |
5350 | applications. Or conversely if one wants wants a stronger | |
5351 | default for QEMU than for all other applications, they can do | |
5352 | this through this parameter. Its format is a gnutls priority | |
5353 | string as described at | |
5354 | https://gnutls.org/manual/html_node/Priority-Strings.html. | |
5355 | ||
69699f30 PMD |
5356 | An example of use of this object is to control UEFI HTTPS Boot. |
5357 | The tls-cipher-suites object exposes the ordered list of permitted | |
5358 | TLS cipher suites from the host side to the guest firmware, via | |
5359 | fw_cfg. The list is represented as an array of IANA_TLS_CIPHER | |
5360 | objects. The firmware uses the IANA_TLS_CIPHER array for configuring | |
5361 | guest-side TLS. | |
5362 | ||
5363 | In the following example, the priority at which the host-side policy | |
5364 | is retrieved is given by the ``priority`` property. | |
5365 | Given that QEMU uses GNUTLS, ``priority=@SYSTEM`` may be used to | |
5366 | refer to /etc/crypto-policies/back-ends/gnutls.config. | |
5367 | ||
5368 | .. parsed-literal:: | |
5369 | ||
353a06b4 LE |
5370 | # |qemu_system| \\ |
5371 | -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM \\ | |
69699f30 PMD |
5372 | -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0 |
5373 | ||
e2fcbf42 PM |
5374 | ``-object filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off][,position=head|tail|id=<id>][,insert=behind|before]`` |
5375 | Interval t can't be 0, this filter batches the packet delivery: | |
5376 | all packets arriving in a given interval on netdev netdevid are | |
5377 | delayed until the end of the interval. Interval is in | |
5378 | microseconds. ``status`` is optional that indicate whether the | |
5379 | netfilter is on (enabled) or off (disabled), the default status | |
5380 | for netfilter will be 'on'. | |
5381 | ||
5382 | queue all\|rx\|tx is an option that can be applied to any | |
5383 | netfilter. | |
5384 | ||
5385 | ``all``: the filter is attached both to the receive and the | |
5386 | transmit queue of the netdev (default). | |
5387 | ||
5388 | ``rx``: the filter is attached to the receive queue of the | |
5389 | netdev, where it will receive packets sent to the netdev. | |
5390 | ||
5391 | ``tx``: the filter is attached to the transmit queue of the | |
5392 | netdev, where it will receive packets sent by the netdev. | |
5393 | ||
5394 | position head\|tail\|id=<id> is an option to specify where the | |
5395 | filter should be inserted in the filter list. It can be applied | |
5396 | to any netfilter. | |
5397 | ||
5398 | ``head``: the filter is inserted at the head of the filter list, | |
5399 | before any existing filters. | |
5400 | ||
5401 | ``tail``: the filter is inserted at the tail of the filter list, | |
5402 | behind any existing filters (default). | |
5403 | ||
5404 | ``id=<id>``: the filter is inserted before or behind the filter | |
5405 | specified by <id>, see the insert option below. | |
5406 | ||
5407 | insert behind\|before is an option to specify where to insert | |
5408 | the new filter relative to the one specified with | |
5409 | position=id=<id>. It can be applied to any netfilter. | |
5410 | ||
5411 | ``before``: insert before the specified filter. | |
5412 | ||
5413 | ``behind``: insert behind the specified filter (default). | |
5414 | ||
5415 | ``-object filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]`` | |
5416 | filter-mirror on netdev netdevid,mirror net packet to | |
5417 | chardevchardevid, if it has the vnet\_hdr\_support flag, | |
5418 | filter-mirror will mirror packet with vnet\_hdr\_len. | |
5419 | ||
5420 | ``-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]`` | |
5421 | filter-redirector on netdev netdevid,redirect filter's net | |
5422 | packet to chardev chardevid,and redirect indev's packet to | |
5423 | filter.if it has the vnet\_hdr\_support flag, filter-redirector | |
5424 | will redirect packet with vnet\_hdr\_len. Create a | |
5425 | filter-redirector we need to differ outdev id from indev id, id | |
5426 | can not be the same. we can just use indev or outdev, but at | |
5427 | least one of indev or outdev need to be specified. | |
5428 | ||
5429 | ``-object filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]`` | |
5430 | Filter-rewriter is a part of COLO project.It will rewrite tcp | |
5431 | packet to secondary from primary to keep secondary tcp | |
5432 | connection,and rewrite tcp packet to primary from secondary make | |
5433 | tcp packet can be handled by client.if it has the | |
5434 | vnet\_hdr\_support flag, we can parse packet with vnet header. | |
5435 | ||
5436 | usage: colo secondary: -object | |
5437 | filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object | |
5438 | filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object | |
5439 | filter-rewriter,id=rew0,netdev=hn0,queue=all | |
5440 | ||
5441 | ``-object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len][,position=head|tail|id=<id>][,insert=behind|before]`` | |
5442 | Dump the network traffic on netdev dev to the file specified by | |
5443 | filename. At most len bytes (64k by default) per packet are | |
5444 | stored. The file format is libpcap, so it can be analyzed with | |
5445 | tools such as tcpdump or Wireshark. | |
5446 | ||
a2e5cb7a | 5447 | ``-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 |
5448 | Colo-compare gets packet from primary\_in chardevid and |
5449 | secondary\_in, then compare whether the payload of primary packet | |
5450 | and secondary packet are the same. If same, it will output | |
5451 | primary packet to out\_dev, else it will notify COLO-framework to do | |
5452 | checkpoint and send primary packet to out\_dev. In order to | |
5453 | improve efficiency, we need to put the task of comparison in | |
5454 | another iothread. If it has the vnet\_hdr\_support flag, | |
5455 | colo compare will send/recv packet with vnet\_hdr\_len. | |
5456 | The compare\_timeout=@var{ms} determines the maximum time of the | |
5457 | colo-compare hold the packet. The expired\_scan\_cycle=@var{ms} | |
5458 | is to set the period of scanning expired primary node network packets. | |
5459 | The max\_queue\_size=@var{size} is to set the max compare queue | |
5460 | size depend on user environment. | |
5461 | If user want to use Xen COLO, need to add the notify\_dev to | |
9cc43c94 | 5462 | notify Xen colo-frame to do checkpoint. |
e2fcbf42 | 5463 | |
2b28a7ef ZC |
5464 | COLO-compare must be used with the help of filter-mirror, |
5465 | filter-redirector and filter-rewriter. | |
e2fcbf42 PM |
5466 | |
5467 | :: | |
5468 | ||
5469 | KVM COLO | |
5470 | ||
5471 | primary: | |
5472 | -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown | |
5473 | -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 | |
bfdc1267 DB |
5474 | -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off |
5475 | -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off | |
5476 | -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off | |
e2fcbf42 | 5477 | -chardev socket,id=compare0-0,host=3.3.3.3,port=9001 |
bfdc1267 | 5478 | -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off |
e2fcbf42 PM |
5479 | -chardev socket,id=compare_out0,host=3.3.3.3,port=9005 |
5480 | -object iothread,id=iothread1 | |
5481 | -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 | |
5482 | -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out | |
5483 | -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 | |
5484 | -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 | |
5485 | ||
5486 | secondary: | |
5487 | -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown | |
5488 | -device e1000,netdev=hn0,mac=52:a4:00:12:78:66 | |
5489 | -chardev socket,id=red0,host=3.3.3.3,port=9003 | |
5490 | -chardev socket,id=red1,host=3.3.3.3,port=9004 | |
5491 | -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 | |
5492 | -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 | |
5493 | ||
5494 | ||
5495 | Xen COLO | |
5496 | ||
5497 | primary: | |
5498 | -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown | |
5499 | -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 | |
bfdc1267 DB |
5500 | -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off |
5501 | -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off | |
5502 | -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off | |
e2fcbf42 | 5503 | -chardev socket,id=compare0-0,host=3.3.3.3,port=9001 |
bfdc1267 | 5504 | -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off |
e2fcbf42 | 5505 | -chardev socket,id=compare_out0,host=3.3.3.3,port=9005 |
bfdc1267 | 5506 | -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server=on,wait=off |
e2fcbf42 PM |
5507 | -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 |
5508 | -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out | |
5509 | -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 | |
5510 | -object iothread,id=iothread1 | |
5511 | -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1 | |
5512 | ||
5513 | secondary: | |
5514 | -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown | |
5515 | -device e1000,netdev=hn0,mac=52:a4:00:12:78:66 | |
5516 | -chardev socket,id=red0,host=3.3.3.3,port=9003 | |
5517 | -chardev socket,id=red1,host=3.3.3.3,port=9004 | |
5518 | -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 | |
5519 | -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 | |
5520 | ||
5521 | If you want to know the detail of above command line, you can | |
5522 | read the colo-compare git log. | |
5523 | ||
5524 | ``-object cryptodev-backend-builtin,id=id[,queues=queues]`` | |
1e458f11 SW |
5525 | Creates a cryptodev backend which executes crypto operations from |
5526 | the QEMU cipher APIs. The id parameter is a unique ID that will | |
e2fcbf42 PM |
5527 | be used to reference this cryptodev backend from the |
5528 | ``virtio-crypto`` device. The queues parameter is optional, | |
5529 | which specify the queue number of cryptodev backend, the default | |
5530 | of queues is 1. | |
5531 | ||
09ce5f2d | 5532 | .. parsed-literal:: |
e2fcbf42 | 5533 | |
353a06b4 LE |
5534 | # |qemu_system| \\ |
5535 | [...] \\ | |
5536 | -object cryptodev-backend-builtin,id=cryptodev0 \\ | |
5537 | -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \\ | |
e2fcbf42 PM |
5538 | [...] |
5539 | ||
5540 | ``-object cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]`` | |
5541 | Creates a vhost-user cryptodev backend, backed by a chardev | |
5542 | chardevid. The id parameter is a unique ID that will be used to | |
5543 | reference this cryptodev backend from the ``virtio-crypto`` | |
5544 | device. The chardev should be a unix domain socket backed one. | |
5545 | The vhost-user uses a specifically defined protocol to pass | |
5546 | vhost ioctl replacement messages to an application on the other | |
5547 | end of the socket. The queues parameter is optional, which | |
5548 | specify the queue number of cryptodev backend for multiqueue | |
5549 | vhost-user, the default of queues is 1. | |
5550 | ||
09ce5f2d | 5551 | .. parsed-literal:: |
e2fcbf42 | 5552 | |
353a06b4 LE |
5553 | # |qemu_system| \\ |
5554 | [...] \\ | |
5555 | -chardev socket,id=chardev0,path=/path/to/socket \\ | |
5556 | -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \\ | |
5557 | -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \\ | |
e2fcbf42 PM |
5558 | [...] |
5559 | ||
5560 | ``-object secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]`` | |
09ce5f2d | 5561 | \ |
e2fcbf42 PM |
5562 | ``-object secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]`` |
5563 | Defines a secret to store a password, encryption key, or some | |
5564 | other sensitive data. The sensitive data can either be passed | |
5565 | directly via the data parameter, or indirectly via the file | |
5566 | parameter. Using the data parameter is insecure unless the | |
5567 | sensitive data is encrypted. | |
5568 | ||
5569 | The sensitive data can be provided in raw format (the default), | |
5570 | or base64. When encoded as JSON, the raw format only supports | |
5571 | valid UTF-8 characters, so base64 is recommended for sending | |
5572 | binary data. QEMU will convert from which ever format is | |
5573 | provided to the format it needs internally. eg, an RBD password | |
5574 | can be provided in raw format, even though it will be base64 | |
5575 | encoded when passed onto the RBD sever. | |
5576 | ||
5577 | For added protection, it is possible to encrypt the data | |
5578 | associated with a secret using the AES-256-CBC cipher. Use of | |
5579 | encryption is indicated by providing the keyid and iv | |
5580 | parameters. The keyid parameter provides the ID of a previously | |
5581 | defined secret that contains the AES-256 decryption key. This | |
5582 | key should be 32-bytes long and be base64 encoded. The iv | |
5583 | parameter provides the random initialization vector used for | |
5584 | encryption of this particular secret and should be a base64 | |
5585 | encrypted string of the 16-byte IV. | |
5586 | ||
5587 | The simplest (insecure) usage is to provide the secret inline | |
5588 | ||
09ce5f2d | 5589 | .. parsed-literal:: |
e2fcbf42 PM |
5590 | |
5591 | # |qemu_system| -object secret,id=sec0,data=letmein,format=raw | |
5592 | ||
5593 | The simplest secure usage is to provide the secret via a file | |
5594 | ||
5595 | # printf "letmein" > mypasswd.txt # QEMU\_SYSTEM\_MACRO -object | |
5596 | secret,id=sec0,file=mypasswd.txt,format=raw | |
5597 | ||
5598 | For greater security, AES-256-CBC should be used. To illustrate | |
5599 | usage, consider the openssl command line tool which can encrypt | |
5600 | the data. Note that when encrypting, the plaintext must be | |
5601 | padded to the cipher block size (32 bytes) using the standard | |
5602 | PKCS#5/6 compatible padding algorithm. | |
5603 | ||
5604 | First a master key needs to be created in base64 encoding: | |
5605 | ||
5606 | :: | |
5607 | ||
5608 | # openssl rand -base64 32 > key.b64 | |
5609 | # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') | |
5610 | ||
5611 | Each secret to be encrypted needs to have a random | |
5612 | initialization vector generated. These do not need to be kept | |
5613 | secret | |
5614 | ||
5615 | :: | |
5616 | ||
5617 | # openssl rand -base64 16 > iv.b64 | |
5618 | # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') | |
5619 | ||
5620 | The secret to be defined can now be encrypted, in this case | |
5621 | we're telling openssl to base64 encode the result, but it could | |
5622 | be left as raw bytes if desired. | |
5623 | ||
5624 | :: | |
5625 | ||
5626 | # SECRET=$(printf "letmein" | | |
5627 | openssl enc -aes-256-cbc -a -K $KEY -iv $IV) | |
5628 | ||
5629 | When launching QEMU, create a master secret pointing to | |
5630 | ``key.b64`` and specify that to be used to decrypt the user | |
5631 | password. Pass the contents of ``iv.b64`` to the second secret | |
5632 | ||
09ce5f2d | 5633 | .. parsed-literal:: |
e2fcbf42 | 5634 | |
353a06b4 LE |
5635 | # |qemu_system| \\ |
5636 | -object secret,id=secmaster0,format=base64,file=key.b64 \\ | |
5637 | -object secret,id=sec0,keyid=secmaster0,format=base64,\\ | |
e2fcbf42 PM |
5638 | data=$SECRET,iv=$(<iv.b64) |
5639 | ||
55cdf566 | 5640 | ``-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 |
5641 | Create a Secure Encrypted Virtualization (SEV) guest object, |
5642 | which can be used to provide the guest memory encryption support | |
5643 | on AMD processors. | |
5644 | ||
5645 | When memory encryption is enabled, one of the physical address | |
5646 | bit (aka the C-bit) is utilized to mark if a memory page is | |
5647 | protected. The ``cbitpos`` is used to provide the C-bit | |
5648 | position. The C-bit position is Host family dependent hence user | |
5649 | must provide this value. On EPYC, the value should be 47. | |
5650 | ||
5651 | When memory encryption is enabled, we loose certain bits in | |
5652 | physical address space. The ``reduced-phys-bits`` is used to | |
5653 | provide the number of bits we loose in physical address space. | |
5654 | Similar to C-bit, the value is Host family dependent. On EPYC, | |
326e3015 | 5655 | a guest will lose a maximum of 1 bit, so the value should be 1. |
e2fcbf42 PM |
5656 | |
5657 | The ``sev-device`` provides the device file to use for | |
5658 | communicating with the SEV firmware running inside AMD Secure | |
5659 | Processor. The default device is '/dev/sev'. If hardware | |
5660 | supports memory encryption then /dev/sev devices are created by | |
5661 | CCP driver. | |
5662 | ||
5663 | The ``policy`` provides the guest policy to be enforced by the | |
5664 | SEV firmware and restrict what configuration and operational | |
5665 | commands can be performed on this guest by the hypervisor. The | |
5666 | policy should be provided by the guest owner and is bound to the | |
5667 | guest and cannot be changed throughout the lifetime of the | |
5668 | guest. The default is 0. | |
5669 | ||
5670 | If guest ``policy`` allows sharing the key with another SEV | |
5671 | guest then ``handle`` can be use to provide handle of the guest | |
5672 | from which to share the key. | |
5673 | ||
5674 | The ``dh-cert-file`` and ``session-file`` provides the guest | |
5675 | owner's Public Diffie-Hillman key defined in SEV spec. The PDH | |
5676 | and session parameters are used for establishing a cryptographic | |
5677 | session with the guest owner to negotiate keys used for | |
5678 | attestation. The file must be encoded in base64. | |
5679 | ||
55cdf566 DM |
5680 | The ``kernel-hashes`` adds the hashes of given kernel/initrd/ |
5681 | cmdline to a designated guest firmware page for measured Linux | |
5682 | boot with -kernel. The default is off. (Since 6.2) | |
5683 | ||
e2fcbf42 PM |
5684 | e.g to launch a SEV guest |
5685 | ||
09ce5f2d | 5686 | .. parsed-literal:: |
e2fcbf42 | 5687 | |
353a06b4 LE |
5688 | # |qemu_system_x86| \\ |
5689 | ...... \\ | |
326e3015 | 5690 | -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \\ |
353a06b4 | 5691 | -machine ...,memory-encryption=sev0 \\ |
e2fcbf42 PM |
5692 | ..... |
5693 | ||
5694 | ``-object authz-simple,id=id,identity=string`` | |
5695 | Create an authorization object that will control access to | |
5696 | network services. | |
5697 | ||
5698 | The ``identity`` parameter is identifies the user and its format | |
5699 | depends on the network service that authorization object is | |
5700 | associated with. For authorizing based on TLS x509 certificates, | |
5701 | the identity must be the x509 distinguished name. Note that care | |
5702 | must be taken to escape any commas in the distinguished name. | |
5703 | ||
5704 | An example authorization object to validate a x509 distinguished | |
5705 | name would look like: | |
5706 | ||
09ce5f2d | 5707 | .. parsed-literal:: |
e2fcbf42 | 5708 | |
353a06b4 LE |
5709 | # |qemu_system| \\ |
5710 | ... \\ | |
5711 | -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \\ | |
e2fcbf42 PM |
5712 | ... |
5713 | ||
5714 | Note the use of quotes due to the x509 distinguished name | |
5715 | containing whitespace, and escaping of ','. | |
5716 | ||
4d7beeab | 5717 | ``-object authz-listfile,id=id,filename=path,refresh=on|off`` |
e2fcbf42 PM |
5718 | Create an authorization object that will control access to |
5719 | network services. | |
5720 | ||
5721 | The ``filename`` parameter is the fully qualified path to a file | |
5722 | containing the access control list rules in JSON format. | |
5723 | ||
5724 | An example set of rules that match against SASL usernames might | |
5725 | look like: | |
5726 | ||
5727 | :: | |
5728 | ||
5729 | { | |
5730 | "rules": [ | |
5731 | { "match": "fred", "policy": "allow", "format": "exact" }, | |
5732 | { "match": "bob", "policy": "allow", "format": "exact" }, | |
5733 | { "match": "danb", "policy": "deny", "format": "glob" }, | |
5734 | { "match": "dan*", "policy": "allow", "format": "exact" }, | |
5735 | ], | |
5736 | "policy": "deny" | |
5737 | } | |
5738 | ||
5739 | When checking access the object will iterate over all the rules | |
5740 | and the first rule to match will have its ``policy`` value | |
5741 | returned as the result. If no rules match, then the default | |
5742 | ``policy`` value is returned. | |
5743 | ||
5744 | The rules can either be an exact string match, or they can use | |
5745 | the simple UNIX glob pattern matching to allow wildcards to be | |
5746 | used. | |
5747 | ||
5748 | If ``refresh`` is set to true the file will be monitored and | |
5749 | automatically reloaded whenever its content changes. | |
5750 | ||
5751 | As with the ``authz-simple`` object, the format of the identity | |
5752 | strings being matched depends on the network service, but is | |
5753 | usually a TLS x509 distinguished name, or a SASL username. | |
5754 | ||
5755 | An example authorization object to validate a SASL username | |
5756 | would look like: | |
5757 | ||
09ce5f2d | 5758 | .. parsed-literal:: |
e2fcbf42 | 5759 | |
353a06b4 LE |
5760 | # |qemu_system| \\ |
5761 | ... \\ | |
4d7beeab | 5762 | -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=on \\ |
e2fcbf42 PM |
5763 | ... |
5764 | ||
5765 | ``-object authz-pam,id=id,service=string`` | |
5766 | Create an authorization object that will control access to | |
5767 | network services. | |
5768 | ||
5769 | The ``service`` parameter provides the name of a PAM service to | |
5770 | use for authorization. It requires that a file | |
5771 | ``/etc/pam.d/service`` exist to provide the configuration for | |
5772 | the ``account`` subsystem. | |
5773 | ||
5774 | An example authorization object to validate a TLS x509 | |
5775 | distinguished name would look like: | |
5776 | ||
09ce5f2d | 5777 | .. parsed-literal:: |
e2fcbf42 | 5778 | |
353a06b4 LE |
5779 | # |qemu_system| \\ |
5780 | ... \\ | |
5781 | -object authz-pam,id=auth0,service=qemu-vnc \\ | |
e2fcbf42 PM |
5782 | ... |
5783 | ||
5784 | There would then be a corresponding config file for PAM at | |
5785 | ``/etc/pam.d/qemu-vnc`` that contains: | |
5786 | ||
5787 | :: | |
5788 | ||
5789 | account requisite pam_listfile.so item=user sense=allow \ | |
5790 | file=/etc/qemu/vnc.allow | |
5791 | ||
5792 | Finally the ``/etc/qemu/vnc.allow`` file would contain the list | |
1e458f11 | 5793 | of x509 distinguished names that are permitted access |
e2fcbf42 PM |
5794 | |
5795 | :: | |
5796 | ||
5797 | CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB | |
5798 | ||
1793ad02 | 5799 | ``-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 |
5800 | Creates a dedicated event loop thread that devices can be |
5801 | assigned to. This is known as an IOThread. By default device | |
5802 | emulation happens in vCPU threads or the main event loop thread. | |
5803 | This can become a scalability bottleneck. IOThreads allow device | |
5804 | emulation and I/O to run on other host CPUs. | |
5805 | ||
5806 | The ``id`` parameter is a unique ID that will be used to | |
5807 | reference this IOThread from ``-device ...,iothread=id``. | |
5808 | Multiple devices can be assigned to an IOThread. Note that not | |
5809 | all devices support an ``iothread`` parameter. | |
5810 | ||
5811 | The ``query-iothreads`` QMP command lists IOThreads and reports | |
5812 | their thread IDs so that the user can configure host CPU | |
5813 | pinning/affinity. | |
5814 | ||
5815 | IOThreads use an adaptive polling algorithm to reduce event loop | |
5816 | latency. Instead of entering a blocking system call to monitor | |
5817 | file descriptors and then pay the cost of being woken up when an | |
5818 | event occurs, the polling algorithm spins waiting for events for | |
5819 | a short time. The algorithm's default parameters are suitable | |
5820 | for many cases but can be adjusted based on knowledge of the | |
5821 | workload and/or host device latency. | |
5822 | ||
5823 | The ``poll-max-ns`` parameter is the maximum number of | |
5824 | nanoseconds to busy wait for events. Polling can be disabled by | |
5825 | setting this value to 0. | |
5826 | ||
5827 | The ``poll-grow`` parameter is the multiplier used to increase | |
5828 | the polling time when the algorithm detects it is missing events | |
5829 | due to not polling long enough. | |
5830 | ||
5831 | The ``poll-shrink`` parameter is the divisor used to decrease | |
5832 | the polling time when the algorithm detects it is spending too | |
5833 | long polling without encountering events. | |
5834 | ||
1793ad02 SG |
5835 | The ``aio-max-batch`` parameter is the maximum number of requests |
5836 | in a batch for the AIO engine, 0 means that the engine will use | |
5837 | its default. | |
5838 | ||
5839 | The IOThread parameters can be modified at run-time using the | |
e2fcbf42 PM |
5840 | ``qom-set`` command (where ``iothread1`` is the IOThread's |
5841 | ``id``): | |
5842 | ||
5843 | :: | |
5844 | ||
5845 | (qemu) qom-set /objects/iothread1 poll-max-ns 100000 | |
5846 | ERST | |
b9174d4f DB |
5847 | |
5848 | ||
3dbf2c7f | 5849 | HXCOMM This is the last statement. Insert new options before this line! |
fd5fc4b1 PB |
5850 | |
5851 | #undef DEF | |
5852 | #undef DEFHEADING | |
5853 | #undef ARCHHEADING |