hw/pci-host/designware: Remove unuseful FALLTHROUGH comment
[qemu/ar7.git] / qemu-options.hx
blob709162c159ad62b2a960d7bc30859963105930eb
1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
6 HXCOMM architectures.
7 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
9 DEFHEADING(Standard options:)
10 STEXI
11 @table @option
12 ETEXI
14 DEF("help", 0, QEMU_OPTION_h,
15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL)
16 STEXI
17 @item -h
18 @findex -h
19 Display help and exit
20 ETEXI
22 DEF("version", 0, QEMU_OPTION_version,
23 "-version display version information and exit\n", QEMU_ARCH_ALL)
24 STEXI
25 @item -version
26 @findex -version
27 Display version information and exit
28 ETEXI
30 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31 "-machine [type=]name[,prop[=value][,...]]\n"
32 " selects emulated machine ('-machine help' for list)\n"
33 " property accel=accel1[:accel2[:...]] selects accelerator\n"
34 " supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n"
35 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
36 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
37 " mem-merge=on|off controls memory merge support (default: on)\n"
38 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
39 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
40 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
41 " nvdimm=on|off controls NVDIMM support (default=off)\n"
42 " enforce-config-section=on|off enforce configuration section migration (default=off)\n"
43 " memory-encryption=@var{} memory encryption object to use (default=none)\n"
44 " hmat=on|off controls ACPI HMAT support (default=off)\n",
45 QEMU_ARCH_ALL)
46 STEXI
47 @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
48 @findex -machine
49 Select the emulated machine by @var{name}. Use @code{-machine help} to list
50 available machines.
52 For architectures which aim to support live migration compatibility
53 across releases, each release will introduce a new versioned machine
54 type. For example, the 2.8.0 release introduced machine types
55 ``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
57 To allow live migration of guests from QEMU version 2.8.0, to QEMU
58 version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
59 and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
60 to skip multiple intermediate releases when upgrading, new releases
61 of QEMU will support machine types from many previous versions.
63 Supported machine properties are:
64 @table @option
65 @item accel=@var{accels1}[:@var{accels2}[:...]]
66 This is used to enable an accelerator. Depending on the target architecture,
67 kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
68 more than one accelerator specified, the next one is used if the previous one
69 fails to initialize.
70 @item vmport=on|off|auto
71 Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
72 value based on accel. For accel=xen the default is off otherwise the default
73 is on.
74 @item dump-guest-core=on|off
75 Include guest memory in a core dump. The default is on.
76 @item mem-merge=on|off
77 Enables or disables memory merge support. This feature, when supported by
78 the host, de-duplicates identical memory pages among VMs instances
79 (enabled by default).
80 @item aes-key-wrap=on|off
81 Enables or disables AES key wrapping support on s390-ccw hosts. This feature
82 controls whether AES wrapping keys will be created to allow
83 execution of AES cryptographic functions. The default is on.
84 @item dea-key-wrap=on|off
85 Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
86 controls whether DEA wrapping keys will be created to allow
87 execution of DEA cryptographic functions. The default is on.
88 @item nvdimm=on|off
89 Enables or disables NVDIMM support. The default is off.
90 @item enforce-config-section=on|off
91 If @option{enforce-config-section} is set to @var{on}, force migration
92 code to send configuration section even if the machine-type sets the
93 @option{migration.send-configuration} property to @var{off}.
94 NOTE: this parameter is deprecated. Please use @option{-global}
95 @option{migration.send-configuration}=@var{on|off} instead.
96 @item memory-encryption=@var{}
97 Memory encryption object to use. The default is none.
98 @item hmat=on|off
99 Enables or disables ACPI Heterogeneous Memory Attribute Table (HMAT) support.
100 The default is off.
101 @end table
102 ETEXI
104 HXCOMM Deprecated by -machine
105 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
107 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
108 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
109 STEXI
110 @item -cpu @var{model}
111 @findex -cpu
112 Select CPU model (@code{-cpu help} for list and additional feature selection)
113 ETEXI
115 DEF("accel", HAS_ARG, QEMU_OPTION_accel,
116 "-accel [accel=]accelerator[,prop[=value][,...]]\n"
117 " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
118 " igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
119 " kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
120 " kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
121 " tb-size=n (TCG translation block cache size)\n"
122 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
123 STEXI
124 @item -accel @var{name}[,prop=@var{value}[,...]]
125 @findex -accel
126 This is used to enable an accelerator. Depending on the target architecture,
127 kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
128 more than one accelerator specified, the next one is used if the previous one
129 fails to initialize.
130 @table @option
131 @item igd-passthru=on|off
132 When Xen is in use, this option controls whether Intel integrated graphics
133 devices can be passed through to the guest (default=off)
134 @item kernel-irqchip=on|off|split
135 Controls KVM in-kernel irqchip support. The default is full acceleration of the
136 interrupt controllers. On x86, split irqchip reduces the kernel attack
137 surface, at a performance cost for non-MSI interrupts. Disabling the in-kernel
138 irqchip completely is not recommended except for debugging purposes.
139 @item kvm-shadow-mem=size
140 Defines the size of the KVM shadow MMU.
141 @item tb-size=@var{n}
142 Controls the size (in MiB) of the TCG translation block cache.
143 @item thread=single|multi
144 Controls number of TCG threads. When the TCG is multi-threaded there will be one
145 thread per vCPU therefor taking advantage of additional host cores. The default
146 is to enable multi-threading where both the back-end and front-ends support it and
147 no incompatible TCG features have been enabled (e.g. icount/replay).
148 @end table
149 ETEXI
151 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
152 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
153 " set the number of CPUs to 'n' [default=1]\n"
154 " maxcpus= maximum number of total cpus, including\n"
155 " offline CPUs for hotplug, etc\n"
156 " cores= number of CPU cores on one socket (for PC, it's on one die)\n"
157 " threads= number of threads on one CPU core\n"
158 " dies= number of CPU dies on one socket (for PC only)\n"
159 " sockets= number of discrete sockets in the system\n",
160 QEMU_ARCH_ALL)
161 STEXI
162 @item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
163 @findex -smp
164 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
165 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
166 to 4.
167 For the PC target, the number of @var{cores} per die, the number of @var{threads}
168 per cores, the number of @var{dies} per packages and the total number of
169 @var{sockets} can be specified. Missing values will be computed.
170 If any on the three values is given, the total number of CPUs @var{n} can be omitted.
171 @var{maxcpus} specifies the maximum number of hotpluggable CPUs.
172 ETEXI
174 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
175 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
176 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
177 "-numa dist,src=source,dst=destination,val=distance\n"
178 "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
179 "-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"
180 "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
181 QEMU_ARCH_ALL)
182 STEXI
183 @item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}]
184 @itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}]
185 @itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
186 @itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
187 @itemx -numa hmat-lb,initiator=@var{node},target=@var{node},hierarchy=@var{hierarchy},data-type=@var{tpye}[,latency=@var{lat}][,bandwidth=@var{bw}]
188 @itemx -numa hmat-cache,node-id=@var{node},size=@var{size},level=@var{level}[,associativity=@var{str}][,policy=@var{str}][,line=@var{size}]
189 @findex -numa
190 Define a NUMA node and assign RAM and VCPUs to it.
191 Set the NUMA distance from a source node to a destination node.
192 Set the ACPI Heterogeneous Memory Attributes for the given nodes.
194 Legacy VCPU assignment uses @samp{cpus} option where
195 @var{firstcpu} and @var{lastcpu} are CPU indexes. Each
196 @samp{cpus} option represent a contiguous range of CPU indexes
197 (or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
198 set of VCPUs can be represented by providing multiple @samp{cpus}
199 options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
200 split between them.
202 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
203 a NUMA node:
204 @example
205 -numa node,cpus=0-2,cpus=5
206 @end example
208 @samp{cpu} option is a new alternative to @samp{cpus} option
209 which uses @samp{socket-id|core-id|thread-id} properties to assign
210 CPU objects to a @var{node} using topology layout properties of CPU.
211 The set of properties is machine specific, and depends on used
212 machine type/@samp{smp} options. It could be queried with
213 @samp{hotpluggable-cpus} monitor command.
214 @samp{node-id} property specifies @var{node} to which CPU object
215 will be assigned, it's required for @var{node} to be declared
216 with @samp{node} option before it's used with @samp{cpu} option.
218 For example:
219 @example
220 -M pc \
221 -smp 1,sockets=2,maxcpus=2 \
222 -numa node,nodeid=0 -numa node,nodeid=1 \
223 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
224 @end example
226 @samp{mem} assigns a given RAM amount to a node. @samp{memdev}
227 assigns RAM from a given memory backend device to a node. If
228 @samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
229 split equally between them.
231 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
232 if one node uses @samp{memdev}, all of them have to use it.
234 @samp{initiator} is an additional option that points to an @var{initiator}
235 NUMA node that has best performance (the lowest latency or largest bandwidth)
236 to this NUMA @var{node}. Note that this option can be set only when
237 the machine property 'hmat' is set to 'on'.
239 Following example creates a machine with 2 NUMA nodes, node 0 has CPU.
240 node 1 has only memory, and its initiator is node 0. Note that because
241 node 0 has CPU, by default the initiator of node 0 is itself and must be
242 itself.
243 @example
244 -machine hmat=on \
245 -m 2G,slots=2,maxmem=4G \
246 -object memory-backend-ram,size=1G,id=m0 \
247 -object memory-backend-ram,size=1G,id=m1 \
248 -numa node,nodeid=0,memdev=m0 \
249 -numa node,nodeid=1,memdev=m1,initiator=0 \
250 -smp 2,sockets=2,maxcpus=2 \
251 -numa cpu,node-id=0,socket-id=0 \
252 -numa cpu,node-id=0,socket-id=1
253 @end example
255 @var{source} and @var{destination} are NUMA node IDs.
256 @var{distance} is the NUMA distance from @var{source} to @var{destination}.
257 The distance from a node to itself is always 10. If any pair of nodes is
258 given a distance, then all pairs must be given distances. Although, when
259 distances are only given in one direction for each pair of nodes, then
260 the distances in the opposite directions are assumed to be the same. If,
261 however, an asymmetrical pair of distances is given for even one node
262 pair, then all node pairs must be provided distance values for both
263 directions, even when they are symmetrical. When a node is unreachable
264 from another node, set the pair's distance to 255.
266 Note that the -@option{numa} option doesn't allocate any of the
267 specified resources, it just assigns existing resources to NUMA
268 nodes. This means that one still has to use the @option{-m},
269 @option{-smp} options to allocate RAM and VCPUs respectively.
271 Use @samp{hmat-lb} to set System Locality Latency and Bandwidth Information
272 between initiator and target NUMA nodes in ACPI Heterogeneous Attribute Memory Table (HMAT).
273 Initiator NUMA node can create memory requests, usually it has one or more processors.
274 Target NUMA node contains addressable memory.
276 In @samp{hmat-lb} option, @var{node} are NUMA node IDs. @var{hierarchy} is the memory
277 hierarchy of the target NUMA node: if @var{hierarchy} is 'memory', the structure
278 represents the memory performance; if @var{hierarchy} is 'first-level|second-level|third-level',
279 this structure represents aggregated performance of memory side caches for each domain.
280 @var{type} of 'data-type' is type of data represented by this structure instance:
281 if 'hierarchy' is 'memory', 'data-type' is 'access|read|write' latency or 'access|read|write'
282 bandwidth of the target memory; if 'hierarchy' is 'first-level|second-level|third-level',
283 'data-type' is 'access|read|write' hit latency or 'access|read|write' hit bandwidth of the
284 target memory side cache.
286 @var{lat} is latency value in nanoseconds. @var{bw} is bandwidth value,
287 the possible value and units are NUM[M|G|T], mean that the bandwidth value are
288 NUM byte per second (or MB/s, GB/s or TB/s depending on used suffix).
289 Note that if latency or bandwidth value is 0, means the corresponding latency or
290 bandwidth information is not provided.
292 In @samp{hmat-cache} option, @var{node-id} is the NUMA-id of the memory belongs.
293 @var{size} is the size of memory side cache in bytes. @var{level} is the cache
294 level described in this structure, note that the cache level 0 should not be used
295 with @samp{hmat-cache} option. @var{associativity} is the cache associativity,
296 the possible value is 'none/direct(direct-mapped)/complex(complex cache indexing)'.
297 @var{policy} is the write policy. @var{line} is the cache Line size in bytes.
299 For example, the following options describe 2 NUMA nodes. Node 0 has 2 cpus and
300 a ram, node 1 has only a ram. The processors in node 0 access memory in node
301 0 with access-latency 5 nanoseconds, access-bandwidth is 200 MB/s;
302 The processors in NUMA node 0 access memory in NUMA node 1 with access-latency 10
303 nanoseconds, access-bandwidth is 100 MB/s.
304 And for memory side cache information, NUMA node 0 and 1 both have 1 level memory
305 cache, size is 10KB, policy is write-back, the cache Line size is 8 bytes:
306 @example
307 -machine hmat=on \
308 -m 2G \
309 -object memory-backend-ram,size=1G,id=m0 \
310 -object memory-backend-ram,size=1G,id=m1 \
311 -smp 2 \
312 -numa node,nodeid=0,memdev=m0 \
313 -numa node,nodeid=1,memdev=m1,initiator=0 \
314 -numa cpu,node-id=0,socket-id=0 \
315 -numa cpu,node-id=0,socket-id=1 \
316 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
317 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
318 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
319 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
320 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
321 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
322 @end example
324 ETEXI
326 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
327 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
328 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
329 STEXI
330 @item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
331 @findex -add-fd
333 Add a file descriptor to an fd set. Valid options are:
335 @table @option
336 @item fd=@var{fd}
337 This option defines the file descriptor of which a duplicate is added to fd set.
338 The file descriptor cannot be stdin, stdout, or stderr.
339 @item set=@var{set}
340 This option defines the ID of the fd set to add the file descriptor to.
341 @item opaque=@var{opaque}
342 This option defines a free-form string that can be used to describe @var{fd}.
343 @end table
345 You can open an image using pre-opened file descriptors from an fd set:
346 @example
347 @value{qemu_system} \
348 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
349 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
350 -drive file=/dev/fdset/2,index=0,media=disk
351 @end example
352 ETEXI
354 DEF("set", HAS_ARG, QEMU_OPTION_set,
355 "-set group.id.arg=value\n"
356 " set <arg> parameter for item <id> of type <group>\n"
357 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
358 STEXI
359 @item -set @var{group}.@var{id}.@var{arg}=@var{value}
360 @findex -set
361 Set parameter @var{arg} for item @var{id} of type @var{group}
362 ETEXI
364 DEF("global", HAS_ARG, QEMU_OPTION_global,
365 "-global driver.property=value\n"
366 "-global driver=driver,property=property,value=value\n"
367 " set a global default for a driver property\n",
368 QEMU_ARCH_ALL)
369 STEXI
370 @item -global @var{driver}.@var{prop}=@var{value}
371 @itemx -global driver=@var{driver},property=@var{property},value=@var{value}
372 @findex -global
373 Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
375 @example
376 @value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img
377 @end example
379 In particular, you can use this to set driver properties for devices which are
380 created automatically by the machine model. To create a device which is not
381 created automatically and set properties on it, use -@option{device}.
383 -global @var{driver}.@var{prop}=@var{value} is shorthand for -global
384 driver=@var{driver},property=@var{prop},value=@var{value}. The
385 longhand syntax works even when @var{driver} contains a dot.
386 ETEXI
388 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
389 "-boot [order=drives][,once=drives][,menu=on|off]\n"
390 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
391 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
392 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
393 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
394 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
395 QEMU_ARCH_ALL)
396 STEXI
397 @item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}][,strict=on|off]
398 @findex -boot
399 Specify boot order @var{drives} as a string of drive letters. Valid
400 drive letters depend on the target architecture. The x86 PC uses: a, b
401 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
402 from network adapter 1-4), hard disk boot is the default. To apply a
403 particular boot order only on the first startup, specify it via
404 @option{once}. Note that the @option{order} or @option{once} parameter
405 should not be used together with the @option{bootindex} property of
406 devices, since the firmware implementations normally do not support both
407 at the same time.
409 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
410 as firmware/BIOS supports them. The default is non-interactive boot.
412 A splash picture could be passed to bios, enabling user to show it as logo,
413 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
414 supports them. Currently Seabios for X86 system support it.
415 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
416 format(true color). The resolution should be supported by the SVGA mode, so
417 the recommended is 320x240, 640x480, 800x640.
419 A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
420 when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
421 reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
422 system support it.
424 Do strict boot via @option{strict=on} as far as firmware/BIOS
425 supports it. This only effects when boot priority is changed by
426 bootindex options. The default is non-strict boot.
428 @example
429 # try to boot from network first, then from hard disk
430 @value{qemu_system_x86} -boot order=nc
431 # boot from CD-ROM first, switch back to default order after reboot
432 @value{qemu_system_x86} -boot once=d
433 # boot with a splash picture for 5 seconds.
434 @value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000
435 @end example
437 Note: The legacy format '-boot @var{drives}' is still supported but its
438 use is discouraged as it may be removed from future versions.
439 ETEXI
441 DEF("m", HAS_ARG, QEMU_OPTION_m,
442 "-m [size=]megs[,slots=n,maxmem=size]\n"
443 " configure guest RAM\n"
444 " size: initial amount of guest memory\n"
445 " slots: number of hotplug slots (default: none)\n"
446 " maxmem: maximum amount of guest memory (default: none)\n"
447 "NOTE: Some architectures might enforce a specific granularity\n",
448 QEMU_ARCH_ALL)
449 STEXI
450 @item -m [size=]@var{megs}[,slots=n,maxmem=size]
451 @findex -m
452 Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
453 Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
454 megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
455 could be used to set amount of hotpluggable memory slots and maximum amount of
456 memory. Note that @var{maxmem} must be aligned to the page size.
458 For example, the following command-line sets the guest startup RAM size to
459 1GB, creates 3 slots to hotplug additional memory and sets the maximum
460 memory the guest can reach to 4GB:
462 @example
463 @value{qemu_system} -m 1G,slots=3,maxmem=4G
464 @end example
466 If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
467 be enabled and the guest startup RAM will never increase.
468 ETEXI
470 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
471 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
472 STEXI
473 @item -mem-path @var{path}
474 @findex -mem-path
475 Allocate guest RAM from a temporarily created file in @var{path}.
476 ETEXI
478 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
479 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
480 QEMU_ARCH_ALL)
481 STEXI
482 @item -mem-prealloc
483 @findex -mem-prealloc
484 Preallocate memory when using -mem-path.
485 ETEXI
487 DEF("k", HAS_ARG, QEMU_OPTION_k,
488 "-k language use keyboard layout (for example 'fr' for French)\n",
489 QEMU_ARCH_ALL)
490 STEXI
491 @item -k @var{language}
492 @findex -k
493 Use keyboard layout @var{language} (for example @code{fr} for
494 French). This option is only needed where it is not easy to get raw PC
495 keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
496 display). You don't normally need to use it on PC/Linux or PC/Windows
497 hosts.
499 The available layouts are:
500 @example
501 ar de-ch es fo fr-ca hu ja mk no pt-br sv
502 da en-gb et fr fr-ch is lt nl pl ru th
503 de en-us fi fr-be hr it lv nl-be pt sl tr
504 @end example
506 The default is @code{en-us}.
507 ETEXI
510 HXCOMM Deprecated by -audiodev
511 DEF("audio-help", 0, QEMU_OPTION_audio_help,
512 "-audio-help show -audiodev equivalent of the currently specified audio settings\n",
513 QEMU_ARCH_ALL)
514 STEXI
515 @item -audio-help
516 @findex -audio-help
517 Will show the -audiodev equivalent of the currently specified
518 (deprecated) environment variables.
519 ETEXI
521 DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
522 "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
523 " specifies the audio backend to use\n"
524 " id= identifier of the backend\n"
525 " timer-period= timer period in microseconds\n"
526 " in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
527 " in|out.fixed-settings= use fixed settings for host audio\n"
528 " in|out.frequency= frequency to use with fixed settings\n"
529 " in|out.channels= number of channels to use with fixed settings\n"
530 " in|out.format= sample format to use with fixed settings\n"
531 " valid values: s8, s16, s32, u8, u16, u32\n"
532 " in|out.voices= number of voices to use\n"
533 " in|out.buffer-length= length of buffer in microseconds\n"
534 "-audiodev none,id=id,[,prop[=value][,...]]\n"
535 " dummy driver that discards all output\n"
536 #ifdef CONFIG_AUDIO_ALSA
537 "-audiodev alsa,id=id[,prop[=value][,...]]\n"
538 " in|out.dev= name of the audio device to use\n"
539 " in|out.period-length= length of period in microseconds\n"
540 " in|out.try-poll= attempt to use poll mode\n"
541 " threshold= threshold (in microseconds) when playback starts\n"
542 #endif
543 #ifdef CONFIG_AUDIO_COREAUDIO
544 "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
545 " in|out.buffer-count= number of buffers\n"
546 #endif
547 #ifdef CONFIG_AUDIO_DSOUND
548 "-audiodev dsound,id=id[,prop[=value][,...]]\n"
549 " latency= add extra latency to playback in microseconds\n"
550 #endif
551 #ifdef CONFIG_AUDIO_OSS
552 "-audiodev oss,id=id[,prop[=value][,...]]\n"
553 " in|out.dev= path of the audio device to use\n"
554 " in|out.buffer-count= number of buffers\n"
555 " in|out.try-poll= attempt to use poll mode\n"
556 " try-mmap= try using memory mapped access\n"
557 " exclusive= open device in exclusive mode\n"
558 " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
559 #endif
560 #ifdef CONFIG_AUDIO_PA
561 "-audiodev pa,id=id[,prop[=value][,...]]\n"
562 " server= PulseAudio server address\n"
563 " in|out.name= source/sink device name\n"
564 " in|out.latency= desired latency in microseconds\n"
565 #endif
566 #ifdef CONFIG_AUDIO_SDL
567 "-audiodev sdl,id=id[,prop[=value][,...]]\n"
568 #endif
569 #ifdef CONFIG_SPICE
570 "-audiodev spice,id=id[,prop[=value][,...]]\n"
571 #endif
572 "-audiodev wav,id=id[,prop[=value][,...]]\n"
573 " path= path of wav file to record\n",
574 QEMU_ARCH_ALL)
575 STEXI
576 @item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]]
577 @findex -audiodev
578 Adds a new audio backend @var{driver} identified by @var{id}. There are
579 global and driver specific properties. Some values can be set
580 differently for input and output, they're marked with @code{in|out.}.
581 You can set the input's property with @code{in.@var{prop}} and the
582 output's property with @code{out.@var{prop}}. For example:
583 @example
584 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
585 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
586 @end example
588 NOTE: parameter validation is known to be incomplete, in many cases
589 specifying an invalid option causes QEMU to print an error message and
590 continue emulation without sound.
592 Valid global options are:
594 @table @option
595 @item id=@var{identifier}
596 Identifies the audio backend.
598 @item timer-period=@var{period}
599 Sets the timer @var{period} used by the audio subsystem in microseconds.
600 Default is 10000 (10 ms).
602 @item in|out.mixing-engine=on|off
603 Use QEMU's mixing engine to mix all streams inside QEMU and convert
604 audio formats when not supported by the backend. When off,
605 @var{fixed-settings} must be off too. Note that disabling this option
606 means that the selected backend must support multiple streams and the
607 audio formats used by the virtual cards, otherwise you'll get no sound.
608 It's not recommended to disable this option unless you want to use 5.1
609 or 7.1 audio, as mixing engine only supports mono and stereo audio.
610 Default is on.
612 @item in|out.fixed-settings=on|off
613 Use fixed settings for host audio. When off, it will change based on
614 how the guest opens the sound card. In this case you must not specify
615 @var{frequency}, @var{channels} or @var{format}. Default is on.
617 @item in|out.frequency=@var{frequency}
618 Specify the @var{frequency} to use when using @var{fixed-settings}.
619 Default is 44100Hz.
621 @item in|out.channels=@var{channels}
622 Specify the number of @var{channels} to use when using
623 @var{fixed-settings}. Default is 2 (stereo).
625 @item in|out.format=@var{format}
626 Specify the sample @var{format} to use when using @var{fixed-settings}.
627 Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
628 @code{u16}, @code{u32}. Default is @code{s16}.
630 @item in|out.voices=@var{voices}
631 Specify the number of @var{voices} to use. Default is 1.
633 @item in|out.buffer-length=@var{usecs}
634 Sets the size of the buffer in microseconds.
636 @end table
638 @item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]]
639 Creates a dummy backend that discards all outputs. This backend has no
640 backend specific properties.
642 @item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
643 Creates backend using the ALSA. This backend is only available on
644 Linux.
646 ALSA specific options are:
648 @table @option
650 @item in|out.dev=@var{device}
651 Specify the ALSA @var{device} to use for input and/or output. Default
652 is @code{default}.
654 @item in|out.period-length=@var{usecs}
655 Sets the period length in microseconds.
657 @item in|out.try-poll=on|off
658 Attempt to use poll mode with the device. Default is on.
660 @item threshold=@var{threshold}
661 Threshold (in microseconds) when playback starts. Default is 0.
663 @end table
665 @item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]]
666 Creates a backend using Apple's Core Audio. This backend is only
667 available on Mac OS and only supports playback.
669 Core Audio specific options are:
671 @table @option
673 @item in|out.buffer-count=@var{count}
674 Sets the @var{count} of the buffers.
676 @end table
678 @item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]]
679 Creates a backend using Microsoft's DirectSound. This backend is only
680 available on Windows and only supports playback.
682 DirectSound specific options are:
684 @table @option
686 @item latency=@var{usecs}
687 Add extra @var{usecs} microseconds latency to playback. Default is
688 10000 (10 ms).
690 @end table
692 @item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]]
693 Creates a backend using OSS. This backend is available on most
694 Unix-like systems.
696 OSS specific options are:
698 @table @option
700 @item in|out.dev=@var{device}
701 Specify the file name of the OSS @var{device} to use. Default is
702 @code{/dev/dsp}.
704 @item in|out.buffer-count=@var{count}
705 Sets the @var{count} of the buffers.
707 @item in|out.try-poll=on|of
708 Attempt to use poll mode with the device. Default is on.
710 @item try-mmap=on|off
711 Try using memory mapped device access. Default is off.
713 @item exclusive=on|off
714 Open the device in exclusive mode (vmix won't work in this case).
715 Default is off.
717 @item dsp-policy=@var{policy}
718 Sets the timing policy (between 0 and 10, where smaller number means
719 smaller latency but higher CPU usage). Use -1 to use buffer sizes
720 specified by @code{buffer} and @code{buffer-count}. This option is
721 ignored if you do not have OSS 4. Default is 5.
723 @end table
725 @item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
726 Creates a backend using PulseAudio. This backend is available on most
727 systems.
729 PulseAudio specific options are:
731 @table @option
733 @item server=@var{server}
734 Sets the PulseAudio @var{server} to connect to.
736 @item in|out.name=@var{sink}
737 Use the specified source/sink for recording/playback.
739 @item in|out.latency=@var{usecs}
740 Desired latency in microseconds. The PulseAudio server will try to honor this
741 value but actual latencies may be lower or higher.
743 @end table
745 @item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
746 Creates a backend using SDL. This backend is available on most systems,
747 but you should use your platform's native backend if possible. This
748 backend has no backend specific properties.
750 @item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]]
751 Creates a backend that sends audio through SPICE. This backend requires
752 @code{-spice} and automatically selected in that case, so usually you
753 can ignore this option. This backend has no backend specific
754 properties.
756 @item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
757 Creates a backend that writes audio to a WAV file.
759 Backend specific options are:
761 @table @option
763 @item path=@var{path}
764 Write recorded audio into the specified file. Default is
765 @code{qemu.wav}.
767 @end table
768 ETEXI
770 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
771 "-soundhw c1,... enable audio support\n"
772 " and only specified sound cards (comma separated list)\n"
773 " use '-soundhw help' to get the list of supported cards\n"
774 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
775 STEXI
776 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
777 @findex -soundhw
778 Enable audio and selected sound hardware. Use 'help' to print all
779 available sound hardware. For example:
781 @example
782 @value{qemu_system_x86} -soundhw sb16,adlib disk.img
783 @value{qemu_system_x86} -soundhw es1370 disk.img
784 @value{qemu_system_x86} -soundhw ac97 disk.img
785 @value{qemu_system_x86} -soundhw hda disk.img
786 @value{qemu_system_x86} -soundhw all disk.img
787 @value{qemu_system_x86} -soundhw help
788 @end example
790 Note that Linux's i810_audio OSS kernel (for AC97) module might
791 require manually specifying clocking.
793 @example
794 modprobe i810_audio clocking=48000
795 @end example
796 ETEXI
798 DEF("device", HAS_ARG, QEMU_OPTION_device,
799 "-device driver[,prop[=value][,...]]\n"
800 " add device (based on driver)\n"
801 " prop=value,... sets driver properties\n"
802 " use '-device help' to print all possible drivers\n"
803 " use '-device driver,help' to print all possible properties\n",
804 QEMU_ARCH_ALL)
805 STEXI
806 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
807 @findex -device
808 Add device @var{driver}. @var{prop}=@var{value} sets driver
809 properties. Valid properties depend on the driver. To get help on
810 possible drivers and properties, use @code{-device help} and
811 @code{-device @var{driver},help}.
813 Some drivers are:
814 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}]
816 Add an IPMI BMC. This is a simulation of a hardware management
817 interface processor that normally sits on a system. It provides
818 a watchdog and the ability to reset and power control the system.
819 You need to connect this to an IPMI interface to make it useful
821 The IPMI slave address to use for the BMC. The default is 0x20.
822 This address is the BMC's address on the I2C network of management
823 controllers. If you don't know what this means, it is safe to ignore
826 @table @option
827 @item id=@var{id}
828 The BMC id for interfaces to use this device.
829 @item slave_addr=@var{val}
830 Define slave address to use for the BMC. The default is 0x20.
831 @item sdrfile=@var{file}
832 file containing raw Sensor Data Records (SDR) data. The default is none.
833 @item fruareasize=@var{val}
834 size of a Field Replaceable Unit (FRU) area. The default is 1024.
835 @item frudatafile=@var{file}
836 file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
837 @item guid=@var{uuid}
838 value for the GUID for the BMC, in standard UUID format. If this is set,
839 get "Get GUID" command to the BMC will return it. Otherwise "Get GUID"
840 will return an error.
841 @end table
843 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
845 Add a connection to an external IPMI BMC simulator. Instead of
846 locally emulating the BMC like the above item, instead connect
847 to an external entity that provides the IPMI services.
849 A connection is made to an external BMC simulator. If you do this, it
850 is strongly recommended that you use the "reconnect=" chardev option
851 to reconnect to the simulator if the connection is lost. Note that if
852 this is not used carefully, it can be a security issue, as the
853 interface has the ability to send resets, NMIs, and power off the VM.
854 It's best if QEMU makes a connection to an external simulator running
855 on a secure port on localhost, so neither the simulator nor QEMU is
856 exposed to any outside network.
858 See the "lanserv/README.vm" file in the OpenIPMI library for more
859 details on the external interface.
861 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
863 Add a KCS IPMI interafce on the ISA bus. This also adds a
864 corresponding ACPI and SMBIOS entries, if appropriate.
866 @table @option
867 @item bmc=@var{id}
868 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
869 @item ioport=@var{val}
870 Define the I/O address of the interface. The default is 0xca0 for KCS.
871 @item irq=@var{val}
872 Define the interrupt to use. The default is 5. To disable interrupts,
873 set this to 0.
874 @end table
876 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
878 Like the KCS interface, but defines a BT interface. The default port is
879 0xe4 and the default interrupt is 5.
881 ETEXI
883 DEF("name", HAS_ARG, QEMU_OPTION_name,
884 "-name string1[,process=string2][,debug-threads=on|off]\n"
885 " set the name of the guest\n"
886 " string1 sets the window title and string2 the process name\n"
887 " When debug-threads is enabled, individual threads are given a separate name\n"
888 " NOTE: The thread names are for debugging and not a stable API.\n",
889 QEMU_ARCH_ALL)
890 STEXI
891 @item -name @var{name}
892 @findex -name
893 Sets the @var{name} of the guest.
894 This name will be displayed in the SDL window caption.
895 The @var{name} will also be used for the VNC server.
896 Also optionally set the top visible process name in Linux.
897 Naming of individual threads can also be enabled on Linux to aid debugging.
898 ETEXI
900 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
901 "-uuid %08x-%04x-%04x-%04x-%012x\n"
902 " specify machine UUID\n", QEMU_ARCH_ALL)
903 STEXI
904 @item -uuid @var{uuid}
905 @findex -uuid
906 Set system UUID.
907 ETEXI
909 STEXI
910 @end table
911 ETEXI
912 DEFHEADING()
914 DEFHEADING(Block device options:)
915 STEXI
916 @table @option
917 ETEXI
919 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
920 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
921 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
922 STEXI
923 @item -fda @var{file}
924 @itemx -fdb @var{file}
925 @findex -fda
926 @findex -fdb
927 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
928 ETEXI
930 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
931 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
932 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
933 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
934 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
935 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
936 STEXI
937 @item -hda @var{file}
938 @itemx -hdb @var{file}
939 @itemx -hdc @var{file}
940 @itemx -hdd @var{file}
941 @findex -hda
942 @findex -hdb
943 @findex -hdc
944 @findex -hdd
945 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
946 ETEXI
948 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
949 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
950 QEMU_ARCH_ALL)
951 STEXI
952 @item -cdrom @var{file}
953 @findex -cdrom
954 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
955 @option{-cdrom} at the same time). You can use the host CD-ROM by
956 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
957 ETEXI
959 DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
960 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
961 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
962 " [,read-only=on|off][,auto-read-only=on|off]\n"
963 " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
964 " [,driver specific parameters...]\n"
965 " configure a block backend\n", QEMU_ARCH_ALL)
966 STEXI
967 @item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
968 @findex -blockdev
970 Define a new block driver node. Some of the options apply to all block drivers,
971 other options are only accepted for a specific block driver. See below for a
972 list of generic options and options for the most common block drivers.
974 Options that expect a reference to another node (e.g. @code{file}) can be
975 given in two ways. Either you specify the node name of an already existing node
976 (file=@var{node-name}), or you define a new node inline, adding options
977 for the referenced node after a dot (file.filename=@var{path},file.aio=native).
979 A block driver node created with @option{-blockdev} can be used for a guest
980 device by specifying its node name for the @code{drive} property in a
981 @option{-device} argument that defines a block device.
983 @table @option
984 @item Valid options for any block driver node:
986 @table @code
987 @item driver
988 Specifies the block driver to use for the given node.
989 @item node-name
990 This defines the name of the block driver node by which it will be referenced
991 later. The name must be unique, i.e. it must not match the name of a different
992 block driver node, or (if you use @option{-drive} as well) the ID of a drive.
994 If no node name is specified, it is automatically generated. The generated node
995 name is not intended to be predictable and changes between QEMU invocations.
996 For the top level, an explicit node name must be specified.
997 @item read-only
998 Open the node read-only. Guest write attempts will fail.
1000 Note that some block drivers support only read-only access, either generally or
1001 in certain configurations. In this case, the default value
1002 @option{read-only=off} does not work and the option must be specified
1003 explicitly.
1004 @item auto-read-only
1005 If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage
1006 even when @option{read-only=off} is requested, or even switch between modes as
1007 needed, e.g. depending on whether the image file is writable or whether a
1008 writing user is attached to the node.
1009 @item force-share
1010 Override the image locking system of QEMU by forcing the node to utilize
1011 weaker shared access for permissions where it would normally request exclusive
1012 access. When there is the potential for multiple instances to have the same
1013 file open (whether this invocation of QEMU is the first or the second
1014 instance), both instances must permit shared access for the second instance to
1015 succeed at opening the file.
1017 Enabling @option{force-share=on} requires @option{read-only=on}.
1018 @item cache.direct
1019 The host page cache can be avoided with @option{cache.direct=on}. This will
1020 attempt to do disk IO directly to the guest's memory. QEMU may still perform an
1021 internal copy of the data.
1022 @item cache.no-flush
1023 In case you don't care about data integrity over host failures, you can use
1024 @option{cache.no-flush=on}. This option tells QEMU that it never needs to write
1025 any data to the disk but can instead keep things in cache. If anything goes
1026 wrong, like your host losing power, the disk storage getting disconnected
1027 accidentally, etc. your image will most probably be rendered unusable.
1028 @item discard=@var{discard}
1029 @var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
1030 whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
1031 ignored or passed to the filesystem. Some machine types may not support
1032 discard requests.
1033 @item detect-zeroes=@var{detect-zeroes}
1034 @var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
1035 conversion of plain zero writes by the OS to driver specific optimized
1036 zero write commands. You may even choose "unmap" if @var{discard} is set
1037 to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
1038 @end table
1040 @item Driver-specific options for @code{file}
1042 This is the protocol-level block driver for accessing regular files.
1044 @table @code
1045 @item filename
1046 The path to the image file in the local filesystem
1047 @item aio
1048 Specifies the AIO backend (threads/native, default: threads)
1049 @item locking
1050 Specifies whether the image file is protected with Linux OFD / POSIX locks. The
1051 default is to use the Linux Open File Descriptor API if available, otherwise no
1052 lock is applied. (auto/on/off, default: auto)
1053 @end table
1054 Example:
1055 @example
1056 -blockdev driver=file,node-name=disk,filename=disk.img
1057 @end example
1059 @item Driver-specific options for @code{raw}
1061 This is the image format block driver for raw images. It is usually
1062 stacked on top of a protocol level block driver such as @code{file}.
1064 @table @code
1065 @item file
1066 Reference to or definition of the data source block driver node
1067 (e.g. a @code{file} driver node)
1068 @end table
1069 Example 1:
1070 @example
1071 -blockdev driver=file,node-name=disk_file,filename=disk.img
1072 -blockdev driver=raw,node-name=disk,file=disk_file
1073 @end example
1074 Example 2:
1075 @example
1076 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
1077 @end example
1079 @item Driver-specific options for @code{qcow2}
1081 This is the image format block driver for qcow2 images. It is usually
1082 stacked on top of a protocol level block driver such as @code{file}.
1084 @table @code
1085 @item file
1086 Reference to or definition of the data source block driver node
1087 (e.g. a @code{file} driver node)
1089 @item backing
1090 Reference to or definition of the backing file block device (default is taken
1091 from the image file). It is allowed to pass @code{null} here in order to disable
1092 the default backing file.
1094 @item lazy-refcounts
1095 Whether to enable the lazy refcounts feature (on/off; default is taken from the
1096 image file)
1098 @item cache-size
1099 The maximum total size of the L2 table and refcount block caches in bytes
1100 (default: the sum of l2-cache-size and refcount-cache-size)
1102 @item l2-cache-size
1103 The maximum size of the L2 table cache in bytes
1104 (default: if cache-size is not specified - 32M on Linux platforms, and 8M on
1105 non-Linux platforms; otherwise, as large as possible within the cache-size,
1106 while permitting the requested or the minimal refcount cache size)
1108 @item refcount-cache-size
1109 The maximum size of the refcount block cache in bytes
1110 (default: 4 times the cluster size; or if cache-size is specified, the part of
1111 it which is not used for the L2 cache)
1113 @item cache-clean-interval
1114 Clean unused entries in the L2 and refcount caches. The interval is in seconds.
1115 The default value is 600 on supporting platforms, and 0 on other platforms.
1116 Setting it to 0 disables this feature.
1118 @item pass-discard-request
1119 Whether discard requests to the qcow2 device should be forwarded to the data
1120 source (on/off; default: on if discard=unmap is specified, off otherwise)
1122 @item pass-discard-snapshot
1123 Whether discard requests for the data source should be issued when a snapshot
1124 operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
1125 default: on)
1127 @item pass-discard-other
1128 Whether discard requests for the data source should be issued on other
1129 occasions where a cluster gets freed (on/off; default: off)
1131 @item overlap-check
1132 Which overlap checks to perform for writes to the image
1133 (none/constant/cached/all; default: cached). For details or finer
1134 granularity control refer to the QAPI documentation of @code{blockdev-add}.
1135 @end table
1137 Example 1:
1138 @example
1139 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1140 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1141 @end example
1142 Example 2:
1143 @example
1144 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1145 @end example
1147 @item Driver-specific options for other drivers
1148 Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
1150 @end table
1152 ETEXI
1154 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
1155 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
1156 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
1157 " [,snapshot=on|off][,rerror=ignore|stop|report]\n"
1158 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
1159 " [,readonly=on|off][,copy-on-read=on|off]\n"
1160 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
1161 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
1162 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
1163 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
1164 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
1165 " [[,iops_size=is]]\n"
1166 " [[,group=g]]\n"
1167 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
1168 STEXI
1169 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
1170 @findex -drive
1172 Define a new drive. This includes creating a block driver node (the backend) as
1173 well as a guest device, and is mostly a shortcut for defining the corresponding
1174 @option{-blockdev} and @option{-device} options.
1176 @option{-drive} accepts all options that are accepted by @option{-blockdev}. In
1177 addition, it knows the following options:
1179 @table @option
1180 @item file=@var{file}
1181 This option defines which disk image (@pxref{disk_images}) to use with
1182 this drive. If the filename contains comma, you must double it
1183 (for instance, "file=my,,file" to use file "my,file").
1185 Special files such as iSCSI devices can be specified using protocol
1186 specific URLs. See the section for "Device URL Syntax" for more information.
1187 @item if=@var{interface}
1188 This option defines on which type on interface the drive is connected.
1189 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
1190 @item bus=@var{bus},unit=@var{unit}
1191 These options define where is connected the drive by defining the bus number and
1192 the unit id.
1193 @item index=@var{index}
1194 This option defines where is connected the drive by using an index in the list
1195 of available connectors of a given interface type.
1196 @item media=@var{media}
1197 This option defines the type of the media: disk or cdrom.
1198 @item snapshot=@var{snapshot}
1199 @var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
1200 (see @option{-snapshot}).
1201 @item cache=@var{cache}
1202 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
1203 and controls how the host cache is used to access block data. This is a
1204 shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
1205 options (as in @option{-blockdev}), and additionally @option{cache.writeback},
1206 which provides a default for the @option{write-cache} option of block guest
1207 devices (as in @option{-device}). The modes correspond to the following
1208 settings:
1210 @c Our texi2pod.pl script doesn't support @multitable, so fall back to using
1211 @c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
1212 @c and the HTML output.
1213 @example
1214 @ │ cache.writeback cache.direct cache.no-flush
1215 ─────────────┼─────────────────────────────────────────────────
1216 writeback │ on off off
1217 none │ on on off
1218 writethrough │ off off off
1219 directsync │ off on off
1220 unsafe │ on off on
1221 @end example
1223 The default mode is @option{cache=writeback}.
1225 @item aio=@var{aio}
1226 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
1227 @item format=@var{format}
1228 Specify which disk @var{format} will be used rather than detecting
1229 the format. Can be used to specify format=raw to avoid interpreting
1230 an untrusted format header.
1231 @item werror=@var{action},rerror=@var{action}
1232 Specify which @var{action} to take on write and read errors. Valid actions are:
1233 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
1234 "report" (report the error to the guest), "enospc" (pause QEMU only if the
1235 host disk is full; report the error to the guest otherwise).
1236 The default setting is @option{werror=enospc} and @option{rerror=report}.
1237 @item copy-on-read=@var{copy-on-read}
1238 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
1239 file sectors into the image file.
1240 @item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
1241 Specify bandwidth throttling limits in bytes per second, either for all request
1242 types or for reads or writes only. Small values can lead to timeouts or hangs
1243 inside the guest. A safe minimum for disks is 2 MB/s.
1244 @item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
1245 Specify bursts in bytes per second, either for all request types or for reads
1246 or writes only. Bursts allow the guest I/O to spike above the limit
1247 temporarily.
1248 @item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
1249 Specify request rate limits in requests per second, either for all request
1250 types or for reads or writes only.
1251 @item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
1252 Specify bursts in requests per second, either for all request types or for reads
1253 or writes only. Bursts allow the guest I/O to spike above the limit
1254 temporarily.
1255 @item iops_size=@var{is}
1256 Let every @var{is} bytes of a request count as a new request for iops
1257 throttling purposes. Use this option to prevent guests from circumventing iops
1258 limits by sending fewer but larger requests.
1259 @item group=@var{g}
1260 Join a throttling quota group with given name @var{g}. All drives that are
1261 members of the same group are accounted for together. Use this option to
1262 prevent guests from circumventing throttling limits by using many small disks
1263 instead of a single larger disk.
1264 @end table
1266 By default, the @option{cache.writeback=on} mode is used. It will report data
1267 writes as completed as soon as the data is present in the host page cache.
1268 This is safe as long as your guest OS makes sure to correctly flush disk caches
1269 where needed. If your guest OS does not handle volatile disk write caches
1270 correctly and your host crashes or loses power, then the guest may experience
1271 data corruption.
1273 For such guests, you should consider using @option{cache.writeback=off}. This
1274 means that the host page cache will be used to read and write data, but write
1275 notification will be sent to the guest only after QEMU has made sure to flush
1276 each write to the disk. Be aware that this has a major impact on performance.
1278 When using the @option{-snapshot} option, unsafe caching is always used.
1280 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
1281 useful when the backing file is over a slow network. By default copy-on-read
1282 is off.
1284 Instead of @option{-cdrom} you can use:
1285 @example
1286 @value{qemu_system} -drive file=file,index=2,media=cdrom
1287 @end example
1289 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
1290 use:
1291 @example
1292 @value{qemu_system} -drive file=file,index=0,media=disk
1293 @value{qemu_system} -drive file=file,index=1,media=disk
1294 @value{qemu_system} -drive file=file,index=2,media=disk
1295 @value{qemu_system} -drive file=file,index=3,media=disk
1296 @end example
1298 You can open an image using pre-opened file descriptors from an fd set:
1299 @example
1300 @value{qemu_system} \
1301 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
1302 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
1303 -drive file=/dev/fdset/2,index=0,media=disk
1304 @end example
1306 You can connect a CDROM to the slave of ide0:
1307 @example
1308 @value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom
1309 @end example
1311 If you don't specify the "file=" argument, you define an empty drive:
1312 @example
1313 @value{qemu_system_x86} -drive if=ide,index=1,media=cdrom
1314 @end example
1316 Instead of @option{-fda}, @option{-fdb}, you can use:
1317 @example
1318 @value{qemu_system_x86} -drive file=file,index=0,if=floppy
1319 @value{qemu_system_x86} -drive file=file,index=1,if=floppy
1320 @end example
1322 By default, @var{interface} is "ide" and @var{index} is automatically
1323 incremented:
1324 @example
1325 @value{qemu_system_x86} -drive file=a -drive file=b"
1326 @end example
1327 is interpreted like:
1328 @example
1329 @value{qemu_system_x86} -hda a -hdb b
1330 @end example
1331 ETEXI
1333 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
1334 "-mtdblock file use 'file' as on-board Flash memory image\n",
1335 QEMU_ARCH_ALL)
1336 STEXI
1337 @item -mtdblock @var{file}
1338 @findex -mtdblock
1339 Use @var{file} as on-board Flash memory image.
1340 ETEXI
1342 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
1343 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
1344 STEXI
1345 @item -sd @var{file}
1346 @findex -sd
1347 Use @var{file} as SecureDigital card image.
1348 ETEXI
1350 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
1351 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
1352 STEXI
1353 @item -pflash @var{file}
1354 @findex -pflash
1355 Use @var{file} as a parallel flash image.
1356 ETEXI
1358 DEF("snapshot", 0, QEMU_OPTION_snapshot,
1359 "-snapshot write to temporary files instead of disk image files\n",
1360 QEMU_ARCH_ALL)
1361 STEXI
1362 @item -snapshot
1363 @findex -snapshot
1364 Write to temporary files instead of disk image files. In this case,
1365 the raw disk image you use is not written back. You can however force
1366 the write back by pressing @key{C-a s} (@pxref{disk_images}).
1367 ETEXI
1369 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
1370 "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1371 " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n"
1372 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1373 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1374 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1375 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1376 " [[,throttling.iops-size=is]]\n"
1377 "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n"
1378 "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n"
1379 "-fsdev synth,id=id\n",
1380 QEMU_ARCH_ALL)
1382 STEXI
1384 @item -fsdev local,id=@var{id},path=@var{path},security_model=@var{security_model} [,writeout=@var{writeout}][,readonly][,fmode=@var{fmode}][,dmode=@var{dmode}] [,throttling.@var{option}=@var{value}[,throttling.@var{option}=@var{value}[,...]]]
1385 @itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly]
1386 @itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly]
1387 @itemx -fsdev synth,id=@var{id}[,readonly]
1388 @findex -fsdev
1389 Define a new file system device. Valid options are:
1390 @table @option
1391 @item local
1392 Accesses to the filesystem are done by QEMU.
1393 @item proxy
1394 Accesses to the filesystem are done by virtfs-proxy-helper(1).
1395 @item synth
1396 Synthetic filesystem, only used by QTests.
1397 @item id=@var{id}
1398 Specifies identifier for this device.
1399 @item path=@var{path}
1400 Specifies the export path for the file system device. Files under
1401 this path will be available to the 9p client on the guest.
1402 @item security_model=@var{security_model}
1403 Specifies the security model to be used for this export path.
1404 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
1405 In "passthrough" security model, files are stored using the same
1406 credentials as they are created on the guest. This requires QEMU
1407 to run as root. In "mapped-xattr" security model, some of the file
1408 attributes like uid, gid, mode bits and link target are stored as
1409 file attributes. For "mapped-file" these attributes are stored in the
1410 hidden .virtfs_metadata directory. Directories exported by this security model cannot
1411 interact with other unix tools. "none" security model is same as
1412 passthrough except the sever won't report failures if it fails to
1413 set file attributes like ownership. Security model is mandatory
1414 only for local fsdriver. Other fsdrivers (like proxy) don't take
1415 security model as a parameter.
1416 @item writeout=@var{writeout}
1417 This is an optional argument. The only supported value is "immediate".
1418 This means that host page cache will be used to read and write data but
1419 write notification will be sent to the guest only when the data has been
1420 reported as written by the storage subsystem.
1421 @item readonly
1422 Enables exporting 9p share as a readonly mount for guests. By default
1423 read-write access is given.
1424 @item socket=@var{socket}
1425 Enables proxy filesystem driver to use passed socket file for communicating
1426 with virtfs-proxy-helper(1).
1427 @item sock_fd=@var{sock_fd}
1428 Enables proxy filesystem driver to use passed socket descriptor for
1429 communicating with virtfs-proxy-helper(1). Usually a helper like libvirt
1430 will create socketpair and pass one of the fds as sock_fd.
1431 @item fmode=@var{fmode}
1432 Specifies the default mode for newly created files on the host. Works only
1433 with security models "mapped-xattr" and "mapped-file".
1434 @item dmode=@var{dmode}
1435 Specifies the default mode for newly created directories on the host. Works
1436 only with security models "mapped-xattr" and "mapped-file".
1437 @item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w}
1438 Specify bandwidth throttling limits in bytes per second, either for all request
1439 types or for reads or writes only.
1440 @item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm}
1441 Specify bursts in bytes per second, either for all request types or for reads
1442 or writes only. Bursts allow the guest I/O to spike above the limit
1443 temporarily.
1444 @item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w}
1445 Specify request rate limits in requests per second, either for all request
1446 types or for reads or writes only.
1447 @item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm}
1448 Specify bursts in requests per second, either for all request types or for reads
1449 or writes only. Bursts allow the guest I/O to spike above the limit temporarily.
1450 @item throttling.iops-size=@var{is}
1451 Let every @var{is} bytes of a request count as a new request for iops
1452 throttling purposes.
1453 @end table
1455 -fsdev option is used along with -device driver "virtio-9p-...".
1456 @item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag}
1457 Options for virtio-9p-... driver are:
1458 @table @option
1459 @item @var{type}
1460 Specifies the variant to be used. Supported values are "pci", "ccw" or "device",
1461 depending on the machine type.
1462 @item fsdev=@var{id}
1463 Specifies the id value specified along with -fsdev option.
1464 @item mount_tag=@var{mount_tag}
1465 Specifies the tag name to be used by the guest to mount this export point.
1466 @end table
1468 ETEXI
1470 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
1471 "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1472 " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
1473 "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n"
1474 "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n"
1475 "-virtfs synth,mount_tag=tag[,id=id][,readonly]\n",
1476 QEMU_ARCH_ALL)
1478 STEXI
1480 @item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}][,multidevs=@var{multidevs}]
1481 @itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
1482 @itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
1483 @itemx -virtfs synth,mount_tag=@var{mount_tag}
1484 @findex -virtfs
1486 Define a new filesystem device and expose it to the guest using a virtio-9p-device. The general form of a Virtual File system pass-through options are:
1487 @table @option
1488 @item local
1489 Accesses to the filesystem are done by QEMU.
1490 @item proxy
1491 Accesses to the filesystem are done by virtfs-proxy-helper(1).
1492 @item synth
1493 Synthetic filesystem, only used by QTests.
1494 @item id=@var{id}
1495 Specifies identifier for the filesystem device
1496 @item path=@var{path}
1497 Specifies the export path for the file system device. Files under
1498 this path will be available to the 9p client on the guest.
1499 @item security_model=@var{security_model}
1500 Specifies the security model to be used for this export path.
1501 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
1502 In "passthrough" security model, files are stored using the same
1503 credentials as they are created on the guest. This requires QEMU
1504 to run as root. In "mapped-xattr" security model, some of the file
1505 attributes like uid, gid, mode bits and link target are stored as
1506 file attributes. For "mapped-file" these attributes are stored in the
1507 hidden .virtfs_metadata directory. Directories exported by this security model cannot
1508 interact with other unix tools. "none" security model is same as
1509 passthrough except the sever won't report failures if it fails to
1510 set file attributes like ownership. Security model is mandatory only
1511 for local fsdriver. Other fsdrivers (like proxy) don't take security
1512 model as a parameter.
1513 @item writeout=@var{writeout}
1514 This is an optional argument. The only supported value is "immediate".
1515 This means that host page cache will be used to read and write data but
1516 write notification will be sent to the guest only when the data has been
1517 reported as written by the storage subsystem.
1518 @item readonly
1519 Enables exporting 9p share as a readonly mount for guests. By default
1520 read-write access is given.
1521 @item socket=@var{socket}
1522 Enables proxy filesystem driver to use passed socket file for
1523 communicating with virtfs-proxy-helper(1). Usually a helper like libvirt
1524 will create socketpair and pass one of the fds as sock_fd.
1525 @item sock_fd
1526 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1527 descriptor for interfacing with virtfs-proxy-helper(1).
1528 @item fmode=@var{fmode}
1529 Specifies the default mode for newly created files on the host. Works only
1530 with security models "mapped-xattr" and "mapped-file".
1531 @item dmode=@var{dmode}
1532 Specifies the default mode for newly created directories on the host. Works
1533 only with security models "mapped-xattr" and "mapped-file".
1534 @item mount_tag=@var{mount_tag}
1535 Specifies the tag name to be used by the guest to mount this export point.
1536 @item multidevs=@var{multidevs}
1537 Specifies how to deal with multiple devices being shared with a 9p export.
1538 Supported behaviours are either "remap", "forbid" or "warn". The latter is
1539 the default behaviour on which virtfs 9p expects only one device to be
1540 shared with the same export, and if more than one device is shared and
1541 accessed via the same 9p export then only a warning message is logged
1542 (once) by qemu on host side. In order to avoid file ID collisions on guest
1543 you should either create a separate virtfs export for each device to be
1544 shared with guests (recommended way) or you might use "remap" instead which
1545 allows you to share multiple devices with only one export instead, which is
1546 achieved by remapping the original inode numbers from host to guest in a
1547 way that would prevent such collisions. Remapping inodes in such use cases
1548 is required because the original device IDs from host are never passed and
1549 exposed on guest. Instead all files of an export shared with virtfs always
1550 share the same device id on guest. So two files with identical inode
1551 numbers but from actually different devices on host would otherwise cause a
1552 file ID collision and hence potential misbehaviours on guest. "forbid" on
1553 the other hand assumes like "warn" that only one device is shared by the
1554 same export, however it will not only log a warning message but also
1555 deny access to additional devices on guest. Note though that "forbid" does
1556 currently not block all possible file access operations (e.g. readdir()
1557 would still return entries from other devices).
1558 @end table
1559 ETEXI
1561 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1562 "-iscsi [user=user][,password=password]\n"
1563 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1564 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1565 " [,timeout=timeout]\n"
1566 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1568 STEXI
1569 @item -iscsi
1570 @findex -iscsi
1571 Configure iSCSI session parameters.
1572 ETEXI
1574 STEXI
1575 @end table
1576 ETEXI
1577 DEFHEADING()
1579 DEFHEADING(USB options:)
1580 STEXI
1581 @table @option
1582 ETEXI
1584 DEF("usb", 0, QEMU_OPTION_usb,
1585 "-usb enable on-board USB host controller (if not enabled by default)\n",
1586 QEMU_ARCH_ALL)
1587 STEXI
1588 @item -usb
1589 @findex -usb
1590 Enable USB emulation on machine types with an on-board USB host controller (if
1591 not enabled by default). Note that on-board USB host controllers may not
1592 support USB 3.0. In this case @option{-device qemu-xhci} can be used instead
1593 on machines with PCI.
1594 ETEXI
1596 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1597 "-usbdevice name add the host or guest USB device 'name'\n",
1598 QEMU_ARCH_ALL)
1599 STEXI
1601 @item -usbdevice @var{devname}
1602 @findex -usbdevice
1603 Add the USB device @var{devname}. Note that this option is deprecated,
1604 please use @code{-device usb-...} instead. @xref{usb_devices}.
1606 @table @option
1608 @item mouse
1609 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1611 @item tablet
1612 Pointer device that uses absolute coordinates (like a touchscreen). This
1613 means QEMU is able to report the mouse position without having to grab the
1614 mouse. Also overrides the PS/2 mouse emulation when activated.
1616 @item braille
1617 Braille device. This will use BrlAPI to display the braille output on a real
1618 or fake device.
1620 @end table
1621 ETEXI
1623 STEXI
1624 @end table
1625 ETEXI
1626 DEFHEADING()
1628 DEFHEADING(Display options:)
1629 STEXI
1630 @table @option
1631 ETEXI
1633 DEF("display", HAS_ARG, QEMU_OPTION_display,
1634 #if defined(CONFIG_SPICE)
1635 "-display spice-app[,gl=on|off]\n"
1636 #endif
1637 #if defined(CONFIG_SDL)
1638 "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
1639 " [,window_close=on|off][,gl=on|core|es|off]\n"
1640 #endif
1641 #if defined(CONFIG_GTK)
1642 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1643 #endif
1644 #if defined(CONFIG_VNC)
1645 "-display vnc=<display>[,<optargs>]\n"
1646 #endif
1647 #if defined(CONFIG_CURSES)
1648 "-display curses[,charset=<encoding>]\n"
1649 #endif
1650 #if defined(CONFIG_OPENGL)
1651 "-display egl-headless[,rendernode=<file>]\n"
1652 #endif
1653 "-display none\n"
1654 " select display backend type\n"
1655 " The default display is equivalent to\n "
1656 #if defined(CONFIG_GTK)
1657 "\"-display gtk\"\n"
1658 #elif defined(CONFIG_SDL)
1659 "\"-display sdl\"\n"
1660 #elif defined(CONFIG_COCOA)
1661 "\"-display cocoa\"\n"
1662 #elif defined(CONFIG_VNC)
1663 "\"-vnc localhost:0,to=99,id=default\"\n"
1664 #else
1665 "\"-display none\"\n"
1666 #endif
1667 , QEMU_ARCH_ALL)
1668 STEXI
1669 @item -display @var{type}
1670 @findex -display
1671 Select type of display to use. This option is a replacement for the
1672 old style -sdl/-curses/... options. Use @code{-display help} to list
1673 the available display types. Valid values for @var{type} are
1674 @table @option
1675 @item sdl
1676 Display video output via SDL (usually in a separate graphics
1677 window; see the SDL documentation for other possibilities).
1678 @item curses
1679 Display video output via curses. For graphics device models which
1680 support a text mode, QEMU can display this output using a
1681 curses/ncurses interface. Nothing is displayed when the graphics
1682 device is in graphical mode or if the graphics device does not support
1683 a text mode. Generally only the VGA device models support text mode.
1684 The font charset used by the guest can be specified with the
1685 @code{charset} option, for example @code{charset=CP850} for IBM CP850
1686 encoding. The default is @code{CP437}.
1687 @item none
1688 Do not display video output. The guest will still see an emulated
1689 graphics card, but its output will not be displayed to the QEMU
1690 user. This option differs from the -nographic option in that it
1691 only affects what is done with video output; -nographic also changes
1692 the destination of the serial and parallel port data.
1693 @item gtk
1694 Display video output in a GTK window. This interface provides drop-down
1695 menus and other UI elements to configure and control the VM during
1696 runtime.
1697 @item vnc
1698 Start a VNC server on display <arg>
1699 @item egl-headless
1700 Offload all OpenGL operations to a local DRI device. For any graphical display,
1701 this display needs to be paired with either VNC or SPICE displays.
1702 @item spice-app
1703 Start QEMU as a Spice server and launch the default Spice client
1704 application. The Spice server will redirect the serial consoles and
1705 QEMU monitors. (Since 4.0)
1706 @end table
1707 ETEXI
1709 DEF("nographic", 0, QEMU_OPTION_nographic,
1710 "-nographic disable graphical output and redirect serial I/Os to console\n",
1711 QEMU_ARCH_ALL)
1712 STEXI
1713 @item -nographic
1714 @findex -nographic
1715 Normally, if QEMU is compiled with graphical window support, it displays
1716 output such as guest graphics, guest console, and the QEMU monitor in a
1717 window. With this option, you can totally disable graphical output so
1718 that QEMU is a simple command line application. The emulated serial port
1719 is redirected on the console and muxed with the monitor (unless
1720 redirected elsewhere explicitly). Therefore, you can still use QEMU to
1721 debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1722 switching between the console and monitor.
1723 ETEXI
1725 DEF("curses", 0, QEMU_OPTION_curses,
1726 "-curses shorthand for -display curses\n",
1727 QEMU_ARCH_ALL)
1728 STEXI
1729 @item -curses
1730 @findex -curses
1731 Normally, if QEMU is compiled with graphical window support, it displays
1732 output such as guest graphics, guest console, and the QEMU monitor in a
1733 window. With this option, QEMU can display the VGA output when in text
1734 mode using a curses/ncurses interface. Nothing is displayed in graphical
1735 mode.
1736 ETEXI
1738 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
1739 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1740 QEMU_ARCH_ALL)
1741 STEXI
1742 @item -alt-grab
1743 @findex -alt-grab
1744 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1745 affects the special keys (for fullscreen, monitor-mode switching, etc).
1746 ETEXI
1748 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
1749 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1750 QEMU_ARCH_ALL)
1751 STEXI
1752 @item -ctrl-grab
1753 @findex -ctrl-grab
1754 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1755 affects the special keys (for fullscreen, monitor-mode switching, etc).
1756 ETEXI
1758 DEF("no-quit", 0, QEMU_OPTION_no_quit,
1759 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
1760 STEXI
1761 @item -no-quit
1762 @findex -no-quit
1763 Disable SDL window close capability.
1764 ETEXI
1766 DEF("sdl", 0, QEMU_OPTION_sdl,
1767 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
1768 STEXI
1769 @item -sdl
1770 @findex -sdl
1771 Enable SDL.
1772 ETEXI
1774 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
1775 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1776 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1777 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
1778 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
1779 " [,tls-ciphers=<list>]\n"
1780 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1781 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1782 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1783 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1784 " [,jpeg-wan-compression=[auto|never|always]]\n"
1785 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1786 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
1787 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1788 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
1789 " [,gl=[on|off]][,rendernode=<file>]\n"
1790 " enable spice\n"
1791 " at least one of {port, tls-port} is mandatory\n",
1792 QEMU_ARCH_ALL)
1793 STEXI
1794 @item -spice @var{option}[,@var{option}[,...]]
1795 @findex -spice
1796 Enable the spice remote desktop protocol. Valid options are
1798 @table @option
1800 @item port=<nr>
1801 Set the TCP port spice is listening on for plaintext channels.
1803 @item addr=<addr>
1804 Set the IP address spice is listening on. Default is any address.
1806 @item ipv4
1807 @itemx ipv6
1808 @itemx unix
1809 Force using the specified IP version.
1811 @item password=<secret>
1812 Set the password you need to authenticate.
1814 @item sasl
1815 Require that the client use SASL to authenticate with the spice.
1816 The exact choice of authentication method used is controlled from the
1817 system / user's SASL configuration file for the 'qemu' service. This
1818 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1819 unprivileged user, an environment variable SASL_CONF_PATH can be used
1820 to make it search alternate locations for the service config.
1821 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1822 it is recommended that SASL always be combined with the 'tls' and
1823 'x509' settings to enable use of SSL and server certificates. This
1824 ensures a data encryption preventing compromise of authentication
1825 credentials.
1827 @item disable-ticketing
1828 Allow client connects without authentication.
1830 @item disable-copy-paste
1831 Disable copy paste between the client and the guest.
1833 @item disable-agent-file-xfer
1834 Disable spice-vdagent based file-xfer between the client and the guest.
1836 @item tls-port=<nr>
1837 Set the TCP port spice is listening on for encrypted channels.
1839 @item x509-dir=<dir>
1840 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1842 @item x509-key-file=<file>
1843 @itemx x509-key-password=<file>
1844 @itemx x509-cert-file=<file>
1845 @itemx x509-cacert-file=<file>
1846 @itemx x509-dh-key-file=<file>
1847 The x509 file names can also be configured individually.
1849 @item tls-ciphers=<list>
1850 Specify which ciphers to use.
1852 @item tls-channel=[main|display|cursor|inputs|record|playback]
1853 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
1854 Force specific channel to be used with or without TLS encryption. The
1855 options can be specified multiple times to configure multiple
1856 channels. The special name "default" can be used to set the default
1857 mode. For channels which are not explicitly forced into one mode the
1858 spice client is allowed to pick tls/plaintext as he pleases.
1860 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1861 Configure image compression (lossless).
1862 Default is auto_glz.
1864 @item jpeg-wan-compression=[auto|never|always]
1865 @itemx zlib-glz-wan-compression=[auto|never|always]
1866 Configure wan image compression (lossy for slow links).
1867 Default is auto.
1869 @item streaming-video=[off|all|filter]
1870 Configure video stream detection. Default is off.
1872 @item agent-mouse=[on|off]
1873 Enable/disable passing mouse events via vdagent. Default is on.
1875 @item playback-compression=[on|off]
1876 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1878 @item seamless-migration=[on|off]
1879 Enable/disable spice seamless migration. Default is off.
1881 @item gl=[on|off]
1882 Enable/disable OpenGL context. Default is off.
1884 @item rendernode=<file>
1885 DRM render node for OpenGL rendering. If not specified, it will pick
1886 the first available. (Since 2.9)
1888 @end table
1889 ETEXI
1891 DEF("portrait", 0, QEMU_OPTION_portrait,
1892 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1893 QEMU_ARCH_ALL)
1894 STEXI
1895 @item -portrait
1896 @findex -portrait
1897 Rotate graphical output 90 deg left (only PXA LCD).
1898 ETEXI
1900 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1901 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1902 QEMU_ARCH_ALL)
1903 STEXI
1904 @item -rotate @var{deg}
1905 @findex -rotate
1906 Rotate graphical output some deg left (only PXA LCD).
1907 ETEXI
1909 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
1910 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
1911 " select video card type\n", QEMU_ARCH_ALL)
1912 STEXI
1913 @item -vga @var{type}
1914 @findex -vga
1915 Select type of VGA card to emulate. Valid values for @var{type} are
1916 @table @option
1917 @item cirrus
1918 Cirrus Logic GD5446 Video card. All Windows versions starting from
1919 Windows 95 should recognize and use this graphic card. For optimal
1920 performances, use 16 bit color depth in the guest and the host OS.
1921 (This card was the default before QEMU 2.2)
1922 @item std
1923 Standard VGA card with Bochs VBE extensions. If your guest OS
1924 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1925 to use high resolution modes (>= 1280x1024x16) then you should use
1926 this option. (This card is the default since QEMU 2.2)
1927 @item vmware
1928 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1929 recent XFree86/XOrg server or Windows guest with a driver for this
1930 card.
1931 @item qxl
1932 QXL paravirtual graphic card. It is VGA compatible (including VESA
1933 2.0 VBE support). Works best with qxl guest drivers installed though.
1934 Recommended choice when using the spice protocol.
1935 @item tcx
1936 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1937 sun4m machines and offers both 8-bit and 24-bit colour depths at a
1938 fixed resolution of 1024x768.
1939 @item cg3
1940 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1941 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1942 resolutions aimed at people wishing to run older Solaris versions.
1943 @item virtio
1944 Virtio VGA card.
1945 @item none
1946 Disable VGA card.
1947 @end table
1948 ETEXI
1950 DEF("full-screen", 0, QEMU_OPTION_full_screen,
1951 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
1952 STEXI
1953 @item -full-screen
1954 @findex -full-screen
1955 Start in full screen.
1956 ETEXI
1958 DEF("g", 1, QEMU_OPTION_g ,
1959 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1960 QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
1961 STEXI
1962 @item -g @var{width}x@var{height}[x@var{depth}]
1963 @findex -g
1964 Set the initial graphical resolution and depth (PPC, SPARC only).
1965 ETEXI
1967 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1968 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
1969 STEXI
1970 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1971 @findex -vnc
1972 Normally, if QEMU is compiled with graphical window support, it displays
1973 output such as guest graphics, guest console, and the QEMU monitor in a
1974 window. With this option, you can have QEMU listen on VNC display
1975 @var{display} and redirect the VGA display over the VNC session. It is
1976 very useful to enable the usb tablet device when using this option
1977 (option @option{-device usb-tablet}). When using the VNC display, you
1978 must use the @option{-k} parameter to set the keyboard layout if you are
1979 not using en-us. Valid syntax for the @var{display} is
1981 @table @option
1983 @item to=@var{L}
1985 With this option, QEMU will try next available VNC @var{display}s, until the
1986 number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1987 available, e.g. port 5900+@var{display} is already used by another
1988 application. By default, to=0.
1990 @item @var{host}:@var{d}
1992 TCP connections will only be allowed from @var{host} on display @var{d}.
1993 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1994 be omitted in which case the server will accept connections from any host.
1996 @item unix:@var{path}
1998 Connections will be allowed over UNIX domain sockets where @var{path} is the
1999 location of a unix socket to listen for connections on.
2001 @item none
2003 VNC is initialized but not started. The monitor @code{change} command
2004 can be used to later start the VNC server.
2006 @end table
2008 Following the @var{display} value there may be one or more @var{option} flags
2009 separated by commas. Valid options are
2011 @table @option
2013 @item reverse
2015 Connect to a listening VNC client via a ``reverse'' connection. The
2016 client is specified by the @var{display}. For reverse network
2017 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
2018 is a TCP port number, not a display number.
2020 @item websocket
2022 Opens an additional TCP listening port dedicated to VNC Websocket connections.
2023 If a bare @var{websocket} option is given, the Websocket port is
2024 5700+@var{display}. An alternative port can be specified with the
2025 syntax @code{websocket}=@var{port}.
2027 If @var{host} is specified connections will only be allowed from this host.
2028 It is possible to control the websocket listen address independently, using
2029 the syntax @code{websocket}=@var{host}:@var{port}.
2031 If no TLS credentials are provided, the websocket connection runs in
2032 unencrypted mode. If TLS credentials are provided, the websocket connection
2033 requires encrypted client connections.
2035 @item password
2037 Require that password based authentication is used for client connections.
2039 The password must be set separately using the @code{set_password} command in
2040 the @ref{pcsys_monitor}. The syntax to change your password is:
2041 @code{set_password <protocol> <password>} where <protocol> could be either
2042 "vnc" or "spice".
2044 If you would like to change <protocol> password expiration, you should use
2045 @code{expire_password <protocol> <expiration-time>} where expiration time could
2046 be one of the following options: now, never, +seconds or UNIX time of
2047 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
2048 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
2049 date and time).
2051 You can also use keywords "now" or "never" for the expiration time to
2052 allow <protocol> password to expire immediately or never expire.
2054 @item tls-creds=@var{ID}
2056 Provides the ID of a set of TLS credentials to use to secure the
2057 VNC server. They will apply to both the normal VNC server socket
2058 and the websocket socket (if enabled). Setting TLS credentials
2059 will cause the VNC server socket to enable the VeNCrypt auth
2060 mechanism. The credentials should have been previously created
2061 using the @option{-object tls-creds} argument.
2063 @item tls-authz=@var{ID}
2065 Provides the ID of the QAuthZ authorization object against which
2066 the client's x509 distinguished name will validated. This object is
2067 only resolved at time of use, so can be deleted and recreated on the
2068 fly while the VNC server is active. If missing, it will default
2069 to denying access.
2071 @item sasl
2073 Require that the client use SASL to authenticate with the VNC server.
2074 The exact choice of authentication method used is controlled from the
2075 system / user's SASL configuration file for the 'qemu' service. This
2076 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
2077 unprivileged user, an environment variable SASL_CONF_PATH can be used
2078 to make it search alternate locations for the service config.
2079 While some SASL auth methods can also provide data encryption (eg GSSAPI),
2080 it is recommended that SASL always be combined with the 'tls' and
2081 'x509' settings to enable use of SSL and server certificates. This
2082 ensures a data encryption preventing compromise of authentication
2083 credentials. See the @ref{vnc_security} section for details on using
2084 SASL authentication.
2086 @item sasl-authz=@var{ID}
2088 Provides the ID of the QAuthZ authorization object against which
2089 the client's SASL username will validated. This object is
2090 only resolved at time of use, so can be deleted and recreated on the
2091 fly while the VNC server is active. If missing, it will default
2092 to denying access.
2094 @item acl
2096 Legacy method for enabling authorization of clients against the
2097 x509 distinguished name and SASL username. It results in the creation
2098 of two @code{authz-list} objects with IDs of @code{vnc.username} and
2099 @code{vnc.x509dname}. The rules for these objects must be configured
2100 with the HMP ACL commands.
2102 This option is deprecated and should no longer be used. The new
2103 @option{sasl-authz} and @option{tls-authz} options are a
2104 replacement.
2106 @item lossy
2108 Enable lossy compression methods (gradient, JPEG, ...). If this
2109 option is set, VNC client may receive lossy framebuffer updates
2110 depending on its encoding settings. Enabling this option can save
2111 a lot of bandwidth at the expense of quality.
2113 @item non-adaptive
2115 Disable adaptive encodings. Adaptive encodings are enabled by default.
2116 An adaptive encoding will try to detect frequently updated screen regions,
2117 and send updates in these regions using a lossy encoding (like JPEG).
2118 This can be really helpful to save bandwidth when playing videos. Disabling
2119 adaptive encodings restores the original static behavior of encodings
2120 like Tight.
2122 @item share=[allow-exclusive|force-shared|ignore]
2124 Set display sharing policy. 'allow-exclusive' allows clients to ask
2125 for exclusive access. As suggested by the rfb spec this is
2126 implemented by dropping other connections. Connecting multiple
2127 clients in parallel requires all clients asking for a shared session
2128 (vncviewer: -shared switch). This is the default. 'force-shared'
2129 disables exclusive client access. Useful for shared desktop sessions,
2130 where you don't want someone forgetting specify -shared disconnect
2131 everybody else. 'ignore' completely ignores the shared flag and
2132 allows everybody connect unconditionally. Doesn't conform to the rfb
2133 spec but is traditional QEMU behavior.
2135 @item key-delay-ms
2137 Set keyboard delay, for key down and key up events, in milliseconds.
2138 Default is 10. Keyboards are low-bandwidth devices, so this slowdown
2139 can help the device and guest to keep up and not lose events in case
2140 events are arriving in bulk. Possible causes for the latter are flaky
2141 network connections, or scripts for automated testing.
2143 @item audiodev=@var{audiodev}
2145 Use the specified @var{audiodev} when the VNC client requests audio
2146 transmission. When not using an -audiodev argument, this option must
2147 be omitted, otherwise is must be present and specify a valid audiodev.
2149 @end table
2150 ETEXI
2152 STEXI
2153 @end table
2154 ETEXI
2155 ARCHHEADING(, QEMU_ARCH_I386)
2157 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
2158 STEXI
2159 @table @option
2160 ETEXI
2162 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
2163 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
2164 QEMU_ARCH_I386)
2165 STEXI
2166 @item -win2k-hack
2167 @findex -win2k-hack
2168 Use it when installing Windows 2000 to avoid a disk full bug. After
2169 Windows 2000 is installed, you no longer need this option (this option
2170 slows down the IDE transfers).
2171 ETEXI
2173 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
2174 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
2175 QEMU_ARCH_I386)
2176 STEXI
2177 @item -no-fd-bootchk
2178 @findex -no-fd-bootchk
2179 Disable boot signature checking for floppy disks in BIOS. May
2180 be needed to boot from old floppy disks.
2181 ETEXI
2183 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
2184 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2185 STEXI
2186 @item -no-acpi
2187 @findex -no-acpi
2188 Disable ACPI (Advanced Configuration and Power Interface) support. Use
2189 it if your guest OS complains about ACPI problems (PC target machine
2190 only).
2191 ETEXI
2193 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
2194 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
2195 STEXI
2196 @item -no-hpet
2197 @findex -no-hpet
2198 Disable HPET support.
2199 ETEXI
2201 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
2202 "-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"
2203 " ACPI table description\n", QEMU_ARCH_I386)
2204 STEXI
2205 @item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
2206 @findex -acpitable
2207 Add ACPI table with specified header fields and context from specified files.
2208 For file=, take whole ACPI table from the specified files, including all
2209 ACPI headers (possible overridden by other options).
2210 For data=, only data
2211 portion of the table is used, all header information is specified in the
2212 command line.
2213 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
2214 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
2215 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
2216 spec.
2217 ETEXI
2219 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2220 "-smbios file=binary\n"
2221 " load SMBIOS entry from binary file\n"
2222 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2223 " [,uefi=on|off]\n"
2224 " specify SMBIOS type 0 fields\n"
2225 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2226 " [,uuid=uuid][,sku=str][,family=str]\n"
2227 " specify SMBIOS type 1 fields\n"
2228 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2229 " [,asset=str][,location=str]\n"
2230 " specify SMBIOS type 2 fields\n"
2231 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2232 " [,sku=str]\n"
2233 " specify SMBIOS type 3 fields\n"
2234 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2235 " [,asset=str][,part=str]\n"
2236 " specify SMBIOS type 4 fields\n"
2237 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
2238 " [,asset=str][,part=str][,speed=%d]\n"
2239 " specify SMBIOS type 17 fields\n",
2240 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2241 STEXI
2242 @item -smbios file=@var{binary}
2243 @findex -smbios
2244 Load SMBIOS entry from binary file.
2246 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
2247 Specify SMBIOS type 0 fields
2249 @item -smbios type=1[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,uuid=@var{uuid}][,sku=@var{str}][,family=@var{str}]
2250 Specify SMBIOS type 1 fields
2252 @item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}]
2253 Specify SMBIOS type 2 fields
2255 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
2256 Specify SMBIOS type 3 fields
2258 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
2259 Specify SMBIOS type 4 fields
2261 @item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}]
2262 Specify SMBIOS type 17 fields
2263 ETEXI
2265 STEXI
2266 @end table
2267 ETEXI
2268 DEFHEADING()
2270 DEFHEADING(Network options:)
2271 STEXI
2272 @table @option
2273 ETEXI
2275 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
2276 #ifdef CONFIG_SLIRP
2277 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
2278 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2279 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
2280 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
2281 " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
2282 #ifndef _WIN32
2283 "[,smb=dir[,smbserver=addr]]\n"
2284 #endif
2285 " configure a user mode network backend with ID 'str',\n"
2286 " its DHCP server and optional services\n"
2287 #endif
2288 #ifdef _WIN32
2289 "-netdev tap,id=str,ifname=name\n"
2290 " configure a host TAP network backend with ID 'str'\n"
2291 #else
2292 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
2293 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
2294 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
2295 " [,poll-us=n]\n"
2296 " configure a host TAP network backend with ID 'str'\n"
2297 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2298 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2299 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2300 " to deconfigure it\n"
2301 " use '[down]script=no' to disable script execution\n"
2302 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2303 " configure it\n"
2304 " use 'fd=h' to connect to an already opened TAP interface\n"
2305 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
2306 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
2307 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
2308 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2309 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
2310 " use vhost=on to enable experimental in kernel accelerator\n"
2311 " (only has effect for virtio guests which use MSIX)\n"
2312 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
2313 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
2314 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
2315 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
2316 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
2317 " spent on busy polling for vhost net\n"
2318 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2319 " configure a host TAP network backend with ID 'str' that is\n"
2320 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2321 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
2322 #endif
2323 #ifdef __linux__
2324 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2325 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
2326 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
2327 " [,rxcookie=rxcookie][,offset=offset]\n"
2328 " configure a network backend with ID 'str' connected to\n"
2329 " an Ethernet over L2TPv3 pseudowire.\n"
2330 " Linux kernel 3.3+ as well as most routers can talk\n"
2331 " L2TPv3. This transport allows connecting a VM to a VM,\n"
2332 " VM to a router and even VM to Host. It is a nearly-universal\n"
2333 " standard (RFC3391). Note - this implementation uses static\n"
2334 " pre-configured tunnels (same as the Linux kernel).\n"
2335 " use 'src=' to specify source address\n"
2336 " use 'dst=' to specify destination address\n"
2337 " use 'udp=on' to specify udp encapsulation\n"
2338 " use 'srcport=' to specify source udp port\n"
2339 " use 'dstport=' to specify destination udp port\n"
2340 " use 'ipv6=on' to force v6\n"
2341 " L2TPv3 uses cookies to prevent misconfiguration as\n"
2342 " well as a weak security measure\n"
2343 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
2344 " use 'txcookie=0x012345678' to specify a txcookie\n"
2345 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2346 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2347 " use 'pincounter=on' to work around broken counter handling in peer\n"
2348 " use 'offset=X' to add an extra offset between header and data\n"
2349 #endif
2350 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2351 " configure a network backend to connect to another network\n"
2352 " using a socket connection\n"
2353 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2354 " configure a network backend to connect to a multicast maddr and port\n"
2355 " use 'localaddr=addr' to specify the host address to send packets from\n"
2356 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2357 " configure a network backend to connect to another network\n"
2358 " using an UDP tunnel\n"
2359 #ifdef CONFIG_VDE
2360 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2361 " configure a network backend to connect to port 'n' of a vde switch\n"
2362 " running on host and listening for incoming connections on 'socketpath'.\n"
2363 " Use group 'groupname' and mode 'octalmode' to change default\n"
2364 " ownership and permissions for communication port.\n"
2365 #endif
2366 #ifdef CONFIG_NETMAP
2367 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
2368 " attach to the existing netmap-enabled network interface 'name', or to a\n"
2369 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2370 " netmap device, defaults to '/dev/netmap')\n"
2371 #endif
2372 #ifdef CONFIG_POSIX
2373 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2374 " configure a vhost-user network, backed by a chardev 'dev'\n"
2375 #endif
2376 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
2377 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
2378 DEF("nic", HAS_ARG, QEMU_OPTION_nic,
2379 "-nic [tap|bridge|"
2380 #ifdef CONFIG_SLIRP
2381 "user|"
2382 #endif
2383 #ifdef __linux__
2384 "l2tpv3|"
2385 #endif
2386 #ifdef CONFIG_VDE
2387 "vde|"
2388 #endif
2389 #ifdef CONFIG_NETMAP
2390 "netmap|"
2391 #endif
2392 #ifdef CONFIG_POSIX
2393 "vhost-user|"
2394 #endif
2395 "socket][,option][,...][mac=macaddr]\n"
2396 " initialize an on-board / default host NIC (using MAC address\n"
2397 " macaddr) and connect it to the given host network backend\n"
2398 "-nic none use it alone to have zero network devices (the default is to\n"
2399 " provided a 'user' network connection)\n",
2400 QEMU_ARCH_ALL)
2401 DEF("net", HAS_ARG, QEMU_OPTION_net,
2402 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2403 " configure or create an on-board (or machine default) NIC and\n"
2404 " connect it to hub 0 (please use -nic unless you need a hub)\n"
2405 "-net ["
2406 #ifdef CONFIG_SLIRP
2407 "user|"
2408 #endif
2409 "tap|"
2410 "bridge|"
2411 #ifdef CONFIG_VDE
2412 "vde|"
2413 #endif
2414 #ifdef CONFIG_NETMAP
2415 "netmap|"
2416 #endif
2417 "socket][,option][,option][,...]\n"
2418 " old way to initialize a host network interface\n"
2419 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2420 STEXI
2421 @item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2422 @findex -nic
2423 This option is a shortcut for configuring both the on-board (default) guest
2424 NIC hardware and the host network backend in one go. The host backend options
2425 are the same as with the corresponding @option{-netdev} options below.
2426 The guest NIC model can be set with @option{model=@var{modelname}}.
2427 Use @option{model=help} to list the available device types.
2428 The hardware MAC address can be set with @option{mac=@var{macaddr}}.
2430 The following two example do exactly the same, to show how @option{-nic} can
2431 be used to shorten the command line length (note that the e1000 is the default
2432 on i386, so the @option{model=e1000} parameter could even be omitted here, too):
2433 @example
2434 @value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2435 @value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2436 @end example
2438 @item -nic none
2439 Indicate that no network devices should be configured. It is used to override
2440 the default configuration (default NIC with ``user'' host network backend)
2441 which is activated if no other networking options are provided.
2443 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
2444 @findex -netdev
2445 Configure user mode host network backend which requires no administrator
2446 privilege to run. Valid options are:
2448 @table @option
2449 @item id=@var{id}
2450 Assign symbolic name for use in monitor commands.
2452 @item ipv4=on|off and ipv6=on|off
2453 Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2454 both protocols are enabled.
2456 @item net=@var{addr}[/@var{mask}]
2457 Set IP network address the guest will see. Optionally specify the netmask,
2458 either in the form a.b.c.d or as number of valid top-most bits. Default is
2459 10.0.2.0/24.
2461 @item host=@var{addr}
2462 Specify the guest-visible address of the host. Default is the 2nd IP in the
2463 guest network, i.e. x.x.x.2.
2465 @item ipv6-net=@var{addr}[/@var{int}]
2466 Set IPv6 network address the guest will see (default is fec0::/64). The
2467 network prefix is given in the usual hexadecimal IPv6 address
2468 notation. The prefix size is optional, and is given as the number of
2469 valid top-most bits (default is 64).
2471 @item ipv6-host=@var{addr}
2472 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2473 the guest network, i.e. xxxx::2.
2475 @item restrict=on|off
2476 If this option is enabled, the guest will be isolated, i.e. it will not be
2477 able to contact the host and no guest IP packets will be routed over the host
2478 to the outside. This option does not affect any explicitly set forwarding rules.
2480 @item hostname=@var{name}
2481 Specifies the client hostname reported by the built-in DHCP server.
2483 @item dhcpstart=@var{addr}
2484 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
2485 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
2487 @item dns=@var{addr}
2488 Specify the guest-visible address of the virtual nameserver. The address must
2489 be different from the host address. Default is the 3rd IP in the guest network,
2490 i.e. x.x.x.3.
2492 @item ipv6-dns=@var{addr}
2493 Specify the guest-visible address of the IPv6 virtual nameserver. The address
2494 must be different from the host address. Default is the 3rd IP in the guest
2495 network, i.e. xxxx::3.
2497 @item dnssearch=@var{domain}
2498 Provides an entry for the domain-search list sent by the built-in
2499 DHCP server. More than one domain suffix can be transmitted by specifying
2500 this option multiple times. If supported, this will cause the guest to
2501 automatically try to append the given domain suffix(es) in case a domain name
2502 can not be resolved.
2504 Example:
2505 @example
2506 @value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2507 @end example
2509 @item domainname=@var{domain}
2510 Specifies the client domain name reported by the built-in DHCP server.
2512 @item tftp=@var{dir}
2513 When using the user mode network stack, activate a built-in TFTP
2514 server. The files in @var{dir} will be exposed as the root of a TFTP server.
2515 The TFTP client on the guest must be configured in binary mode (use the command
2516 @code{bin} of the Unix TFTP client).
2518 @item tftp-server-name=@var{name}
2519 In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
2520 66). This can be used to advise the guest to load boot files or configurations
2521 from a different server than the host address.
2523 @item bootfile=@var{file}
2524 When using the user mode network stack, broadcast @var{file} as the BOOTP
2525 filename. In conjunction with @option{tftp}, this can be used to network boot
2526 a guest from a local directory.
2528 Example (using pxelinux):
2529 @example
2530 @value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \
2531 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2532 @end example
2534 @item smb=@var{dir}[,smbserver=@var{addr}]
2535 When using the user mode network stack, activate a built-in SMB
2536 server so that Windows OSes can access to the host files in @file{@var{dir}}
2537 transparently. The IP address of the SMB server can be set to @var{addr}. By
2538 default the 4th IP in the guest network is used, i.e. x.x.x.4.
2540 In the guest Windows OS, the line:
2541 @example
2542 10.0.2.4 smbserver
2543 @end example
2544 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2545 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2547 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2549 Note that a SAMBA server must be installed on the host OS.
2551 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
2552 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2553 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2554 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
2555 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2556 be bound to a specific host interface. If no connection type is set, TCP is
2557 used. This option can be given multiple times.
2559 For example, to redirect host X11 connection from screen 1 to guest
2560 screen 0, use the following:
2562 @example
2563 # on the host
2564 @value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2565 # this host xterm should open in the guest X11 server
2566 xterm -display :1
2567 @end example
2569 To redirect telnet connections from host port 5555 to telnet port on
2570 the guest, use the following:
2572 @example
2573 # on the host
2574 @value{qemu_system} -nic user,hostfwd=tcp::5555-:23
2575 telnet localhost 5555
2576 @end example
2578 Then when you use on the host @code{telnet localhost 5555}, you
2579 connect to the guest telnet server.
2581 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
2582 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
2583 Forward guest TCP connections to the IP address @var{server} on port @var{port}
2584 to the character device @var{dev} or to a program executed by @var{cmd:command}
2585 which gets spawned for each connection. This option can be given multiple times.
2587 You can either use a chardev directly and have that one used throughout QEMU's
2588 lifetime, like in the following example:
2590 @example
2591 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2592 # the guest accesses it
2593 @value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2594 @end example
2596 Or you can execute a command on every TCP connection established by the guest,
2597 so that QEMU behaves similar to an inetd process for that virtual server:
2599 @example
2600 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2601 # and connect the TCP stream to its stdin/stdout
2602 @value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2603 @end example
2605 @end table
2607 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2608 Configure a host TAP network backend with ID @var{id}.
2610 Use the network script @var{file} to configure it and the network script
2611 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
2612 automatically provides one. The default network configure script is
2613 @file{/etc/qemu-ifup} and the default network deconfigure script is
2614 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2615 to disable script execution.
2617 If running QEMU as an unprivileged user, use the network helper
2618 @var{helper} to configure the TAP interface and attach it to the bridge.
2619 The default network helper executable is @file{/path/to/qemu-bridge-helper}
2620 and the default bridge device is @file{br0}.
2622 @option{fd}=@var{h} can be used to specify the handle of an already
2623 opened host TAP interface.
2625 Examples:
2627 @example
2628 #launch a QEMU instance with the default network script
2629 @value{qemu_system} linux.img -nic tap
2630 @end example
2632 @example
2633 #launch a QEMU instance with two NICs, each one connected
2634 #to a TAP device
2635 @value{qemu_system} linux.img \
2636 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2637 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2638 @end example
2640 @example
2641 #launch a QEMU instance with the default network helper to
2642 #connect a TAP device to bridge br0
2643 @value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \
2644 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2645 @end example
2647 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
2648 Connect a host TAP network interface to a host bridge device.
2650 Use the network helper @var{helper} to configure the TAP interface and
2651 attach it to the bridge. The default network helper executable is
2652 @file{/path/to/qemu-bridge-helper} and the default bridge
2653 device is @file{br0}.
2655 Examples:
2657 @example
2658 #launch a QEMU instance with the default network helper to
2659 #connect a TAP device to bridge br0
2660 @value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2661 @end example
2663 @example
2664 #launch a QEMU instance with the default network helper to
2665 #connect a TAP device to bridge qemubr0
2666 @value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2667 @end example
2669 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
2671 This host network backend can be used to connect the guest's network to
2672 another QEMU virtual machine using a TCP socket connection. If @option{listen}
2673 is specified, QEMU waits for incoming connections on @var{port}
2674 (@var{host} is optional). @option{connect} is used to connect to
2675 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2676 specifies an already opened TCP socket.
2678 Example:
2679 @example
2680 # launch a first QEMU instance
2681 @value{qemu_system} linux.img \
2682 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2683 -netdev socket,id=n1,listen=:1234
2684 # connect the network of this instance to the network of the first instance
2685 @value{qemu_system} linux.img \
2686 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2687 -netdev socket,id=n2,connect=127.0.0.1:1234
2688 @end example
2690 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
2692 Configure a socket host network backend to share the guest's network traffic
2693 with another QEMU virtual machines using a UDP multicast socket, effectively
2694 making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
2695 NOTES:
2696 @enumerate
2697 @item
2698 Several QEMU can be running on different hosts and share same bus (assuming
2699 correct multicast setup for these hosts).
2700 @item
2701 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2702 @url{http://user-mode-linux.sf.net}.
2703 @item
2704 Use @option{fd=h} to specify an already opened UDP multicast socket.
2705 @end enumerate
2707 Example:
2708 @example
2709 # launch one QEMU instance
2710 @value{qemu_system} linux.img \
2711 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2712 -netdev socket,id=n1,mcast=230.0.0.1:1234
2713 # launch another QEMU instance on same "bus"
2714 @value{qemu_system} linux.img \
2715 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2716 -netdev socket,id=n2,mcast=230.0.0.1:1234
2717 # launch yet another QEMU instance on same "bus"
2718 @value{qemu_system} linux.img \
2719 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
2720 -netdev socket,id=n3,mcast=230.0.0.1:1234
2721 @end example
2723 Example (User Mode Linux compat.):
2724 @example
2725 # launch QEMU instance (note mcast address selected is UML's default)
2726 @value{qemu_system} linux.img \
2727 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2728 -netdev socket,id=n1,mcast=239.192.168.1:1102
2729 # launch UML
2730 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2731 @end example
2733 Example (send packets from host's 1.2.3.4):
2734 @example
2735 @value{qemu_system} linux.img \
2736 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2737 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2738 @end example
2740 @item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
2741 Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
2742 popular protocol to transport Ethernet (and other Layer 2) data frames between
2743 two systems. It is present in routers, firewalls and the Linux kernel
2744 (from version 3.3 onwards).
2746 This transport allows a VM to communicate to another VM, router or firewall directly.
2748 @table @option
2749 @item src=@var{srcaddr}
2750 source address (mandatory)
2751 @item dst=@var{dstaddr}
2752 destination address (mandatory)
2753 @item udp
2754 select udp encapsulation (default is ip).
2755 @item srcport=@var{srcport}
2756 source udp port.
2757 @item dstport=@var{dstport}
2758 destination udp port.
2759 @item ipv6
2760 force v6, otherwise defaults to v4.
2761 @item rxcookie=@var{rxcookie}
2762 @itemx txcookie=@var{txcookie}
2763 Cookies are a weak form of security in the l2tpv3 specification.
2764 Their function is mostly to prevent misconfiguration. By default they are 32
2765 bit.
2766 @item cookie64
2767 Set cookie size to 64 bit instead of the default 32
2768 @item counter=off
2769 Force a 'cut-down' L2TPv3 with no counter as in
2770 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2771 @item pincounter=on
2772 Work around broken counter handling in peer. This may also help on
2773 networks which have packet reorder.
2774 @item offset=@var{offset}
2775 Add an extra offset between header and data
2776 @end table
2778 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2779 on the remote Linux host 1.2.3.4:
2780 @example
2781 # Setup tunnel on linux host using raw ip as encapsulation
2782 # on 1.2.3.4
2783 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2784 encap udp udp_sport 16384 udp_dport 16384
2785 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2786 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2787 ifconfig vmtunnel0 mtu 1500
2788 ifconfig vmtunnel0 up
2789 brctl addif br-lan vmtunnel0
2792 # on 4.3.2.1
2793 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2795 @value{qemu_system} linux.img -device e1000,netdev=n1 \
2796 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2798 @end example
2800 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2801 Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
2802 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2803 and MODE @var{octalmode} to change default ownership and permissions for
2804 communication port. This option is only available if QEMU has been compiled
2805 with vde support enabled.
2807 Example:
2808 @example
2809 # launch vde switch
2810 vde_switch -F -sock /tmp/myswitch
2811 # launch QEMU instance
2812 @value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch
2813 @end example
2815 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2817 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2818 be a unix domain socket backed one. The vhost-user uses a specifically defined
2819 protocol to pass vhost ioctl replacement messages to an application on the other
2820 end of the socket. On non-MSIX guests, the feature can be forced with
2821 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2822 be created for multiqueue vhost-user.
2824 Example:
2825 @example
2826 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2827 -numa node,memdev=mem \
2828 -chardev socket,id=chr0,path=/path/to/socket \
2829 -netdev type=vhost-user,id=net0,chardev=chr0 \
2830 -device virtio-net-pci,netdev=net0
2831 @end example
2833 @item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
2835 Create a hub port on the emulated hub with ID @var{hubid}.
2837 The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
2838 single netdev. Alternatively, you can also connect the hubport to another
2839 netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
2841 @item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
2842 @findex -net
2843 Legacy option to configure or create an on-board (or machine default) Network
2844 Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2845 the default hub), or to the netdev @var{nd}.
2846 The NIC is an e1000 by default on the PC target. Optionally, the MAC address
2847 can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
2848 only), and a @var{name} can be assigned for use in monitor commands.
2849 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2850 that the card should have; this option currently only affects virtio cards; set
2851 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2852 NIC is created. QEMU can emulate several different models of network card.
2853 Use @code{-net nic,model=help} for a list of available devices for your target.
2855 @item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
2856 Configure a host network backend (with the options corresponding to the same
2857 @option{-netdev} option) and connect it to the emulated hub 0 (the default
2858 hub). Use @var{name} to specify the name of the hub port.
2859 ETEXI
2861 STEXI
2862 @end table
2863 ETEXI
2864 DEFHEADING()
2866 DEFHEADING(Character device options:)
2868 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
2869 "-chardev help\n"
2870 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2871 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2872 " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n"
2873 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
2874 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n"
2875 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
2876 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
2877 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
2878 " [,logfile=PATH][,logappend=on|off]\n"
2879 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2880 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
2881 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2882 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2883 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2884 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2885 #ifdef _WIN32
2886 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2887 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2888 #else
2889 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2890 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
2891 #endif
2892 #ifdef CONFIG_BRLAPI
2893 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2894 #endif
2895 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2896 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2897 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2898 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2899 #endif
2900 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2901 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2902 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2903 #endif
2904 #if defined(CONFIG_SPICE)
2905 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2906 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2907 #endif
2908 , QEMU_ARCH_ALL
2911 STEXI
2913 The general form of a character device option is:
2914 @table @option
2915 @item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
2916 @findex -chardev
2917 Backend is one of:
2918 @option{null},
2919 @option{socket},
2920 @option{udp},
2921 @option{msmouse},
2922 @option{vc},
2923 @option{ringbuf},
2924 @option{file},
2925 @option{pipe},
2926 @option{console},
2927 @option{serial},
2928 @option{pty},
2929 @option{stdio},
2930 @option{braille},
2931 @option{tty},
2932 @option{parallel},
2933 @option{parport},
2934 @option{spicevmc},
2935 @option{spiceport}.
2936 The specific backend will determine the applicable options.
2938 Use @code{-chardev help} to print all available chardev backend types.
2940 All devices must have an id, which can be any string up to 127 characters long.
2941 It is used to uniquely identify this device in other command line directives.
2943 A character device may be used in multiplexing mode by multiple front-ends.
2944 Specify @option{mux=on} to enable this mode.
2945 A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2946 backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2947 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2948 create a multiplexer with your specified ID, and you can then configure multiple
2949 front ends to use that chardev ID for their input/output. Up to four different
2950 front ends can be connected to a single multiplexed chardev. (Without
2951 multiplexing enabled, a chardev can only be used by a single front end.)
2952 For instance you could use this to allow a single stdio chardev to be used by
2953 two serial ports and the QEMU monitor:
2955 @example
2956 -chardev stdio,mux=on,id=char0 \
2957 -mon chardev=char0,mode=readline \
2958 -serial chardev:char0 \
2959 -serial chardev:char0
2960 @end example
2962 You can have more than one multiplexer in a system configuration; for instance
2963 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2964 multiplexed between the QEMU monitor and a parallel port:
2966 @example
2967 -chardev stdio,mux=on,id=char0 \
2968 -mon chardev=char0,mode=readline \
2969 -parallel chardev:char0 \
2970 -chardev tcp,...,mux=on,id=char1 \
2971 -serial chardev:char1 \
2972 -serial chardev:char1
2973 @end example
2975 When you're using a multiplexed character device, some escape sequences are
2976 interpreted in the input. @xref{mux_keys, Keys in the character backend
2977 multiplexer}.
2979 Note that some other command line options may implicitly create multiplexed
2980 character backends; for instance @option{-serial mon:stdio} creates a
2981 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2982 and @option{-nographic} also multiplexes the console and the monitor to
2983 stdio.
2985 There is currently no support for multiplexing in the other direction
2986 (where a single QEMU front end takes input and output from multiple chardevs).
2988 Every backend supports the @option{logfile} option, which supplies the path
2989 to a file to record all data transmitted via the backend. The @option{logappend}
2990 option controls whether the log file will be truncated or appended to when
2991 opened.
2993 @end table
2995 The available backends are:
2997 @table @option
2998 @item -chardev null,id=@var{id}
2999 A void device. This device will not emit any data, and will drop any data it
3000 receives. The null backend does not take any options.
3002 @item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}]
3004 Create a two-way stream socket, which can be either a TCP or a unix socket. A
3005 unix socket will be created if @option{path} is specified. Behaviour is
3006 undefined if TCP options are specified for a unix socket.
3008 @option{server} specifies that the socket shall be a listening socket.
3010 @option{nowait} specifies that QEMU should not block waiting for a client to
3011 connect to a listening socket.
3013 @option{telnet} specifies that traffic on the socket should interpret telnet
3014 escape sequences.
3016 @option{websocket} specifies that the socket uses WebSocket protocol for
3017 communication.
3019 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
3020 the remote end goes away. qemu will delay this many seconds and then attempt
3021 to reconnect. Zero disables reconnecting, and is the default.
3023 @option{tls-creds} requests enablement of the TLS protocol for encryption,
3024 and specifies the id of the TLS credentials to use for the handshake. The
3025 credentials must be previously created with the @option{-object tls-creds}
3026 argument.
3028 @option{tls-auth} provides the ID of the QAuthZ authorization object against
3029 which the client's x509 distinguished name will be validated. This object is
3030 only resolved at time of use, so can be deleted and recreated on the fly
3031 while the chardev server is active. If missing, it will default to denying
3032 access.
3034 TCP and unix socket options are given below:
3036 @table @option
3038 @item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
3040 @option{host} for a listening socket specifies the local address to be bound.
3041 For a connecting socket species the remote host to connect to. @option{host} is
3042 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
3044 @option{port} for a listening socket specifies the local port to be bound. For a
3045 connecting socket specifies the port on the remote host to connect to.
3046 @option{port} can be given as either a port number or a service name.
3047 @option{port} is required.
3049 @option{to} is only relevant to listening sockets. If it is specified, and
3050 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
3051 to and including @option{to} until it succeeds. @option{to} must be specified
3052 as a port number.
3054 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
3055 If neither is specified the socket may use either protocol.
3057 @option{nodelay} disables the Nagle algorithm.
3059 @item unix options: path=@var{path}
3061 @option{path} specifies the local path of the unix socket. @option{path} is
3062 required.
3064 @end table
3066 @item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6]
3068 Sends all traffic from the guest to a remote host over UDP.
3070 @option{host} specifies the remote host to connect to. If not specified it
3071 defaults to @code{localhost}.
3073 @option{port} specifies the port on the remote host to connect to. @option{port}
3074 is required.
3076 @option{localaddr} specifies the local address to bind to. If not specified it
3077 defaults to @code{0.0.0.0}.
3079 @option{localport} specifies the local port to bind to. If not specified any
3080 available local port will be used.
3082 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
3083 If neither is specified the device may use either protocol.
3085 @item -chardev msmouse,id=@var{id}
3087 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
3088 take any options.
3090 @item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]]
3092 Connect to a QEMU text console. @option{vc} may optionally be given a specific
3093 size.
3095 @option{width} and @option{height} specify the width and height respectively of
3096 the console, in pixels.
3098 @option{cols} and @option{rows} specify that the console be sized to fit a text
3099 console with the given dimensions.
3101 @item -chardev ringbuf,id=@var{id}[,size=@var{size}]
3103 Create a ring buffer with fixed size @option{size}.
3104 @var{size} must be a power of two and defaults to @code{64K}.
3106 @item -chardev file,id=@var{id},path=@var{path}
3108 Log all traffic received from the guest to a file.
3110 @option{path} specifies the path of the file to be opened. This file will be
3111 created if it does not already exist, and overwritten if it does. @option{path}
3112 is required.
3114 @item -chardev pipe,id=@var{id},path=@var{path}
3116 Create a two-way connection to the guest. The behaviour differs slightly between
3117 Windows hosts and other hosts:
3119 On Windows, a single duplex pipe will be created at
3120 @file{\\.pipe\@option{path}}.
3122 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
3123 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
3124 received by the guest. Data written by the guest can be read from
3125 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
3126 be present.
3128 @option{path} forms part of the pipe path as described above. @option{path} is
3129 required.
3131 @item -chardev console,id=@var{id}
3133 Send traffic from the guest to QEMU's standard output. @option{console} does not
3134 take any options.
3136 @option{console} is only available on Windows hosts.
3138 @item -chardev serial,id=@var{id},path=@option{path}
3140 Send traffic from the guest to a serial device on the host.
3142 On Unix hosts serial will actually accept any tty device,
3143 not only serial lines.
3145 @option{path} specifies the name of the serial device to open.
3147 @item -chardev pty,id=@var{id}
3149 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
3150 not take any options.
3152 @option{pty} is not available on Windows hosts.
3154 @item -chardev stdio,id=@var{id}[,signal=on|off]
3155 Connect to standard input and standard output of the QEMU process.
3157 @option{signal} controls if signals are enabled on the terminal, that includes
3158 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
3159 default, use @option{signal=off} to disable it.
3161 @item -chardev braille,id=@var{id}
3163 Connect to a local BrlAPI server. @option{braille} does not take any options.
3165 @item -chardev tty,id=@var{id},path=@var{path}
3167 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
3168 DragonFlyBSD hosts. It is an alias for @option{serial}.
3170 @option{path} specifies the path to the tty. @option{path} is required.
3172 @item -chardev parallel,id=@var{id},path=@var{path}
3173 @itemx -chardev parport,id=@var{id},path=@var{path}
3175 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
3177 Connect to a local parallel port.
3179 @option{path} specifies the path to the parallel port device. @option{path} is
3180 required.
3182 @item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
3184 @option{spicevmc} is only available when spice support is built in.
3186 @option{debug} debug level for spicevmc
3188 @option{name} name of spice channel to connect to
3190 Connect to a spice virtual machine channel, such as vdiport.
3192 @item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
3194 @option{spiceport} is only available when spice support is built in.
3196 @option{debug} debug level for spicevmc
3198 @option{name} name of spice port to connect to
3200 Connect to a spice port, allowing a Spice client to handle the traffic
3201 identified by a name (preferably a fqdn).
3202 ETEXI
3204 STEXI
3205 @end table
3206 ETEXI
3207 DEFHEADING()
3209 #ifdef CONFIG_TPM
3210 DEFHEADING(TPM device options:)
3212 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3213 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3214 " use path to provide path to a character device; default is /dev/tpm0\n"
3215 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3216 " not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3217 "-tpmdev emulator,id=id,chardev=dev\n"
3218 " configure the TPM device using chardev backend\n",
3219 QEMU_ARCH_ALL)
3220 STEXI
3222 The general form of a TPM device option is:
3223 @table @option
3225 @item -tpmdev @var{backend},id=@var{id}[,@var{options}]
3226 @findex -tpmdev
3228 The specific backend type will determine the applicable options.
3229 The @code{-tpmdev} option creates the TPM backend and requires a
3230 @code{-device} option that specifies the TPM frontend interface model.
3232 Use @code{-tpmdev help} to print all available TPM backend types.
3234 @end table
3236 The available backends are:
3238 @table @option
3240 @item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
3242 (Linux-host only) Enable access to the host's TPM using the passthrough
3243 driver.
3245 @option{path} specifies the path to the host's TPM device, i.e., on
3246 a Linux host this would be @code{/dev/tpm0}.
3247 @option{path} is optional and by default @code{/dev/tpm0} is used.
3249 @option{cancel-path} specifies the path to the host TPM device's sysfs
3250 entry allowing for cancellation of an ongoing TPM command.
3251 @option{cancel-path} is optional and by default QEMU will search for the
3252 sysfs entry to use.
3254 Some notes about using the host's TPM with the passthrough driver:
3256 The TPM device accessed by the passthrough driver must not be
3257 used by any other application on the host.
3259 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3260 the VM's firmware (BIOS/UEFI) will not be able to initialize the
3261 TPM again and may therefore not show a TPM-specific menu that would
3262 otherwise allow the user to configure the TPM, e.g., allow the user to
3263 enable/disable or activate/deactivate the TPM.
3264 Further, if TPM ownership is released from within a VM then the host's TPM
3265 will get disabled and deactivated. To enable and activate the
3266 TPM again afterwards, the host has to be rebooted and the user is
3267 required to enter the firmware's menu to enable and activate the TPM.
3268 If the TPM is left disabled and/or deactivated most TPM commands will fail.
3270 To create a passthrough TPM use the following two options:
3271 @example
3272 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3273 @end example
3274 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3275 @code{tpmdev=tpm0} in the device option.
3277 @item -tpmdev emulator,id=@var{id},chardev=@var{dev}
3279 (Linux-host only) Enable access to a TPM emulator using Unix domain socket based
3280 chardev backend.
3282 @option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
3284 To create a TPM emulator backend device with chardev socket backend:
3285 @example
3287 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3289 @end example
3291 ETEXI
3293 STEXI
3294 @end table
3295 ETEXI
3296 DEFHEADING()
3298 #endif
3300 DEFHEADING(Linux/Multiboot boot specific:)
3301 STEXI
3303 When using these options, you can use a given Linux or Multiboot
3304 kernel without installing it in the disk image. It can be useful
3305 for easier testing of various kernels.
3307 @table @option
3308 ETEXI
3310 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3311 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3312 STEXI
3313 @item -kernel @var{bzImage}
3314 @findex -kernel
3315 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3316 or in multiboot format.
3317 ETEXI
3319 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3320 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3321 STEXI
3322 @item -append @var{cmdline}
3323 @findex -append
3324 Use @var{cmdline} as kernel command line
3325 ETEXI
3327 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3328 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3329 STEXI
3330 @item -initrd @var{file}
3331 @findex -initrd
3332 Use @var{file} as initial ram disk.
3334 @item -initrd "@var{file1} arg=foo,@var{file2}"
3336 This syntax is only available with multiboot.
3338 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3339 first module.
3340 ETEXI
3342 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3343 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
3344 STEXI
3345 @item -dtb @var{file}
3346 @findex -dtb
3347 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3348 on boot.
3349 ETEXI
3351 STEXI
3352 @end table
3353 ETEXI
3354 DEFHEADING()
3356 DEFHEADING(Debug/Expert options:)
3357 STEXI
3358 @table @option
3359 ETEXI
3361 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3362 "-fw_cfg [name=]<name>,file=<file>\n"
3363 " add named fw_cfg entry with contents from file\n"
3364 "-fw_cfg [name=]<name>,string=<str>\n"
3365 " add named fw_cfg entry with contents from string\n",
3366 QEMU_ARCH_ALL)
3367 STEXI
3369 @item -fw_cfg [name=]@var{name},file=@var{file}
3370 @findex -fw_cfg
3371 Add named fw_cfg entry with contents from file @var{file}.
3373 @item -fw_cfg [name=]@var{name},string=@var{str}
3374 Add named fw_cfg entry with contents from string @var{str}.
3376 The terminating NUL character of the contents of @var{str} will not be
3377 included as part of the fw_cfg item data. To insert contents with
3378 embedded NUL characters, you have to use the @var{file} parameter.
3380 The fw_cfg entries are passed by QEMU through to the guest.
3382 Example:
3383 @example
3384 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3385 @end example
3386 creates an fw_cfg entry named opt/com.mycompany/blob with contents
3387 from ./my_blob.bin.
3389 ETEXI
3391 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3392 "-serial dev redirect the serial port to char device 'dev'\n",
3393 QEMU_ARCH_ALL)
3394 STEXI
3395 @item -serial @var{dev}
3396 @findex -serial
3397 Redirect the virtual serial port to host character device
3398 @var{dev}. The default device is @code{vc} in graphical mode and
3399 @code{stdio} in non graphical mode.
3401 This option can be used several times to simulate up to 4 serial
3402 ports.
3404 Use @code{-serial none} to disable all serial ports.
3406 Available character devices are:
3407 @table @option
3408 @item vc[:@var{W}x@var{H}]
3409 Virtual console. Optionally, a width and height can be given in pixel with
3410 @example
3411 vc:800x600
3412 @end example
3413 It is also possible to specify width or height in characters:
3414 @example
3415 vc:80Cx24C
3416 @end example
3417 @item pty
3418 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3419 @item none
3420 No device is allocated.
3421 @item null
3422 void device
3423 @item chardev:@var{id}
3424 Use a named character device defined with the @code{-chardev} option.
3425 @item /dev/XXX
3426 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3427 parameters are set according to the emulated ones.
3428 @item /dev/parport@var{N}
3429 [Linux only, parallel port only] Use host parallel port
3430 @var{N}. Currently SPP and EPP parallel port features can be used.
3431 @item file:@var{filename}
3432 Write output to @var{filename}. No character can be read.
3433 @item stdio
3434 [Unix only] standard input/output
3435 @item pipe:@var{filename}
3436 name pipe @var{filename}
3437 @item COM@var{n}
3438 [Windows only] Use host serial port @var{n}
3439 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3440 This implements UDP Net Console.
3441 When @var{remote_host} or @var{src_ip} are not specified
3442 they default to @code{0.0.0.0}.
3443 When not using a specified @var{src_port} a random port is automatically chosen.
3445 If you just want a simple readonly console you can use @code{netcat} or
3446 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3447 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
3448 will appear in the netconsole session.
3450 If you plan to send characters back via netconsole or you want to stop
3451 and start QEMU a lot of times, you should have QEMU use the same
3452 source port each time by using something like @code{-serial
3453 udp::4555@@:4556} to QEMU. Another approach is to use a patched
3454 version of netcat which can listen to a TCP port and send and receive
3455 characters via udp. If you have a patched version of netcat which
3456 activates telnet remote echo and single char transfer, then you can
3457 use the following options to set up a netcat redirector to allow
3458 telnet on port 5555 to access the QEMU port.
3459 @table @code
3460 @item QEMU Options:
3461 -serial udp::4555@@:4556
3462 @item netcat options:
3463 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3464 @item telnet options:
3465 localhost 5555
3466 @end table
3468 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3469 The TCP Net Console has two modes of operation. It can send the serial
3470 I/O to a location or wait for a connection from a location. By default
3471 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3472 the @var{server} option QEMU will wait for a client socket application
3473 to connect to the port before continuing, unless the @code{nowait}
3474 option was specified. The @code{nodelay} option disables the Nagle buffering
3475 algorithm. The @code{reconnect} option only applies if @var{noserver} is
3476 set, if the connection goes down it will attempt to reconnect at the
3477 given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
3478 one TCP connection at a time is accepted. You can use @code{telnet} to
3479 connect to the corresponding character device.
3480 @table @code
3481 @item Example to send tcp console to 192.168.0.2 port 4444
3482 -serial tcp:192.168.0.2:4444
3483 @item Example to listen and wait on port 4444 for connection
3484 -serial tcp::4444,server
3485 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3486 -serial tcp:192.168.0.100:4444,server,nowait
3487 @end table
3489 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3490 The telnet protocol is used instead of raw tcp sockets. The options
3491 work the same as if you had specified @code{-serial tcp}. The
3492 difference is that the port acts like a telnet server or client using
3493 telnet option negotiation. This will also allow you to send the
3494 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3495 sequence. Typically in unix telnet you do it with Control-] and then
3496 type "send break" followed by pressing the enter key.
3498 @item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
3499 The WebSocket protocol is used instead of raw tcp socket. The port acts as
3500 a WebSocket server. Client mode is not supported.
3502 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3503 A unix domain socket is used instead of a tcp socket. The option works the
3504 same as if you had specified @code{-serial tcp} except the unix domain socket
3505 @var{path} is used for connections.
3507 @item mon:@var{dev_string}
3508 This is a special option to allow the monitor to be multiplexed onto
3509 another serial port. The monitor is accessed with key sequence of
3510 @key{Control-a} and then pressing @key{c}.
3511 @var{dev_string} should be any one of the serial devices specified
3512 above. An example to multiplex the monitor onto a telnet server
3513 listening on port 4444 would be:
3514 @table @code
3515 @item -serial mon:telnet::4444,server,nowait
3516 @end table
3517 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3518 QEMU any more but will be passed to the guest instead.
3520 @item braille
3521 Braille device. This will use BrlAPI to display the braille output on a real
3522 or fake device.
3524 @item msmouse
3525 Three button serial mouse. Configure the guest to use Microsoft protocol.
3526 @end table
3527 ETEXI
3529 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3530 "-parallel dev redirect the parallel port to char device 'dev'\n",
3531 QEMU_ARCH_ALL)
3532 STEXI
3533 @item -parallel @var{dev}
3534 @findex -parallel
3535 Redirect the virtual parallel port to host device @var{dev} (same
3536 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3537 be used to use hardware devices connected on the corresponding host
3538 parallel port.
3540 This option can be used several times to simulate up to 3 parallel
3541 ports.
3543 Use @code{-parallel none} to disable all parallel ports.
3544 ETEXI
3546 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3547 "-monitor dev redirect the monitor to char device 'dev'\n",
3548 QEMU_ARCH_ALL)
3549 STEXI
3550 @item -monitor @var{dev}
3551 @findex -monitor
3552 Redirect the monitor to host device @var{dev} (same devices as the
3553 serial port).
3554 The default device is @code{vc} in graphical mode and @code{stdio} in
3555 non graphical mode.
3556 Use @code{-monitor none} to disable the default monitor.
3557 ETEXI
3558 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3559 "-qmp dev like -monitor but opens in 'control' mode\n",
3560 QEMU_ARCH_ALL)
3561 STEXI
3562 @item -qmp @var{dev}
3563 @findex -qmp
3564 Like -monitor but opens in 'control' mode.
3565 ETEXI
3566 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3567 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3568 QEMU_ARCH_ALL)
3569 STEXI
3570 @item -qmp-pretty @var{dev}
3571 @findex -qmp-pretty
3572 Like -qmp but uses pretty JSON formatting.
3573 ETEXI
3575 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3576 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
3577 STEXI
3578 @item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
3579 @findex -mon
3580 Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3581 easing human reading and debugging.
3582 ETEXI
3584 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3585 "-debugcon dev redirect the debug console to char device 'dev'\n",
3586 QEMU_ARCH_ALL)
3587 STEXI
3588 @item -debugcon @var{dev}
3589 @findex -debugcon
3590 Redirect the debug console to host device @var{dev} (same devices as the
3591 serial port). The debug console is an I/O port which is typically port
3592 0xe9; writing to that I/O port sends output to this device.
3593 The default device is @code{vc} in graphical mode and @code{stdio} in
3594 non graphical mode.
3595 ETEXI
3597 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3598 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
3599 STEXI
3600 @item -pidfile @var{file}
3601 @findex -pidfile
3602 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3603 from a script.
3604 ETEXI
3606 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3607 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
3608 STEXI
3609 @item -singlestep
3610 @findex -singlestep
3611 Run the emulation in single step mode.
3612 ETEXI
3614 DEF("preconfig", 0, QEMU_OPTION_preconfig, \
3615 "--preconfig pause QEMU before machine is initialized (experimental)\n",
3616 QEMU_ARCH_ALL)
3617 STEXI
3618 @item --preconfig
3619 @findex --preconfig
3620 Pause QEMU for interactive configuration before the machine is created,
3621 which allows querying and configuring properties that will affect
3622 machine initialization. Use QMP command 'x-exit-preconfig' to exit
3623 the preconfig state and move to the next state (i.e. run guest if -S
3624 isn't used or pause the second time if -S is used). This option is
3625 experimental.
3626 ETEXI
3628 DEF("S", 0, QEMU_OPTION_S, \
3629 "-S freeze CPU at startup (use 'c' to start execution)\n",
3630 QEMU_ARCH_ALL)
3631 STEXI
3632 @item -S
3633 @findex -S
3634 Do not start CPU at startup (you must type 'c' in the monitor).
3635 ETEXI
3637 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3638 "-realtime [mlock=on|off]\n"
3639 " run qemu with realtime features\n"
3640 " mlock=on|off controls mlock support (default: on)\n",
3641 QEMU_ARCH_ALL)
3642 STEXI
3643 @item -realtime mlock=on|off
3644 @findex -realtime
3645 Run qemu with realtime features.
3646 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3647 (enabled by default).
3648 ETEXI
3650 DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
3651 "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
3652 " run qemu with overcommit hints\n"
3653 " mem-lock=on|off controls memory lock support (default: off)\n"
3654 " cpu-pm=on|off controls cpu power management (default: off)\n",
3655 QEMU_ARCH_ALL)
3656 STEXI
3657 @item -overcommit mem-lock=on|off
3658 @item -overcommit cpu-pm=on|off
3659 @findex -overcommit
3660 Run qemu with hints about host resource overcommit. The default is
3661 to assume that host overcommits all resources.
3663 Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3664 by default). This works when host memory is not overcommitted and reduces the
3665 worst-case latency for guest. This is equivalent to @option{realtime}.
3667 Guest ability to manage power state of host cpus (increasing latency for other
3668 processes on the same host cpu, but decreasing latency for guest) can be
3669 enabled via @option{cpu-pm=on} (disabled by default). This works best when
3670 host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3671 utilization will be incorrect, not taking into account guest idle time.
3672 ETEXI
3674 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3675 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
3676 STEXI
3677 @item -gdb @var{dev}
3678 @findex -gdb
3679 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3680 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3681 stdio are reasonable use case. The latter is allowing to start QEMU from
3682 within gdb and establish the connection via a pipe:
3683 @example
3684 (gdb) target remote | exec @value{qemu_system} -gdb stdio ...
3685 @end example
3686 ETEXI
3688 DEF("s", 0, QEMU_OPTION_s, \
3689 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3690 QEMU_ARCH_ALL)
3691 STEXI
3692 @item -s
3693 @findex -s
3694 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3695 (@pxref{gdb_usage}).
3696 ETEXI
3698 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3699 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
3700 QEMU_ARCH_ALL)
3701 STEXI
3702 @item -d @var{item1}[,...]
3703 @findex -d
3704 Enable logging of specified items. Use '-d help' for a list of log items.
3705 ETEXI
3707 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3708 "-D logfile output log to logfile (default stderr)\n",
3709 QEMU_ARCH_ALL)
3710 STEXI
3711 @item -D @var{logfile}
3712 @findex -D
3713 Output log in @var{logfile} instead of to stderr
3714 ETEXI
3716 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3717 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3718 QEMU_ARCH_ALL)
3719 STEXI
3720 @item -dfilter @var{range1}[,...]
3721 @findex -dfilter
3722 Filter debug output to that relevant to a range of target addresses. The filter
3723 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3724 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3725 addresses and sizes required. For example:
3726 @example
3727 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3728 @end example
3729 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3730 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3731 block starting at 0xffffffc00005f000.
3732 ETEXI
3734 DEF("seed", HAS_ARG, QEMU_OPTION_seed, \
3735 "-seed number seed the pseudo-random number generator\n",
3736 QEMU_ARCH_ALL)
3737 STEXI
3738 @item -seed @var{number}
3739 @findex -seed
3740 Force the guest to use a deterministic pseudo-random number generator, seeded
3741 with @var{number}. This does not affect crypto routines within the host.
3742 ETEXI
3744 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3745 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3746 QEMU_ARCH_ALL)
3747 STEXI
3748 @item -L @var{path}
3749 @findex -L
3750 Set the directory for the BIOS, VGA BIOS and keymaps.
3752 To list all the data directories, use @code{-L help}.
3753 ETEXI
3755 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3756 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
3757 STEXI
3758 @item -bios @var{file}
3759 @findex -bios
3760 Set the filename for the BIOS.
3761 ETEXI
3763 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3764 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3765 STEXI
3766 @item -enable-kvm
3767 @findex -enable-kvm
3768 Enable KVM full virtualization support. This option is only available
3769 if KVM support is enabled when compiling.
3770 ETEXI
3772 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3773 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
3774 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3775 "-xen-attach attach to existing xen domain\n"
3776 " libxl will use this when starting QEMU\n",
3777 QEMU_ARCH_ALL)
3778 DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3779 "-xen-domid-restrict restrict set of available xen operations\n"
3780 " to specified domain id. (Does not affect\n"
3781 " xenpv machine type).\n",
3782 QEMU_ARCH_ALL)
3783 STEXI
3784 @item -xen-domid @var{id}
3785 @findex -xen-domid
3786 Specify xen guest domain @var{id} (XEN only).
3787 @item -xen-attach
3788 @findex -xen-attach
3789 Attach to existing xen domain.
3790 libxl will use this when starting QEMU (XEN only).
3791 @findex -xen-domid-restrict
3792 Restrict set of available xen operations to specified domain id (XEN only).
3793 ETEXI
3795 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3796 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
3797 STEXI
3798 @item -no-reboot
3799 @findex -no-reboot
3800 Exit instead of rebooting.
3801 ETEXI
3803 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3804 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
3805 STEXI
3806 @item -no-shutdown
3807 @findex -no-shutdown
3808 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3809 This allows for instance switching to monitor to commit changes to the
3810 disk image.
3811 ETEXI
3813 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3814 "-loadvm [tag|id]\n" \
3815 " start right away with a saved state (loadvm in monitor)\n",
3816 QEMU_ARCH_ALL)
3817 STEXI
3818 @item -loadvm @var{file}
3819 @findex -loadvm
3820 Start right away with a saved state (@code{loadvm} in monitor)
3821 ETEXI
3823 #ifndef _WIN32
3824 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3825 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3826 #endif
3827 STEXI
3828 @item -daemonize
3829 @findex -daemonize
3830 Daemonize the QEMU process after initialization. QEMU will not detach from
3831 standard IO until it is ready to receive connections on any of its devices.
3832 This option is a useful way for external programs to launch QEMU without having
3833 to cope with initialization race conditions.
3834 ETEXI
3836 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3837 "-option-rom rom load a file, rom, into the option ROM space\n",
3838 QEMU_ARCH_ALL)
3839 STEXI
3840 @item -option-rom @var{file}
3841 @findex -option-rom
3842 Load the contents of @var{file} as an option ROM.
3843 This option is useful to load things like EtherBoot.
3844 ETEXI
3846 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3847 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3848 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3849 QEMU_ARCH_ALL)
3851 STEXI
3853 @item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
3854 @findex -rtc
3855 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3856 UTC or local time, respectively. @code{localtime} is required for correct date in
3857 MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
3858 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3860 By default the RTC is driven by the host system time. This allows using of the
3861 RTC as accurate reference clock inside the guest, specifically if the host
3862 time is smoothly following an accurate external reference clock, e.g. via NTP.
3863 If you want to isolate the guest time from the host, you can set @option{clock}
3864 to @code{rt} instead, which provides a host monotonic clock if host support it.
3865 To even prevent the RTC from progressing during suspension, you can set @option{clock}
3866 to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
3867 icount mode in order to preserve determinism; however, note that in icount mode
3868 the speed of the virtual clock is variable and can in general differ from the
3869 host clock.
3871 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3872 specifically with Windows' ACPI HAL. This option will try to figure out how
3873 many timer interrupts were not processed by the Windows guest and will
3874 re-inject them.
3875 ETEXI
3877 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
3878 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
3879 " enable virtual instruction counter with 2^N clock ticks per\n" \
3880 " instruction, enable aligning the host and virtual clocks\n" \
3881 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
3882 STEXI
3883 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
3884 @findex -icount
3885 Enable virtual instruction counter. The virtual cpu will execute one
3886 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
3887 then the virtual cpu speed will be automatically adjusted to keep virtual
3888 time within a few seconds of real time.
3890 When the virtual cpu is sleeping, the virtual time will advance at default
3891 speed unless @option{sleep=on|off} is specified.
3892 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3893 instantly whenever the virtual cpu goes to sleep mode and will not advance
3894 if no timer is enabled. This behavior give deterministic execution times from
3895 the guest point of view.
3897 Note that while this option can give deterministic behavior, it does not
3898 provide cycle accurate emulation. Modern CPUs contain superscalar out of
3899 order cores with complex cache hierarchies. The number of instructions
3900 executed often has little or no correlation with actual performance.
3902 @option{align=on} will activate the delay algorithm which will try
3903 to synchronise the host clock and the virtual clock. The goal is to
3904 have a guest running at the real frequency imposed by the shift option.
3905 Whenever the guest clock is behind the host clock and if
3906 @option{align=on} is specified then we print a message to the user
3907 to inform about the delay.
3908 Currently this option does not work when @option{shift} is @code{auto}.
3909 Note: The sync algorithm will work for those shift values for which
3910 the guest clock runs ahead of the host clock. Typically this happens
3911 when the shift value is high (how high depends on the host machine).
3913 When @option{rr} option is specified deterministic record/replay is enabled.
3914 Replay log is written into @var{filename} file in record mode and
3915 read from this file in replay mode.
3917 Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3918 at the start of execution recording. In replay mode this option is used
3919 to load the initial VM state.
3920 ETEXI
3922 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3923 "-watchdog model\n" \
3924 " enable virtual hardware watchdog [default=none]\n",
3925 QEMU_ARCH_ALL)
3926 STEXI
3927 @item -watchdog @var{model}
3928 @findex -watchdog
3929 Create a virtual hardware watchdog device. Once enabled (by a guest
3930 action), the watchdog must be periodically polled by an agent inside
3931 the guest or else the guest will be restarted. Choose a model for
3932 which your guest has drivers.
3934 The @var{model} is the model of hardware watchdog to emulate. Use
3935 @code{-watchdog help} to list available hardware models. Only one
3936 watchdog can be enabled for a guest.
3938 The following models may be available:
3939 @table @option
3940 @item ib700
3941 iBASE 700 is a very simple ISA watchdog with a single timer.
3942 @item i6300esb
3943 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3944 dual-timer watchdog.
3945 @item diag288
3946 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3947 (currently KVM only).
3948 @end table
3949 ETEXI
3951 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3952 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
3953 " action when watchdog fires [default=reset]\n",
3954 QEMU_ARCH_ALL)
3955 STEXI
3956 @item -watchdog-action @var{action}
3957 @findex -watchdog-action
3959 The @var{action} controls what QEMU will do when the watchdog timer
3960 expires.
3961 The default is
3962 @code{reset} (forcefully reset the guest).
3963 Other possible actions are:
3964 @code{shutdown} (attempt to gracefully shutdown the guest),
3965 @code{poweroff} (forcefully poweroff the guest),
3966 @code{inject-nmi} (inject a NMI into the guest),
3967 @code{pause} (pause the guest),
3968 @code{debug} (print a debug message and continue), or
3969 @code{none} (do nothing).
3971 Note that the @code{shutdown} action requires that the guest responds
3972 to ACPI signals, which it may not be able to do in the sort of
3973 situations where the watchdog would have expired, and thus
3974 @code{-watchdog-action shutdown} is not recommended for production use.
3976 Examples:
3978 @table @code
3979 @item -watchdog i6300esb -watchdog-action pause
3980 @itemx -watchdog ib700
3981 @end table
3982 ETEXI
3984 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
3985 "-echr chr set terminal escape character instead of ctrl-a\n",
3986 QEMU_ARCH_ALL)
3987 STEXI
3989 @item -echr @var{numeric_ascii_value}
3990 @findex -echr
3991 Change the escape character used for switching to the monitor when using
3992 monitor and serial sharing. The default is @code{0x01} when using the
3993 @code{-nographic} option. @code{0x01} is equal to pressing
3994 @code{Control-a}. You can select a different character from the ascii
3995 control keys where 1 through 26 map to Control-a through Control-z. For
3996 instance you could use the either of the following to change the escape
3997 character to Control-t.
3998 @table @code
3999 @item -echr 0x14
4000 @itemx -echr 20
4001 @end table
4002 ETEXI
4004 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
4005 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
4006 STEXI
4007 @item -show-cursor
4008 @findex -show-cursor
4009 Show cursor.
4010 ETEXI
4012 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
4013 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
4014 STEXI
4015 @item -tb-size @var{n}
4016 @findex -tb-size
4017 Set TCG translation block cache size. Deprecated, use @samp{-accel tcg,tb-size=@var{n}}
4018 instead.
4019 ETEXI
4021 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
4022 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
4023 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
4024 "-incoming unix:socketpath\n" \
4025 " prepare for incoming migration, listen on\n" \
4026 " specified protocol and socket address\n" \
4027 "-incoming fd:fd\n" \
4028 "-incoming exec:cmdline\n" \
4029 " accept incoming migration on given file descriptor\n" \
4030 " or from given external command\n" \
4031 "-incoming defer\n" \
4032 " wait for the URI to be specified via migrate_incoming\n",
4033 QEMU_ARCH_ALL)
4034 STEXI
4035 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
4036 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
4037 @findex -incoming
4038 Prepare for incoming migration, listen on a given tcp port.
4040 @item -incoming unix:@var{socketpath}
4041 Prepare for incoming migration, listen on a given unix socket.
4043 @item -incoming fd:@var{fd}
4044 Accept incoming migration from a given filedescriptor.
4046 @item -incoming exec:@var{cmdline}
4047 Accept incoming migration as an output from specified external command.
4049 @item -incoming defer
4050 Wait for the URI to be specified via migrate_incoming. The monitor can
4051 be used to change settings (such as migration parameters) prior to issuing
4052 the migrate_incoming to allow the migration to begin.
4053 ETEXI
4055 DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
4056 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
4057 STEXI
4058 @item -only-migratable
4059 @findex -only-migratable
4060 Only allow migratable devices. Devices will not be allowed to enter an
4061 unmigratable state.
4062 ETEXI
4064 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
4065 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
4066 STEXI
4067 @item -nodefaults
4068 @findex -nodefaults
4069 Don't create default devices. Normally, QEMU sets the default devices like serial
4070 port, parallel port, virtual console, monitor device, VGA adapter, floppy and
4071 CD-ROM drive and others. The @code{-nodefaults} option will disable all those
4072 default devices.
4073 ETEXI
4075 #ifndef _WIN32
4076 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
4077 "-chroot dir chroot to dir just before starting the VM\n",
4078 QEMU_ARCH_ALL)
4079 #endif
4080 STEXI
4081 @item -chroot @var{dir}
4082 @findex -chroot
4083 Immediately before starting guest execution, chroot to the specified
4084 directory. Especially useful in combination with -runas.
4085 ETEXI
4087 #ifndef _WIN32
4088 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
4089 "-runas user change to user id user just before starting the VM\n" \
4090 " user can be numeric uid:gid instead\n",
4091 QEMU_ARCH_ALL)
4092 #endif
4093 STEXI
4094 @item -runas @var{user}
4095 @findex -runas
4096 Immediately before starting guest execution, drop root privileges, switching
4097 to the specified user.
4098 ETEXI
4100 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
4101 "-prom-env variable=value\n"
4102 " set OpenBIOS nvram variables\n",
4103 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
4104 STEXI
4105 @item -prom-env @var{variable}=@var{value}
4106 @findex -prom-env
4107 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
4108 ETEXI
4109 DEF("semihosting", 0, QEMU_OPTION_semihosting,
4110 "-semihosting semihosting mode\n",
4111 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
4112 QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2)
4113 STEXI
4114 @item -semihosting
4115 @findex -semihosting
4116 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
4117 ETEXI
4118 DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
4119 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \
4120 " semihosting configuration\n",
4121 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
4122 QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2)
4123 STEXI
4124 @item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]
4125 @findex -semihosting-config
4126 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only).
4127 @table @option
4128 @item target=@code{native|gdb|auto}
4129 Defines where the semihosting calls will be addressed, to QEMU (@code{native})
4130 or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
4131 during debug sessions and @code{native} otherwise.
4132 @item chardev=@var{str1}
4133 Send the output to a chardev backend output for native or auto output when not in gdb
4134 @item arg=@var{str1},arg=@var{str2},...
4135 Allows the user to pass input arguments, and can be used multiple times to build
4136 up a list. The old-style @code{-kernel}/@code{-append} method of passing a
4137 command line is still supported for backward compatibility. If both the
4138 @code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
4139 specified, the former is passed to semihosting as it always takes precedence.
4140 @end table
4141 ETEXI
4142 DEF("old-param", 0, QEMU_OPTION_old_param,
4143 "-old-param old param mode\n", QEMU_ARCH_ARM)
4144 STEXI
4145 @item -old-param
4146 @findex -old-param (ARM)
4147 Old param mode (ARM only).
4148 ETEXI
4150 DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
4151 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
4152 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
4153 " Enable seccomp mode 2 system call filter (default 'off').\n" \
4154 " use 'obsolete' to allow obsolete system calls that are provided\n" \
4155 " by the kernel, but typically no longer used by modern\n" \
4156 " C library implementations.\n" \
4157 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
4158 " its privileges by blacklisting all set*uid|gid system calls.\n" \
4159 " The value 'children' will deny set*uid|gid system calls for\n" \
4160 " main QEMU process but will allow forks and execves to run unprivileged\n" \
4161 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
4162 " blacklisting *fork and execve\n" \
4163 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
4164 QEMU_ARCH_ALL)
4165 STEXI
4166 @item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
4167 @findex -sandbox
4168 Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
4169 disable it. The default is 'off'.
4170 @table @option
4171 @item obsolete=@var{string}
4172 Enable Obsolete system calls
4173 @item elevateprivileges=@var{string}
4174 Disable set*uid|gid system calls
4175 @item spawn=@var{string}
4176 Disable *fork and execve
4177 @item resourcecontrol=@var{string}
4178 Disable process affinity and schedular priority
4179 @end table
4180 ETEXI
4182 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
4183 "-readconfig <file>\n", QEMU_ARCH_ALL)
4184 STEXI
4185 @item -readconfig @var{file}
4186 @findex -readconfig
4187 Read device configuration from @var{file}. This approach is useful when you want to spawn
4188 QEMU process with many command line options but you don't want to exceed the command line
4189 character limit.
4190 ETEXI
4191 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
4192 "-writeconfig <file>\n"
4193 " read/write config file\n", QEMU_ARCH_ALL)
4194 STEXI
4195 @item -writeconfig @var{file}
4196 @findex -writeconfig
4197 Write device configuration to @var{file}. The @var{file} can be either filename to save
4198 command line and device configuration into file or dash @code{-}) character to print the
4199 output to stdout. This can be later used as input file for @code{-readconfig} option.
4200 ETEXI
4202 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
4203 "-no-user-config\n"
4204 " do not load default user-provided config files at startup\n",
4205 QEMU_ARCH_ALL)
4206 STEXI
4207 @item -no-user-config
4208 @findex -no-user-config
4209 The @code{-no-user-config} option makes QEMU not load any of the user-provided
4210 config files on @var{sysconfdir}.
4211 ETEXI
4213 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
4214 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
4215 " specify tracing options\n",
4216 QEMU_ARCH_ALL)
4217 STEXI
4218 HXCOMM This line is not accurate, as some sub-options are backend-specific but
4219 HXCOMM HX does not support conditional compilation of text.
4220 @item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
4221 @findex -trace
4222 @include qemu-option-trace.texi
4223 ETEXI
4224 DEF("plugin", HAS_ARG, QEMU_OPTION_plugin,
4225 "-plugin [file=]<file>[,arg=<string>]\n"
4226 " load a plugin\n",
4227 QEMU_ARCH_ALL)
4228 STEXI
4229 @item -plugin file=@var{file}[,arg=@var{string}]
4230 @findex -plugin
4232 Load a plugin.
4234 @table @option
4235 @item file=@var{file}
4236 Load the given plugin from a shared library file.
4237 @item arg=@var{string}
4238 Argument string passed to the plugin. (Can be given multiple times.)
4239 @end table
4240 ETEXI
4242 HXCOMM Internal use
4243 DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
4244 DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
4246 #ifdef __linux__
4247 DEF("enable-fips", 0, QEMU_OPTION_enablefips,
4248 "-enable-fips enable FIPS 140-2 compliance\n",
4249 QEMU_ARCH_ALL)
4250 #endif
4251 STEXI
4252 @item -enable-fips
4253 @findex -enable-fips
4254 Enable FIPS 140-2 compliance mode.
4255 ETEXI
4257 HXCOMM Deprecated by -accel tcg
4258 DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
4260 DEF("msg", HAS_ARG, QEMU_OPTION_msg,
4261 "-msg timestamp[=on|off]\n"
4262 " control error message format\n"
4263 " timestamp=on enables timestamps (default: off)\n",
4264 QEMU_ARCH_ALL)
4265 STEXI
4266 @item -msg timestamp[=on|off]
4267 @findex -msg
4268 Control error message format.
4269 @table @option
4270 @item timestamp=on|off
4271 Prefix messages with a timestamp. Default is off.
4272 @end table
4273 ETEXI
4275 DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
4276 "-dump-vmstate <file>\n"
4277 " Output vmstate information in JSON format to file.\n"
4278 " Use the scripts/vmstate-static-checker.py file to\n"
4279 " check for possible regressions in migration code\n"
4280 " by comparing two such vmstate dumps.\n",
4281 QEMU_ARCH_ALL)
4282 STEXI
4283 @item -dump-vmstate @var{file}
4284 @findex -dump-vmstate
4285 Dump json-encoded vmstate information for current machine type to file
4286 in @var{file}
4287 ETEXI
4289 DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
4290 "-enable-sync-profile\n"
4291 " enable synchronization profiling\n",
4292 QEMU_ARCH_ALL)
4293 STEXI
4294 @item -enable-sync-profile
4295 @findex -enable-sync-profile
4296 Enable synchronization profiling.
4297 ETEXI
4299 STEXI
4300 @end table
4301 ETEXI
4302 DEFHEADING()
4304 DEFHEADING(Generic object creation:)
4305 STEXI
4306 @table @option
4307 ETEXI
4309 DEF("object", HAS_ARG, QEMU_OPTION_object,
4310 "-object TYPENAME[,PROP1=VALUE1,...]\n"
4311 " create a new object of type TYPENAME setting properties\n"
4312 " in the order they are specified. Note that the 'id'\n"
4313 " property must be set. These objects are placed in the\n"
4314 " '/objects' path.\n",
4315 QEMU_ARCH_ALL)
4316 STEXI
4317 @item -object @var{typename}[,@var{prop1}=@var{value1},...]
4318 @findex -object
4319 Create a new object of type @var{typename} setting properties
4320 in the order they are specified. Note that the 'id'
4321 property must be set. These objects are placed in the
4322 '/objects' path.
4324 @table @option
4326 @item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},align=@var{align}
4328 Creates a memory file backend object, which can be used to back
4329 the guest RAM with huge pages.
4331 The @option{id} parameter is a unique ID that will be used to reference this
4332 memory region when configuring the @option{-numa} argument.
4334 The @option{size} option provides the size of the memory region, and accepts
4335 common suffixes, eg @option{500M}.
4337 The @option{mem-path} provides the path to either a shared memory or huge page
4338 filesystem mount.
4340 The @option{share} boolean option determines whether the memory
4341 region is marked as private to QEMU, or shared. The latter allows
4342 a co-operating external process to access the QEMU memory region.
4344 The @option{share} is also required for pvrdma devices due to
4345 limitations in the RDMA API provided by Linux.
4347 Setting share=on might affect the ability to configure NUMA
4348 bindings for the memory backend under some circumstances, see
4349 Documentation/vm/numa_memory_policy.txt on the Linux kernel
4350 source tree for additional details.
4352 Setting the @option{discard-data} boolean option to @var{on}
4353 indicates that file contents can be destroyed when QEMU exits,
4354 to avoid unnecessarily flushing data to the backing file. Note
4355 that @option{discard-data} is only an optimization, and QEMU
4356 might not discard file contents if it aborts unexpectedly or is
4357 terminated using SIGKILL.
4359 The @option{merge} boolean option enables memory merge, also known as
4360 MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
4361 memory deduplication.
4363 Setting the @option{dump} boolean option to @var{off} excludes the memory from
4364 core dumps. This feature is also known as MADV_DONTDUMP.
4366 The @option{prealloc} boolean option enables memory preallocation.
4368 The @option{host-nodes} option binds the memory range to a list of NUMA host
4369 nodes.
4371 The @option{policy} option sets the NUMA policy to one of the following values:
4373 @table @option
4374 @item @var{default}
4375 default host policy
4377 @item @var{preferred}
4378 prefer the given host node list for allocation
4380 @item @var{bind}
4381 restrict memory allocation to the given host node list
4383 @item @var{interleave}
4384 interleave memory allocations across the given host node list
4385 @end table
4387 The @option{align} option specifies the base address alignment when
4388 QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
4389 @option{2M}. Some backend store specified by @option{mem-path}
4390 requires an alignment different than the default one used by QEMU, eg
4391 the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
4392 such cases, users can specify the required alignment via this option.
4394 The @option{pmem} option specifies whether the backing file specified
4395 by @option{mem-path} is in host persistent memory that can be accessed
4396 using the SNIA NVM programming model (e.g. Intel NVDIMM).
4397 If @option{pmem} is set to 'on', QEMU will take necessary operations to
4398 guarantee the persistence of its own writes to @option{mem-path}
4399 (e.g. in vNVDIMM label emulation and live migration).
4400 Also, we will map the backend-file with MAP_SYNC flag, which ensures the
4401 file metadata is in sync for @option{mem-path} in case of host crash
4402 or a power failure. MAP_SYNC requires support from both the host kernel
4403 (since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted
4404 with DAX option.
4406 @item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave}
4408 Creates a memory backend object, which can be used to back the guest RAM.
4409 Memory backend objects offer more control than the @option{-m} option that is
4410 traditionally used to define guest RAM. Please refer to
4411 @option{memory-backend-file} for a description of the options.
4413 @item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size}
4415 Creates an anonymous memory file backend object, which allows QEMU to
4416 share the memory with an external process (e.g. when using
4417 vhost-user). The memory is allocated with memfd and optional
4418 sealing. (Linux only)
4420 The @option{seal} option creates a sealed-file, that will block
4421 further resizing the memory ('on' by default).
4423 The @option{hugetlb} option specify the file to be created resides in
4424 the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
4425 the @option{hugetlb} option, the @option{hugetlbsize} option specify
4426 the hugetlb page size on systems that support multiple hugetlb page
4427 sizes (it must be a power of 2 value supported by the system).
4429 In some versions of Linux, the @option{hugetlb} option is incompatible
4430 with the @option{seal} option (requires at least Linux 4.16).
4432 Please refer to @option{memory-backend-file} for a description of the
4433 other options.
4435 The @option{share} boolean option is @var{on} by default with memfd.
4437 @item -object rng-builtin,id=@var{id}
4439 Creates a random number generator backend which obtains entropy from
4440 QEMU builtin functions. The @option{id} parameter is a unique ID that
4441 will be used to reference this entropy backend from the @option{virtio-rng}
4442 device. By default, the @option{virtio-rng} device uses this RNG backend.
4444 @item -object rng-random,id=@var{id},filename=@var{/dev/random}
4446 Creates a random number generator backend which obtains entropy from
4447 a device on the host. The @option{id} parameter is a unique ID that
4448 will be used to reference this entropy backend from the @option{virtio-rng}
4449 device. The @option{filename} parameter specifies which file to obtain
4450 entropy from and if omitted defaults to @option{/dev/urandom}.
4452 @item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4454 Creates a random number generator backend which obtains entropy from
4455 an external daemon running on the host. The @option{id} parameter is
4456 a unique ID that will be used to reference this entropy backend from
4457 the @option{virtio-rng} device. The @option{chardev} parameter is
4458 the unique ID of a character device backend that provides the connection
4459 to the RNG daemon.
4461 @item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4463 Creates a TLS anonymous credentials object, which can be used to provide
4464 TLS support on network backends. The @option{id} parameter is a unique
4465 ID which network backends will use to access the credentials. The
4466 @option{endpoint} is either @option{server} or @option{client} depending
4467 on whether the QEMU network backend that uses the credentials will be
4468 acting as a client or as a server. If @option{verify-peer} is enabled
4469 (the default) then once the handshake is completed, the peer credentials
4470 will be verified, though this is a no-op for anonymous credentials.
4472 The @var{dir} parameter tells QEMU where to find the credential
4473 files. For server endpoints, this directory may contain a file
4474 @var{dh-params.pem} providing diffie-hellman parameters to use
4475 for the TLS server. If the file is missing, QEMU will generate
4476 a set of DH parameters at startup. This is a computationally
4477 expensive operation that consumes random pool entropy, so it is
4478 recommended that a persistent set of parameters be generated
4479 upfront and saved.
4481 @item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}]
4483 Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide
4484 TLS support on network backends. The @option{id} parameter is a unique
4485 ID which network backends will use to access the credentials. The
4486 @option{endpoint} is either @option{server} or @option{client} depending
4487 on whether the QEMU network backend that uses the credentials will be
4488 acting as a client or as a server. For clients only, @option{username}
4489 is the username which will be sent to the server. If omitted
4490 it defaults to ``qemu''.
4492 The @var{dir} parameter tells QEMU where to find the keys file.
4493 It is called ``@var{dir}/keys.psk'' and contains ``username:key''
4494 pairs. This file can most easily be created using the GnuTLS
4495 @code{psktool} program.
4497 For server endpoints, @var{dir} may also contain a file
4498 @var{dh-params.pem} providing diffie-hellman parameters to use
4499 for the TLS server. If the file is missing, QEMU will generate
4500 a set of DH parameters at startup. This is a computationally
4501 expensive operation that consumes random pool entropy, so it is
4502 recommended that a persistent set of parameters be generated
4503 up front and saved.
4505 @item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id}
4507 Creates a TLS anonymous credentials object, which can be used to provide
4508 TLS support on network backends. The @option{id} parameter is a unique
4509 ID which network backends will use to access the credentials. The
4510 @option{endpoint} is either @option{server} or @option{client} depending
4511 on whether the QEMU network backend that uses the credentials will be
4512 acting as a client or as a server. If @option{verify-peer} is enabled
4513 (the default) then once the handshake is completed, the peer credentials
4514 will be verified. With x509 certificates, this implies that the clients
4515 must be provided with valid client certificates too.
4517 The @var{dir} parameter tells QEMU where to find the credential
4518 files. For server endpoints, this directory may contain a file
4519 @var{dh-params.pem} providing diffie-hellman parameters to use
4520 for the TLS server. If the file is missing, QEMU will generate
4521 a set of DH parameters at startup. This is a computationally
4522 expensive operation that consumes random pool entropy, so it is
4523 recommended that a persistent set of parameters be generated
4524 upfront and saved.
4526 For x509 certificate credentials the directory will contain further files
4527 providing the x509 certificates. The certificates must be stored
4528 in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4529 @var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4530 @var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4532 For the @var{server-key.pem} and @var{client-key.pem} files which
4533 contain sensitive private keys, it is possible to use an encrypted
4534 version by providing the @var{passwordid} parameter. This provides
4535 the ID of a previously created @code{secret} object containing the
4536 password for decryption.
4538 The @var{priority} parameter allows to override the global default
4539 priority used by gnutls. This can be useful if the system administrator
4540 needs to use a weaker set of crypto priorities for QEMU without
4541 potentially forcing the weakness onto all applications. Or conversely
4542 if one wants wants a stronger default for QEMU than for all other
4543 applications, they can do this through this parameter. Its format is
4544 a gnutls priority string as described at
4545 @url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
4547 @item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
4549 Interval @var{t} can't be 0, this filter batches the packet delivery: all
4550 packets arriving in a given interval on netdev @var{netdevid} are delayed
4551 until the end of the interval. Interval is in microseconds.
4552 @option{status} is optional that indicate whether the netfilter is
4553 on (enabled) or off (disabled), the default status for netfilter will be 'on'.
4555 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4557 @option{all}: the filter is attached both to the receive and the transmit
4558 queue of the netdev (default).
4560 @option{rx}: the filter is attached to the receive queue of the netdev,
4561 where it will receive packets sent to the netdev.
4563 @option{tx}: the filter is attached to the transmit queue of the netdev,
4564 where it will receive packets sent by the netdev.
4566 @item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
4568 filter-mirror on netdev @var{netdevid},mirror net packet to chardev@var{chardevid}, if it has the vnet_hdr_support flag, filter-mirror will mirror packet with vnet_hdr_len.
4570 @item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
4572 filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
4573 @var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4574 filter-redirector will redirect packet with vnet_hdr_len.
4575 Create a filter-redirector we need to differ outdev id from indev id, id can not
4576 be the same. we can just use indev or outdev, but at least one of indev or outdev
4577 need to be specified.
4579 @item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support]
4581 Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4582 secondary from primary to keep secondary tcp connection,and rewrite
4583 tcp packet to primary from secondary make tcp packet can be handled by
4584 client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
4586 usage:
4587 colo secondary:
4588 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4589 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4590 -object filter-rewriter,id=rew0,netdev=hn0,queue=all
4592 @item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
4594 Dump the network traffic on netdev @var{dev} to the file specified by
4595 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4596 The file format is libpcap, so it can be analyzed with tools such as tcpdump
4597 or Wireshark.
4599 @item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid},iothread=@var{id}[,vnet_hdr_support][,notify_dev=@var{id}]
4601 Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4602 secondary packet. If the packets are same, we will output primary
4603 packet to outdev@var{chardevid}, else we will notify colo-frame
4604 do checkpoint and send primary packet to outdev@var{chardevid}.
4605 In order to improve efficiency, we need to put the task of comparison
4606 in another thread. If it has the vnet_hdr_support flag, colo compare
4607 will send/recv packet with vnet_hdr_len.
4608 If you want to use Xen COLO, will need the notify_dev to notify Xen
4609 colo-frame to do checkpoint.
4611 we must use it with the help of filter-mirror and filter-redirector.
4613 @example
4615 KVM COLO
4617 primary:
4618 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4619 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4620 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4621 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4622 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4623 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4624 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4625 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4626 -object iothread,id=iothread1
4627 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4628 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4629 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4630 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
4632 secondary:
4633 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4634 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4635 -chardev socket,id=red0,host=3.3.3.3,port=9003
4636 -chardev socket,id=red1,host=3.3.3.3,port=9004
4637 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4638 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4641 Xen COLO
4643 primary:
4644 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4645 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4646 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4647 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4648 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4649 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4650 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4651 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4652 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
4653 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4654 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4655 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4656 -object iothread,id=iothread1
4657 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
4659 secondary:
4660 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4661 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4662 -chardev socket,id=red0,host=3.3.3.3,port=9003
4663 -chardev socket,id=red1,host=3.3.3.3,port=9004
4664 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4665 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4667 @end example
4669 If you want to know the detail of above command line, you can read
4670 the colo-compare git log.
4672 @item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4674 Creates a cryptodev backend which executes crypto opreation from
4675 the QEMU cipher APIS. The @var{id} parameter is
4676 a unique ID that will be used to reference this cryptodev backend from
4677 the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4678 which specify the queue number of cryptodev backend, the default of
4679 @var{queues} is 1.
4681 @example
4683 # @value{qemu_system} \
4684 [...] \
4685 -object cryptodev-backend-builtin,id=cryptodev0 \
4686 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4687 [...]
4688 @end example
4690 @item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
4692 Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
4693 The @var{id} parameter is a unique ID that will be used to reference this
4694 cryptodev backend from the @option{virtio-crypto} device.
4695 The chardev should be a unix domain socket backed one. The vhost-user uses
4696 a specifically defined protocol to pass vhost ioctl replacement messages
4697 to an application on the other end of the socket.
4698 The @var{queues} parameter is optional, which specify the queue number
4699 of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
4701 @example
4703 # @value{qemu_system} \
4704 [...] \
4705 -chardev socket,id=chardev0,path=/path/to/socket \
4706 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4707 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4708 [...]
4709 @end example
4711 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4712 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4714 Defines a secret to store a password, encryption key, or some other sensitive
4715 data. The sensitive data can either be passed directly via the @var{data}
4716 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4717 parameter is insecure unless the sensitive data is encrypted.
4719 The sensitive data can be provided in raw format (the default), or base64.
4720 When encoded as JSON, the raw format only supports valid UTF-8 characters,
4721 so base64 is recommended for sending binary data. QEMU will convert from
4722 which ever format is provided to the format it needs internally. eg, an
4723 RBD password can be provided in raw format, even though it will be base64
4724 encoded when passed onto the RBD sever.
4726 For added protection, it is possible to encrypt the data associated with
4727 a secret using the AES-256-CBC cipher. Use of encryption is indicated
4728 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4729 parameter provides the ID of a previously defined secret that contains
4730 the AES-256 decryption key. This key should be 32-bytes long and be
4731 base64 encoded. The @var{iv} parameter provides the random initialization
4732 vector used for encryption of this particular secret and should be a
4733 base64 encrypted string of the 16-byte IV.
4735 The simplest (insecure) usage is to provide the secret inline
4737 @example
4739 # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw
4741 @end example
4743 The simplest secure usage is to provide the secret via a file
4745 # printf "letmein" > mypasswd.txt
4746 # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw
4748 For greater security, AES-256-CBC should be used. To illustrate usage,
4749 consider the openssl command line tool which can encrypt the data. Note
4750 that when encrypting, the plaintext must be padded to the cipher block
4751 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4753 First a master key needs to be created in base64 encoding:
4755 @example
4756 # openssl rand -base64 32 > key.b64
4757 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4758 @end example
4760 Each secret to be encrypted needs to have a random initialization vector
4761 generated. These do not need to be kept secret
4763 @example
4764 # openssl rand -base64 16 > iv.b64
4765 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4766 @end example
4768 The secret to be defined can now be encrypted, in this case we're
4769 telling openssl to base64 encode the result, but it could be left
4770 as raw bytes if desired.
4772 @example
4773 # SECRET=$(printf "letmein" |
4774 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4775 @end example
4777 When launching QEMU, create a master secret pointing to @code{key.b64}
4778 and specify that to be used to decrypt the user password. Pass the
4779 contents of @code{iv.b64} to the second secret
4781 @example
4782 # @value{qemu_system} \
4783 -object secret,id=secmaster0,format=base64,file=key.b64 \
4784 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4785 data=$SECRET,iv=$(<iv.b64)
4786 @end example
4788 @item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}]
4790 Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
4791 to provide the guest memory encryption support on AMD processors.
4793 When memory encryption is enabled, one of the physical address bit (aka the
4794 C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
4795 is used to provide the C-bit position. The C-bit position is Host family dependent
4796 hence user must provide this value. On EPYC, the value should be 47.
4798 When memory encryption is enabled, we loose certain bits in physical address space.
4799 The @option{reduced-phys-bits} is used to provide the number of bits we loose in
4800 physical address space. Similar to C-bit, the value is Host family dependent.
4801 On EPYC, the value should be 5.
4803 The @option{sev-device} provides the device file to use for communicating with
4804 the SEV firmware running inside AMD Secure Processor. The default device is
4805 '/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
4806 created by CCP driver.
4808 The @option{policy} provides the guest policy to be enforced by the SEV firmware
4809 and restrict what configuration and operational commands can be performed on this
4810 guest by the hypervisor. The policy should be provided by the guest owner and is
4811 bound to the guest and cannot be changed throughout the lifetime of the guest.
4812 The default is 0.
4814 If guest @option{policy} allows sharing the key with another SEV guest then
4815 @option{handle} can be use to provide handle of the guest from which to share
4816 the key.
4818 The @option{dh-cert-file} and @option{session-file} provides the guest owner's
4819 Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
4820 are used for establishing a cryptographic session with the guest owner to
4821 negotiate keys used for attestation. The file must be encoded in base64.
4823 e.g to launch a SEV guest
4824 @example
4825 # @value{qemu_system_x86} \
4826 ......
4827 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4828 -machine ...,memory-encryption=sev0
4829 .....
4831 @end example
4834 @item -object authz-simple,id=@var{id},identity=@var{string}
4836 Create an authorization object that will control access to network services.
4838 The @option{identity} parameter is identifies the user and its format
4839 depends on the network service that authorization object is associated
4840 with. For authorizing based on TLS x509 certificates, the identity must
4841 be the x509 distinguished name. Note that care must be taken to escape
4842 any commas in the distinguished name.
4844 An example authorization object to validate a x509 distinguished name
4845 would look like:
4846 @example
4847 # @value{qemu_system} \
4849 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
4851 @end example
4853 Note the use of quotes due to the x509 distinguished name containing
4854 whitespace, and escaping of ','.
4856 @item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no}
4858 Create an authorization object that will control access to network services.
4860 The @option{filename} parameter is the fully qualified path to a file
4861 containing the access control list rules in JSON format.
4863 An example set of rules that match against SASL usernames might look
4864 like:
4866 @example
4868 "rules": [
4869 @{ "match": "fred", "policy": "allow", "format": "exact" @},
4870 @{ "match": "bob", "policy": "allow", "format": "exact" @},
4871 @{ "match": "danb", "policy": "deny", "format": "glob" @},
4872 @{ "match": "dan*", "policy": "allow", "format": "exact" @},
4874 "policy": "deny"
4876 @end example
4878 When checking access the object will iterate over all the rules and
4879 the first rule to match will have its @option{policy} value returned
4880 as the result. If no rules match, then the default @option{policy}
4881 value is returned.
4883 The rules can either be an exact string match, or they can use the
4884 simple UNIX glob pattern matching to allow wildcards to be used.
4886 If @option{refresh} is set to true the file will be monitored
4887 and automatically reloaded whenever its content changes.
4889 As with the @code{authz-simple} object, the format of the identity
4890 strings being matched depends on the network service, but is usually
4891 a TLS x509 distinguished name, or a SASL username.
4893 An example authorization object to validate a SASL username
4894 would look like:
4895 @example
4896 # @value{qemu_system} \
4898 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
4900 @end example
4902 @item -object authz-pam,id=@var{id},service=@var{string}
4904 Create an authorization object that will control access to network services.
4906 The @option{service} parameter provides the name of a PAM service to use
4907 for authorization. It requires that a file @code{/etc/pam.d/@var{service}}
4908 exist to provide the configuration for the @code{account} subsystem.
4910 An example authorization object to validate a TLS x509 distinguished
4911 name would look like:
4913 @example
4914 # @value{qemu_system} \
4916 -object authz-pam,id=auth0,service=qemu-vnc
4918 @end example
4920 There would then be a corresponding config file for PAM at
4921 @code{/etc/pam.d/qemu-vnc} that contains:
4923 @example
4924 account requisite pam_listfile.so item=user sense=allow \
4925 file=/etc/qemu/vnc.allow
4926 @end example
4928 Finally the @code{/etc/qemu/vnc.allow} file would contain
4929 the list of x509 distingished names that are permitted
4930 access
4932 @example
4933 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4934 @end example
4936 @item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink}
4938 Creates a dedicated event loop thread that devices can be assigned to. This is
4939 known as an IOThread. By default device emulation happens in vCPU threads or
4940 the main event loop thread. This can become a scalability bottleneck.
4941 IOThreads allow device emulation and I/O to run on other host CPUs.
4943 The @option{id} parameter is a unique ID that will be used to reference this
4944 IOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be
4945 assigned to an IOThread. Note that not all devices support an
4946 @option{iothread} parameter.
4948 The @code{query-iothreads} QMP command lists IOThreads and reports their thread
4949 IDs so that the user can configure host CPU pinning/affinity.
4951 IOThreads use an adaptive polling algorithm to reduce event loop latency.
4952 Instead of entering a blocking system call to monitor file descriptors and then
4953 pay the cost of being woken up when an event occurs, the polling algorithm
4954 spins waiting for events for a short time. The algorithm's default parameters
4955 are suitable for many cases but can be adjusted based on knowledge of the
4956 workload and/or host device latency.
4958 The @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy
4959 wait for events. Polling can be disabled by setting this value to 0.
4961 The @option{poll-grow} parameter is the multiplier used to increase the polling
4962 time when the algorithm detects it is missing events due to not polling long
4963 enough.
4965 The @option{poll-shrink} parameter is the divisor used to decrease the polling
4966 time when the algorithm detects it is spending too long polling without
4967 encountering events.
4969 The polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}):
4971 @example
4972 (qemu) qom-set /objects/iothread1 poll-max-ns 100000
4973 @end example
4975 @end table
4977 ETEXI
4980 HXCOMM This is the last statement. Insert new options before this line!
4981 STEXI
4982 @end table
4983 ETEXI