docs: Roll -prom-env and -g target-specific info into qemu-options.hx
[qemu.git] / qemu-options.hx
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
8
9 DEFHEADING(Standard options:)
10 STEXI
11 @table @option
12 ETEXI
13
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
21
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
29
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.
51
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.
56
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.
62
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
103
104 HXCOMM Deprecated by -machine
105 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
106
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
114
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
150
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
173
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.
193
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.
201
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
207
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.
217
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
225
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.
230
231 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
232 if one node uses @samp{memdev}, all of them have to use it.
233
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'.
238
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
254
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.
265
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.
270
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.
275
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.
285
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.
291
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.
298
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
323
324 ETEXI
325
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
332
333 Add a file descriptor to an fd set.  Valid options are:
334
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
344
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
353
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
363
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.:
374
375 @example
376 @value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img
377 @end example
378
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}.
382
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
387
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.
408
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.
411
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.
418
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.
423
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.
427
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
436
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
440
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.
457
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:
461
462 @example
463 @value{qemu_system} -m 1G,slots=3,maxmem=4G
464 @end example
465
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
469
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
477
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
486
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.
498
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
505
506 The default is @code{en-us}.
507 ETEXI
508
509
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
520
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
587
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.
591
592 Valid global options are:
593
594 @table @option
595 @item id=@var{identifier}
596 Identifies the audio backend.
597
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).
601
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.
611
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.
616
617 @item in|out.frequency=@var{frequency}
618 Specify the @var{frequency} to use when using @var{fixed-settings}.
619 Default is 44100Hz.
620
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).
624
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}.
629
630 @item in|out.voices=@var{voices}
631 Specify the number of @var{voices} to use.  Default is 1.
632
633 @item in|out.buffer-length=@var{usecs}
634 Sets the size of the buffer in microseconds.
635
636 @end table
637
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.
641
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.
645
646 ALSA specific options are:
647
648 @table @option
649
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}.
653
654 @item in|out.period-length=@var{usecs}
655 Sets the period length in microseconds.
656
657 @item in|out.try-poll=on|off
658 Attempt to use poll mode with the device.  Default is on.
659
660 @item threshold=@var{threshold}
661 Threshold (in microseconds) when playback starts.  Default is 0.
662
663 @end table
664
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.
668
669 Core Audio specific options are:
670
671 @table @option
672
673 @item in|out.buffer-count=@var{count}
674 Sets the @var{count} of the buffers.
675
676 @end table
677
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.
681
682 DirectSound specific options are:
683
684 @table @option
685
686 @item latency=@var{usecs}
687 Add extra @var{usecs} microseconds latency to playback.  Default is
688 10000 (10 ms).
689
690 @end table
691
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.
695
696 OSS specific options are:
697
698 @table @option
699
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}.
703
704 @item in|out.buffer-count=@var{count}
705 Sets the @var{count} of the buffers.
706
707 @item in|out.try-poll=on|of
708 Attempt to use poll mode with the device.  Default is on.
709
710 @item try-mmap=on|off
711 Try using memory mapped device access.  Default is off.
712
713 @item exclusive=on|off
714 Open the device in exclusive mode (vmix won't work in this case).
715 Default is off.
716
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.
722
723 @end table
724
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.
728
729 PulseAudio specific options are:
730
731 @table @option
732
733 @item server=@var{server}
734 Sets the PulseAudio @var{server} to connect to.
735
736 @item in|out.name=@var{sink}
737 Use the specified source/sink for recording/playback.
738
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.
742
743 @end table
744
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.
749
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.
755
756 @item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
757 Creates a backend that writes audio to a WAV file.
758
759 Backend specific options are:
760
761 @table @option
762
763 @item path=@var{path}
764 Write recorded audio into the specified file.  Default is
765 @code{qemu.wav}.
766
767 @end table
768 ETEXI
769
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:
780
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
789
790 Note that Linux's i810_audio OSS kernel (for AC97) module might
791 require manually specifying clocking.
792
793 @example
794 modprobe i810_audio clocking=48000
795 @end example
796 ETEXI
797
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}.
812
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}]
815
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
820
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
824 it.
825
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
842
843 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
844
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.
848
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.
857
858 See the "lanserv/README.vm" file in the OpenIPMI library for more
859 details on the external interface.
860
861 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
862
863 Add a KCS IPMI interafce on the ISA bus.  This also adds a
864 corresponding ACPI and SMBIOS entries, if appropriate.
865
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
875
876 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
877
878 Like the KCS interface, but defines a BT interface.  The default port is
879 0xe4 and the default interrupt is 5.
880
881 ETEXI
882
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
899
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
908
909 STEXI
910 @end table
911 ETEXI
912 DEFHEADING()
913
914 DEFHEADING(Block device options:)
915 STEXI
916 @table @option
917 ETEXI
918
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
929
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
947
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.
957 ETEXI
958
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
969
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.
973
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).
978
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.
982
983 @table @option
984 @item Valid options for any block driver node:
985
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.
993
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.
999
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.
1016
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
1039
1040 @item Driver-specific options for @code{file}
1041
1042 This is the protocol-level block driver for accessing regular files.
1043
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
1058
1059 @item Driver-specific options for @code{raw}
1060
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}.
1063
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
1078
1079 @item Driver-specific options for @code{qcow2}
1080
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}.
1083
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)
1088
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.
1093
1094 @item lazy-refcounts
1095 Whether to enable the lazy refcounts feature (on/off; default is taken from the
1096 image file)
1097
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)
1101
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)
1107
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)
1112
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.
1117
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)
1121
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)
1126
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)
1130
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
1136
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
1146
1147 @item Driver-specific options for other drivers
1148 Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
1149
1150 @end table
1151
1152 ETEXI
1153
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
1171
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.
1175
1176 @option{-drive} accepts all options that are accepted by @option{-blockdev}. In
1177 addition, it knows the following options:
1178
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").
1184
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:
1209
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
1222
1223 The default mode is @option{cache=writeback}.
1224
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
1265
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.
1272
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.
1277
1278 When using the @option{-snapshot} option, unsafe caching is always used.
1279
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.
1283
1284 Instead of @option{-cdrom} you can use:
1285 @example
1286 @value{qemu_system} -drive file=file,index=2,media=cdrom
1287 @end example
1288
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
1297
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
1305
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
1310
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
1315
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
1321
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
1332
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
1341
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
1349
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
1357
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
1368
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)
1381
1382 STEXI
1383
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
1454
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
1467
1468 ETEXI
1469
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)
1477
1478 STEXI
1479
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
1485
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
1560
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)
1567
1568 STEXI
1569 @item -iscsi
1570 @findex -iscsi
1571 Configure iSCSI session parameters.
1572 ETEXI
1573
1574 STEXI
1575 @end table
1576 ETEXI
1577 DEFHEADING()
1578
1579 DEFHEADING(USB options:)
1580 STEXI
1581 @table @option
1582 ETEXI
1583
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
1595
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
1600
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}.
1605
1606 @table @option
1607
1608 @item mouse
1609 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1610
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.
1615
1616 @item braille
1617 Braille device.  This will use BrlAPI to display the braille output on a real
1618 or fake device.
1619
1620 @end table
1621 ETEXI
1622
1623 STEXI
1624 @end table
1625 ETEXI
1626 DEFHEADING()
1627
1628 DEFHEADING(Display options:)
1629 STEXI
1630 @table @option
1631 ETEXI
1632
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
1708
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
1724
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
1737
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
1747
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
1757
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
1765
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
1773
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
1797
1798 @table @option
1799
1800 @item port=<nr>
1801 Set the TCP port spice is listening on for plaintext channels.
1802
1803 @item addr=<addr>
1804 Set the IP address spice is listening on.  Default is any address.
1805
1806 @item ipv4
1807 @itemx ipv6
1808 @itemx unix
1809 Force using the specified IP version.
1810
1811 @item password=<secret>
1812 Set the password you need to authenticate.
1813
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.
1826
1827 @item disable-ticketing
1828 Allow client connects without authentication.
1829
1830 @item disable-copy-paste
1831 Disable copy paste between the client and the guest.
1832
1833 @item disable-agent-file-xfer
1834 Disable spice-vdagent based file-xfer between the client and the guest.
1835
1836 @item tls-port=<nr>
1837 Set the TCP port spice is listening on for encrypted channels.
1838
1839 @item x509-dir=<dir>
1840 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1841
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.
1848
1849 @item tls-ciphers=<list>
1850 Specify which ciphers to use.
1851
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.
1859
1860 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1861 Configure image compression (lossless).
1862 Default is auto_glz.
1863
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.
1868
1869 @item streaming-video=[off|all|filter]
1870 Configure video stream detection.  Default is off.
1871
1872 @item agent-mouse=[on|off]
1873 Enable/disable passing mouse events via vdagent.  Default is on.
1874
1875 @item playback-compression=[on|off]
1876 Enable/disable audio stream compression (using celt 0.5.1).  Default is on.
1877
1878 @item seamless-migration=[on|off]
1879 Enable/disable spice seamless migration. Default is off.
1880
1881 @item gl=[on|off]
1882 Enable/disable OpenGL context. Default is off.
1883
1884 @item rendernode=<file>
1885 DRM render node for OpenGL rendering. If not specified, it will pick
1886 the first available. (Since 2.9)
1887
1888 @end table
1889 ETEXI
1890
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
1899
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
1908
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
1949
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
1957
1958 DEF("g", HAS_ARG, 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
1966 For PPC the default is 800x600x32.
1967
1968 For SPARC with the TCX graphics device, the default is 1024x768x8 with the
1969 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
1970 of 1152x900x8 for people who wish to use OBP.
1971
1972 ETEXI
1973
1974 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1975     "-vnc <display>  shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
1976 STEXI
1977 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1978 @findex -vnc
1979 Normally, if QEMU is compiled with graphical window support, it displays
1980 output such as guest graphics, guest console, and the QEMU monitor in a
1981 window. With this option, you can have QEMU listen on VNC display
1982 @var{display} and redirect the VGA display over the VNC session. It is
1983 very useful to enable the usb tablet device when using this option
1984 (option @option{-device usb-tablet}). When using the VNC display, you
1985 must use the @option{-k} parameter to set the keyboard layout if you are
1986 not using en-us. Valid syntax for the @var{display} is
1987
1988 @table @option
1989
1990 @item to=@var{L}
1991
1992 With this option, QEMU will try next available VNC @var{display}s, until the
1993 number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1994 available, e.g. port 5900+@var{display} is already used by another
1995 application. By default, to=0.
1996
1997 @item @var{host}:@var{d}
1998
1999 TCP connections will only be allowed from @var{host} on display @var{d}.
2000 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
2001 be omitted in which case the server will accept connections from any host.
2002
2003 @item unix:@var{path}
2004
2005 Connections will be allowed over UNIX domain sockets where @var{path} is the
2006 location of a unix socket to listen for connections on.
2007
2008 @item none
2009
2010 VNC is initialized but not started. The monitor @code{change} command
2011 can be used to later start the VNC server.
2012
2013 @end table
2014
2015 Following the @var{display} value there may be one or more @var{option} flags
2016 separated by commas. Valid options are
2017
2018 @table @option
2019
2020 @item reverse
2021
2022 Connect to a listening VNC client via a ``reverse'' connection. The
2023 client is specified by the @var{display}. For reverse network
2024 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
2025 is a TCP port number, not a display number.
2026
2027 @item websocket
2028
2029 Opens an additional TCP listening port dedicated to VNC Websocket connections.
2030 If a bare @var{websocket} option is given, the Websocket port is
2031 5700+@var{display}. An alternative port can be specified with the
2032 syntax @code{websocket}=@var{port}.
2033
2034 If @var{host} is specified connections will only be allowed from this host.
2035 It is possible to control the websocket listen address independently, using
2036 the syntax @code{websocket}=@var{host}:@var{port}.
2037
2038 If no TLS credentials are provided, the websocket connection runs in
2039 unencrypted mode. If TLS credentials are provided, the websocket connection
2040 requires encrypted client connections.
2041
2042 @item password
2043
2044 Require that password based authentication is used for client connections.
2045
2046 The password must be set separately using the @code{set_password} command in
2047 the @ref{pcsys_monitor}. The syntax to change your password is:
2048 @code{set_password <protocol> <password>} where <protocol> could be either
2049 "vnc" or "spice".
2050
2051 If you would like to change <protocol> password expiration, you should use
2052 @code{expire_password <protocol> <expiration-time>} where expiration time could
2053 be one of the following options: now, never, +seconds or UNIX time of
2054 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
2055 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
2056 date and time).
2057
2058 You can also use keywords "now" or "never" for the expiration time to
2059 allow <protocol> password to expire immediately or never expire.
2060
2061 @item tls-creds=@var{ID}
2062
2063 Provides the ID of a set of TLS credentials to use to secure the
2064 VNC server. They will apply to both the normal VNC server socket
2065 and the websocket socket (if enabled). Setting TLS credentials
2066 will cause the VNC server socket to enable the VeNCrypt auth
2067 mechanism.  The credentials should have been previously created
2068 using the @option{-object tls-creds} argument.
2069
2070 @item tls-authz=@var{ID}
2071
2072 Provides the ID of the QAuthZ authorization object against which
2073 the client's x509 distinguished name will validated. This object is
2074 only resolved at time of use, so can be deleted and recreated on the
2075 fly while the VNC server is active. If missing, it will default
2076 to denying access.
2077
2078 @item sasl
2079
2080 Require that the client use SASL to authenticate with the VNC server.
2081 The exact choice of authentication method used is controlled from the
2082 system / user's SASL configuration file for the 'qemu' service. This
2083 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
2084 unprivileged user, an environment variable SASL_CONF_PATH can be used
2085 to make it search alternate locations for the service config.
2086 While some SASL auth methods can also provide data encryption (eg GSSAPI),
2087 it is recommended that SASL always be combined with the 'tls' and
2088 'x509' settings to enable use of SSL and server certificates. This
2089 ensures a data encryption preventing compromise of authentication
2090 credentials. See the @ref{vnc_security} section for details on using
2091 SASL authentication.
2092
2093 @item sasl-authz=@var{ID}
2094
2095 Provides the ID of the QAuthZ authorization object against which
2096 the client's SASL username will validated. This object is
2097 only resolved at time of use, so can be deleted and recreated on the
2098 fly while the VNC server is active. If missing, it will default
2099 to denying access.
2100
2101 @item acl
2102
2103 Legacy method for enabling authorization of clients against the
2104 x509 distinguished name and SASL username. It results in the creation
2105 of two @code{authz-list} objects with IDs of @code{vnc.username} and
2106 @code{vnc.x509dname}. The rules for these objects must be configured
2107 with the HMP ACL commands.
2108
2109 This option is deprecated and should no longer be used. The new
2110 @option{sasl-authz} and @option{tls-authz} options are a
2111 replacement.
2112
2113 @item lossy
2114
2115 Enable lossy compression methods (gradient, JPEG, ...). If this
2116 option is set, VNC client may receive lossy framebuffer updates
2117 depending on its encoding settings. Enabling this option can save
2118 a lot of bandwidth at the expense of quality.
2119
2120 @item non-adaptive
2121
2122 Disable adaptive encodings. Adaptive encodings are enabled by default.
2123 An adaptive encoding will try to detect frequently updated screen regions,
2124 and send updates in these regions using a lossy encoding (like JPEG).
2125 This can be really helpful to save bandwidth when playing videos. Disabling
2126 adaptive encodings restores the original static behavior of encodings
2127 like Tight.
2128
2129 @item share=[allow-exclusive|force-shared|ignore]
2130
2131 Set display sharing policy.  'allow-exclusive' allows clients to ask
2132 for exclusive access.  As suggested by the rfb spec this is
2133 implemented by dropping other connections.  Connecting multiple
2134 clients in parallel requires all clients asking for a shared session
2135 (vncviewer: -shared switch).  This is the default.  'force-shared'
2136 disables exclusive client access.  Useful for shared desktop sessions,
2137 where you don't want someone forgetting specify -shared disconnect
2138 everybody else.  'ignore' completely ignores the shared flag and
2139 allows everybody connect unconditionally.  Doesn't conform to the rfb
2140 spec but is traditional QEMU behavior.
2141
2142 @item key-delay-ms
2143
2144 Set keyboard delay, for key down and key up events, in milliseconds.
2145 Default is 10.  Keyboards are low-bandwidth devices, so this slowdown
2146 can help the device and guest to keep up and not lose events in case
2147 events are arriving in bulk.  Possible causes for the latter are flaky
2148 network connections, or scripts for automated testing.
2149
2150 @item audiodev=@var{audiodev}
2151
2152 Use the specified @var{audiodev} when the VNC client requests audio
2153 transmission. When not using an -audiodev argument, this option must
2154 be omitted, otherwise is must be present and specify a valid audiodev.
2155
2156 @end table
2157 ETEXI
2158
2159 STEXI
2160 @end table
2161 ETEXI
2162 ARCHHEADING(, QEMU_ARCH_I386)
2163
2164 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
2165 STEXI
2166 @table @option
2167 ETEXI
2168
2169 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
2170     "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
2171     QEMU_ARCH_I386)
2172 STEXI
2173 @item -win2k-hack
2174 @findex -win2k-hack
2175 Use it when installing Windows 2000 to avoid a disk full bug. After
2176 Windows 2000 is installed, you no longer need this option (this option
2177 slows down the IDE transfers).
2178 ETEXI
2179
2180 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
2181     "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
2182     QEMU_ARCH_I386)
2183 STEXI
2184 @item -no-fd-bootchk
2185 @findex -no-fd-bootchk
2186 Disable boot signature checking for floppy disks in BIOS. May
2187 be needed to boot from old floppy disks.
2188 ETEXI
2189
2190 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
2191            "-no-acpi        disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2192 STEXI
2193 @item -no-acpi
2194 @findex -no-acpi
2195 Disable ACPI (Advanced Configuration and Power Interface) support. Use
2196 it if your guest OS complains about ACPI problems (PC target machine
2197 only).
2198 ETEXI
2199
2200 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
2201     "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
2202 STEXI
2203 @item -no-hpet
2204 @findex -no-hpet
2205 Disable HPET support.
2206 ETEXI
2207
2208 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
2209     "-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"
2210     "                ACPI table description\n", QEMU_ARCH_I386)
2211 STEXI
2212 @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}]...]
2213 @findex -acpitable
2214 Add ACPI table with specified header fields and context from specified files.
2215 For file=, take whole ACPI table from the specified files, including all
2216 ACPI headers (possible overridden by other options).
2217 For data=, only data
2218 portion of the table is used, all header information is specified in the
2219 command line.
2220 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
2221 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
2222 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
2223 spec.
2224 ETEXI
2225
2226 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2227     "-smbios file=binary\n"
2228     "                load SMBIOS entry from binary file\n"
2229     "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2230     "              [,uefi=on|off]\n"
2231     "                specify SMBIOS type 0 fields\n"
2232     "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2233     "              [,uuid=uuid][,sku=str][,family=str]\n"
2234     "                specify SMBIOS type 1 fields\n"
2235     "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2236     "              [,asset=str][,location=str]\n"
2237     "                specify SMBIOS type 2 fields\n"
2238     "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2239     "              [,sku=str]\n"
2240     "                specify SMBIOS type 3 fields\n"
2241     "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2242     "              [,asset=str][,part=str]\n"
2243     "                specify SMBIOS type 4 fields\n"
2244     "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
2245     "               [,asset=str][,part=str][,speed=%d]\n"
2246     "                specify SMBIOS type 17 fields\n",
2247     QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2248 STEXI
2249 @item -smbios file=@var{binary}
2250 @findex -smbios
2251 Load SMBIOS entry from binary file.
2252
2253 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
2254 Specify SMBIOS type 0 fields
2255
2256 @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}]
2257 Specify SMBIOS type 1 fields
2258
2259 @item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}]
2260 Specify SMBIOS type 2 fields
2261
2262 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
2263 Specify SMBIOS type 3 fields
2264
2265 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
2266 Specify SMBIOS type 4 fields
2267
2268 @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}]
2269 Specify SMBIOS type 17 fields
2270 ETEXI
2271
2272 STEXI
2273 @end table
2274 ETEXI
2275 DEFHEADING()
2276
2277 DEFHEADING(Network options:)
2278 STEXI
2279 @table @option
2280 ETEXI
2281
2282 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
2283 #ifdef CONFIG_SLIRP
2284     "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
2285     "         [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2286     "         [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
2287     "         [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
2288     "         [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
2289 #ifndef _WIN32
2290                                              "[,smb=dir[,smbserver=addr]]\n"
2291 #endif
2292     "                configure a user mode network backend with ID 'str',\n"
2293     "                its DHCP server and optional services\n"
2294 #endif
2295 #ifdef _WIN32
2296     "-netdev tap,id=str,ifname=name\n"
2297     "                configure a host TAP network backend with ID 'str'\n"
2298 #else
2299     "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
2300     "         [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
2301     "         [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
2302     "         [,poll-us=n]\n"
2303     "                configure a host TAP network backend with ID 'str'\n"
2304     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2305     "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2306     "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2307     "                to deconfigure it\n"
2308     "                use '[down]script=no' to disable script execution\n"
2309     "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2310     "                configure it\n"
2311     "                use 'fd=h' to connect to an already opened TAP interface\n"
2312     "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
2313     "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
2314     "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
2315     "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2316     "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
2317     "                use vhost=on to enable experimental in kernel accelerator\n"
2318     "                    (only has effect for virtio guests which use MSIX)\n"
2319     "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
2320     "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
2321     "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
2322     "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
2323     "                use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
2324     "                spent on busy polling for vhost net\n"
2325     "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2326     "                configure a host TAP network backend with ID 'str' that is\n"
2327     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2328     "                using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
2329 #endif
2330 #ifdef __linux__
2331     "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2332     "         [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
2333     "         [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
2334     "         [,rxcookie=rxcookie][,offset=offset]\n"
2335     "                configure a network backend with ID 'str' connected to\n"
2336     "                an Ethernet over L2TPv3 pseudowire.\n"
2337     "                Linux kernel 3.3+ as well as most routers can talk\n"
2338     "                L2TPv3. This transport allows connecting a VM to a VM,\n"
2339     "                VM to a router and even VM to Host. It is a nearly-universal\n"
2340     "                standard (RFC3931). Note - this implementation uses static\n"
2341     "                pre-configured tunnels (same as the Linux kernel).\n"
2342     "                use 'src=' to specify source address\n"
2343     "                use 'dst=' to specify destination address\n"
2344     "                use 'udp=on' to specify udp encapsulation\n"
2345     "                use 'srcport=' to specify source udp port\n"
2346     "                use 'dstport=' to specify destination udp port\n"
2347     "                use 'ipv6=on' to force v6\n"
2348     "                L2TPv3 uses cookies to prevent misconfiguration as\n"
2349     "                well as a weak security measure\n"
2350     "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
2351     "                use 'txcookie=0x012345678' to specify a txcookie\n"
2352     "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2353     "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2354     "                use 'pincounter=on' to work around broken counter handling in peer\n"
2355     "                use 'offset=X' to add an extra offset between header and data\n"
2356 #endif
2357     "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2358     "                configure a network backend to connect to another network\n"
2359     "                using a socket connection\n"
2360     "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2361     "                configure a network backend to connect to a multicast maddr and port\n"
2362     "                use 'localaddr=addr' to specify the host address to send packets from\n"
2363     "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2364     "                configure a network backend to connect to another network\n"
2365     "                using an UDP tunnel\n"
2366 #ifdef CONFIG_VDE
2367     "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2368     "                configure a network backend to connect to port 'n' of a vde switch\n"
2369     "                running on host and listening for incoming connections on 'socketpath'.\n"
2370     "                Use group 'groupname' and mode 'octalmode' to change default\n"
2371     "                ownership and permissions for communication port.\n"
2372 #endif
2373 #ifdef CONFIG_NETMAP
2374     "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
2375     "                attach to the existing netmap-enabled network interface 'name', or to a\n"
2376     "                VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2377     "                netmap device, defaults to '/dev/netmap')\n"
2378 #endif
2379 #ifdef CONFIG_POSIX
2380     "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2381     "                configure a vhost-user network, backed by a chardev 'dev'\n"
2382 #endif
2383     "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
2384     "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
2385 DEF("nic", HAS_ARG, QEMU_OPTION_nic,
2386     "-nic [tap|bridge|"
2387 #ifdef CONFIG_SLIRP
2388     "user|"
2389 #endif
2390 #ifdef __linux__
2391     "l2tpv3|"
2392 #endif
2393 #ifdef CONFIG_VDE
2394     "vde|"
2395 #endif
2396 #ifdef CONFIG_NETMAP
2397     "netmap|"
2398 #endif
2399 #ifdef CONFIG_POSIX
2400     "vhost-user|"
2401 #endif
2402     "socket][,option][,...][mac=macaddr]\n"
2403     "                initialize an on-board / default host NIC (using MAC address\n"
2404     "                macaddr) and connect it to the given host network backend\n"
2405     "-nic none       use it alone to have zero network devices (the default is to\n"
2406     "                provided a 'user' network connection)\n",
2407     QEMU_ARCH_ALL)
2408 DEF("net", HAS_ARG, QEMU_OPTION_net,
2409     "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2410     "                configure or create an on-board (or machine default) NIC and\n"
2411     "                connect it to hub 0 (please use -nic unless you need a hub)\n"
2412     "-net ["
2413 #ifdef CONFIG_SLIRP
2414     "user|"
2415 #endif
2416     "tap|"
2417     "bridge|"
2418 #ifdef CONFIG_VDE
2419     "vde|"
2420 #endif
2421 #ifdef CONFIG_NETMAP
2422     "netmap|"
2423 #endif
2424     "socket][,option][,option][,...]\n"
2425     "                old way to initialize a host network interface\n"
2426     "                (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2427 STEXI
2428 @item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2429 @findex -nic
2430 This option is a shortcut for configuring both the on-board (default) guest
2431 NIC hardware and the host network backend in one go. The host backend options
2432 are the same as with the corresponding @option{-netdev} options below.
2433 The guest NIC model can be set with @option{model=@var{modelname}}.
2434 Use @option{model=help} to list the available device types.
2435 The hardware MAC address can be set with @option{mac=@var{macaddr}}.
2436
2437 The following two example do exactly the same, to show how @option{-nic} can
2438 be used to shorten the command line length:
2439 @example
2440 @value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2441 @value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2442 @end example
2443
2444 @item -nic none
2445 Indicate that no network devices should be configured. It is used to override
2446 the default configuration (default NIC with ``user'' host network backend)
2447 which is activated if no other networking options are provided.
2448
2449 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
2450 @findex -netdev
2451 Configure user mode host network backend which requires no administrator
2452 privilege to run. Valid options are:
2453
2454 @table @option
2455 @item id=@var{id}
2456 Assign symbolic name for use in monitor commands.
2457
2458 @item ipv4=on|off and ipv6=on|off
2459 Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2460 both protocols are enabled.
2461
2462 @item net=@var{addr}[/@var{mask}]
2463 Set IP network address the guest will see. Optionally specify the netmask,
2464 either in the form a.b.c.d or as number of valid top-most bits. Default is
2465 10.0.2.0/24.
2466
2467 @item host=@var{addr}
2468 Specify the guest-visible address of the host. Default is the 2nd IP in the
2469 guest network, i.e. x.x.x.2.
2470
2471 @item ipv6-net=@var{addr}[/@var{int}]
2472 Set IPv6 network address the guest will see (default is fec0::/64). The
2473 network prefix is given in the usual hexadecimal IPv6 address
2474 notation. The prefix size is optional, and is given as the number of
2475 valid top-most bits (default is 64).
2476
2477 @item ipv6-host=@var{addr}
2478 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2479 the guest network, i.e. xxxx::2.
2480
2481 @item restrict=on|off
2482 If this option is enabled, the guest will be isolated, i.e. it will not be
2483 able to contact the host and no guest IP packets will be routed over the host
2484 to the outside. This option does not affect any explicitly set forwarding rules.
2485
2486 @item hostname=@var{name}
2487 Specifies the client hostname reported by the built-in DHCP server.
2488
2489 @item dhcpstart=@var{addr}
2490 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
2491 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
2492
2493 @item dns=@var{addr}
2494 Specify the guest-visible address of the virtual nameserver. The address must
2495 be different from the host address. Default is the 3rd IP in the guest network,
2496 i.e. x.x.x.3.
2497
2498 @item ipv6-dns=@var{addr}
2499 Specify the guest-visible address of the IPv6 virtual nameserver. The address
2500 must be different from the host address. Default is the 3rd IP in the guest
2501 network, i.e. xxxx::3.
2502
2503 @item dnssearch=@var{domain}
2504 Provides an entry for the domain-search list sent by the built-in
2505 DHCP server. More than one domain suffix can be transmitted by specifying
2506 this option multiple times. If supported, this will cause the guest to
2507 automatically try to append the given domain suffix(es) in case a domain name
2508 can not be resolved.
2509
2510 Example:
2511 @example
2512 @value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2513 @end example
2514
2515 @item domainname=@var{domain}
2516 Specifies the client domain name reported by the built-in DHCP server.
2517
2518 @item tftp=@var{dir}
2519 When using the user mode network stack, activate a built-in TFTP
2520 server. The files in @var{dir} will be exposed as the root of a TFTP server.
2521 The TFTP client on the guest must be configured in binary mode (use the command
2522 @code{bin} of the Unix TFTP client).
2523
2524 @item tftp-server-name=@var{name}
2525 In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
2526 66). This can be used to advise the guest to load boot files or configurations
2527 from a different server than the host address.
2528
2529 @item bootfile=@var{file}
2530 When using the user mode network stack, broadcast @var{file} as the BOOTP
2531 filename. In conjunction with @option{tftp}, this can be used to network boot
2532 a guest from a local directory.
2533
2534 Example (using pxelinux):
2535 @example
2536 @value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \
2537     -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2538 @end example
2539
2540 @item smb=@var{dir}[,smbserver=@var{addr}]
2541 When using the user mode network stack, activate a built-in SMB
2542 server so that Windows OSes can access to the host files in @file{@var{dir}}
2543 transparently. The IP address of the SMB server can be set to @var{addr}. By
2544 default the 4th IP in the guest network is used, i.e. x.x.x.4.
2545
2546 In the guest Windows OS, the line:
2547 @example
2548 10.0.2.4 smbserver
2549 @end example
2550 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2551 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2552
2553 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2554
2555 Note that a SAMBA server must be installed on the host OS.
2556
2557 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
2558 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2559 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2560 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
2561 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2562 be bound to a specific host interface. If no connection type is set, TCP is
2563 used. This option can be given multiple times.
2564
2565 For example, to redirect host X11 connection from screen 1 to guest
2566 screen 0, use the following:
2567
2568 @example
2569 # on the host
2570 @value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2571 # this host xterm should open in the guest X11 server
2572 xterm -display :1
2573 @end example
2574
2575 To redirect telnet connections from host port 5555 to telnet port on
2576 the guest, use the following:
2577
2578 @example
2579 # on the host
2580 @value{qemu_system} -nic user,hostfwd=tcp::5555-:23
2581 telnet localhost 5555
2582 @end example
2583
2584 Then when you use on the host @code{telnet localhost 5555}, you
2585 connect to the guest telnet server.
2586
2587 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
2588 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
2589 Forward guest TCP connections to the IP address @var{server} on port @var{port}
2590 to the character device @var{dev} or to a program executed by @var{cmd:command}
2591 which gets spawned for each connection. This option can be given multiple times.
2592
2593 You can either use a chardev directly and have that one used throughout QEMU's
2594 lifetime, like in the following example:
2595
2596 @example
2597 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2598 # the guest accesses it
2599 @value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2600 @end example
2601
2602 Or you can execute a command on every TCP connection established by the guest,
2603 so that QEMU behaves similar to an inetd process for that virtual server:
2604
2605 @example
2606 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2607 # and connect the TCP stream to its stdin/stdout
2608 @value{qemu_system} -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2609 @end example
2610
2611 @end table
2612
2613 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2614 Configure a host TAP network backend with ID @var{id}.
2615
2616 Use the network script @var{file} to configure it and the network script
2617 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
2618 automatically provides one. The default network configure script is
2619 @file{/etc/qemu-ifup} and the default network deconfigure script is
2620 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2621 to disable script execution.
2622
2623 If running QEMU as an unprivileged user, use the network helper
2624 @var{helper} to configure the TAP interface and attach it to the bridge.
2625 The default network helper executable is @file{/path/to/qemu-bridge-helper}
2626 and the default bridge device is @file{br0}.
2627
2628 @option{fd}=@var{h} can be used to specify the handle of an already
2629 opened host TAP interface.
2630
2631 Examples:
2632
2633 @example
2634 #launch a QEMU instance with the default network script
2635 @value{qemu_system} linux.img -nic tap
2636 @end example
2637
2638 @example
2639 #launch a QEMU instance with two NICs, each one connected
2640 #to a TAP device
2641 @value{qemu_system} linux.img \
2642         -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2643         -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2644 @end example
2645
2646 @example
2647 #launch a QEMU instance with the default network helper to
2648 #connect a TAP device to bridge br0
2649 @value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \
2650         -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2651 @end example
2652
2653 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
2654 Connect a host TAP network interface to a host bridge device.
2655
2656 Use the network helper @var{helper} to configure the TAP interface and
2657 attach it to the bridge. The default network helper executable is
2658 @file{/path/to/qemu-bridge-helper} and the default bridge
2659 device is @file{br0}.
2660
2661 Examples:
2662
2663 @example
2664 #launch a QEMU instance with the default network helper to
2665 #connect a TAP device to bridge br0
2666 @value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2667 @end example
2668
2669 @example
2670 #launch a QEMU instance with the default network helper to
2671 #connect a TAP device to bridge qemubr0
2672 @value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2673 @end example
2674
2675 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
2676
2677 This host network backend can be used to connect the guest's network to
2678 another QEMU virtual machine using a TCP socket connection. If @option{listen}
2679 is specified, QEMU waits for incoming connections on @var{port}
2680 (@var{host} is optional). @option{connect} is used to connect to
2681 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2682 specifies an already opened TCP socket.
2683
2684 Example:
2685 @example
2686 # launch a first QEMU instance
2687 @value{qemu_system} linux.img \
2688                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2689                  -netdev socket,id=n1,listen=:1234
2690 # connect the network of this instance to the network of the first instance
2691 @value{qemu_system} linux.img \
2692                  -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2693                  -netdev socket,id=n2,connect=127.0.0.1:1234
2694 @end example
2695
2696 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
2697
2698 Configure a socket host network backend to share the guest's network traffic
2699 with another QEMU virtual machines using a UDP multicast socket, effectively
2700 making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
2701 NOTES:
2702 @enumerate
2703 @item
2704 Several QEMU can be running on different hosts and share same bus (assuming
2705 correct multicast setup for these hosts).
2706 @item
2707 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2708 @url{http://user-mode-linux.sf.net}.
2709 @item
2710 Use @option{fd=h} to specify an already opened UDP multicast socket.
2711 @end enumerate
2712
2713 Example:
2714 @example
2715 # launch one QEMU instance
2716 @value{qemu_system} linux.img \
2717                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2718                  -netdev socket,id=n1,mcast=230.0.0.1:1234
2719 # launch another QEMU instance on same "bus"
2720 @value{qemu_system} linux.img \
2721                  -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2722                  -netdev socket,id=n2,mcast=230.0.0.1:1234
2723 # launch yet another QEMU instance on same "bus"
2724 @value{qemu_system} linux.img \
2725                  -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
2726                  -netdev socket,id=n3,mcast=230.0.0.1:1234
2727 @end example
2728
2729 Example (User Mode Linux compat.):
2730 @example
2731 # launch QEMU instance (note mcast address selected is UML's default)
2732 @value{qemu_system} linux.img \
2733                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2734                  -netdev socket,id=n1,mcast=239.192.168.1:1102
2735 # launch UML
2736 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2737 @end example
2738
2739 Example (send packets from host's 1.2.3.4):
2740 @example
2741 @value{qemu_system} linux.img \
2742                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2743                  -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2744 @end example
2745
2746 @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}]
2747 Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931) is a
2748 popular protocol to transport Ethernet (and other Layer 2) data frames between
2749 two systems. It is present in routers, firewalls and the Linux kernel
2750 (from version 3.3 onwards).
2751
2752 This transport allows a VM to communicate to another VM, router or firewall directly.
2753
2754 @table @option
2755 @item src=@var{srcaddr}
2756     source address (mandatory)
2757 @item dst=@var{dstaddr}
2758     destination address (mandatory)
2759 @item udp
2760     select udp encapsulation (default is ip).
2761 @item srcport=@var{srcport}
2762     source udp port.
2763 @item dstport=@var{dstport}
2764     destination udp port.
2765 @item ipv6
2766     force v6, otherwise defaults to v4.
2767 @item rxcookie=@var{rxcookie}
2768 @itemx txcookie=@var{txcookie}
2769     Cookies are a weak form of security in the l2tpv3 specification.
2770 Their function is mostly to prevent misconfiguration. By default they are 32
2771 bit.
2772 @item cookie64
2773     Set cookie size to 64 bit instead of the default 32
2774 @item counter=off
2775     Force a 'cut-down' L2TPv3 with no counter as in
2776 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2777 @item pincounter=on
2778     Work around broken counter handling in peer. This may also help on
2779 networks which have packet reorder.
2780 @item offset=@var{offset}
2781     Add an extra offset between header and data
2782 @end table
2783
2784 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2785 on the remote Linux host 1.2.3.4:
2786 @example
2787 # Setup tunnel on linux host using raw ip as encapsulation
2788 # on 1.2.3.4
2789 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2790     encap udp udp_sport 16384 udp_dport 16384
2791 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2792     0xFFFFFFFF peer_session_id 0xFFFFFFFF
2793 ifconfig vmtunnel0 mtu 1500
2794 ifconfig vmtunnel0 up
2795 brctl addif br-lan vmtunnel0
2796
2797
2798 # on 4.3.2.1
2799 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2800
2801 @value{qemu_system} linux.img -device e1000,netdev=n1 \
2802     -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2803
2804 @end example
2805
2806 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2807 Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
2808 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2809 and MODE @var{octalmode} to change default ownership and permissions for
2810 communication port. This option is only available if QEMU has been compiled
2811 with vde support enabled.
2812
2813 Example:
2814 @example
2815 # launch vde switch
2816 vde_switch -F -sock /tmp/myswitch
2817 # launch QEMU instance
2818 @value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch
2819 @end example
2820
2821 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2822
2823 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2824 be a unix domain socket backed one. The vhost-user uses a specifically defined
2825 protocol to pass vhost ioctl replacement messages to an application on the other
2826 end of the socket. On non-MSIX guests, the feature can be forced with
2827 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2828 be created for multiqueue vhost-user.
2829
2830 Example:
2831 @example
2832 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2833      -numa node,memdev=mem \
2834      -chardev socket,id=chr0,path=/path/to/socket \
2835      -netdev type=vhost-user,id=net0,chardev=chr0 \
2836      -device virtio-net-pci,netdev=net0
2837 @end example
2838
2839 @item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
2840
2841 Create a hub port on the emulated hub with ID @var{hubid}.
2842
2843 The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
2844 single netdev. Alternatively, you can also connect the hubport to another
2845 netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
2846
2847 @item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
2848 @findex -net
2849 Legacy option to configure or create an on-board (or machine default) Network
2850 Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2851 the default hub), or to the netdev @var{nd}.
2852 If @var{model} is omitted, then the default NIC model associated with
2853 the machine type is used. Note that the default NIC model may change in
2854 future QEMU releases, so it is highly recommended to always specify a model.
2855 Optionally, the MAC address can be changed to @var{mac}, the device
2856 address set to @var{addr} (PCI cards only), and a @var{name} can be
2857 assigned for use in monitor commands.
2858 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2859 that the card should have; this option currently only affects virtio cards; set
2860 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2861 NIC is created.  QEMU can emulate several different models of network card.
2862 Use @code{-net nic,model=help} for a list of available devices for your target.
2863
2864 @item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
2865 Configure a host network backend (with the options corresponding to the same
2866 @option{-netdev} option) and connect it to the emulated hub 0 (the default
2867 hub). Use @var{name} to specify the name of the hub port.
2868 ETEXI
2869
2870 STEXI
2871 @end table
2872 ETEXI
2873 DEFHEADING()
2874
2875 DEFHEADING(Character device options:)
2876
2877 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
2878     "-chardev help\n"
2879     "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2880     "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2881     "         [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n"
2882     "         [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
2883     "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n"
2884     "         [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
2885     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
2886     "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
2887     "         [,logfile=PATH][,logappend=on|off]\n"
2888     "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2889     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
2890     "         [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2891     "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2892     "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2893     "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2894 #ifdef _WIN32
2895     "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2896     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2897 #else
2898     "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2899     "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
2900 #endif
2901 #ifdef CONFIG_BRLAPI
2902     "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2903 #endif
2904 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2905         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2906     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2907     "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2908 #endif
2909 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2910     "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2911     "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2912 #endif
2913 #if defined(CONFIG_SPICE)
2914     "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2915     "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2916 #endif
2917     , QEMU_ARCH_ALL
2918 )
2919
2920 STEXI
2921
2922 The general form of a character device option is:
2923 @table @option
2924 @item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
2925 @findex -chardev
2926 Backend is one of:
2927 @option{null},
2928 @option{socket},
2929 @option{udp},
2930 @option{msmouse},
2931 @option{vc},
2932 @option{ringbuf},
2933 @option{file},
2934 @option{pipe},
2935 @option{console},
2936 @option{serial},
2937 @option{pty},
2938 @option{stdio},
2939 @option{braille},
2940 @option{tty},
2941 @option{parallel},
2942 @option{parport},
2943 @option{spicevmc},
2944 @option{spiceport}.
2945 The specific backend will determine the applicable options.
2946
2947 Use @code{-chardev help} to print all available chardev backend types.
2948
2949 All devices must have an id, which can be any string up to 127 characters long.
2950 It is used to uniquely identify this device in other command line directives.
2951
2952 A character device may be used in multiplexing mode by multiple front-ends.
2953 Specify @option{mux=on} to enable this mode.
2954 A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2955 backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2956 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2957 create a multiplexer with your specified ID, and you can then configure multiple
2958 front ends to use that chardev ID for their input/output. Up to four different
2959 front ends can be connected to a single multiplexed chardev. (Without
2960 multiplexing enabled, a chardev can only be used by a single front end.)
2961 For instance you could use this to allow a single stdio chardev to be used by
2962 two serial ports and the QEMU monitor:
2963
2964 @example
2965 -chardev stdio,mux=on,id=char0 \
2966 -mon chardev=char0,mode=readline \
2967 -serial chardev:char0 \
2968 -serial chardev:char0
2969 @end example
2970
2971 You can have more than one multiplexer in a system configuration; for instance
2972 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2973 multiplexed between the QEMU monitor and a parallel port:
2974
2975 @example
2976 -chardev stdio,mux=on,id=char0 \
2977 -mon chardev=char0,mode=readline \
2978 -parallel chardev:char0 \
2979 -chardev tcp,...,mux=on,id=char1 \
2980 -serial chardev:char1 \
2981 -serial chardev:char1
2982 @end example
2983
2984 When you're using a multiplexed character device, some escape sequences are
2985 interpreted in the input. @xref{mux_keys, Keys in the character backend
2986 multiplexer}.
2987
2988 Note that some other command line options may implicitly create multiplexed
2989 character backends; for instance @option{-serial mon:stdio} creates a
2990 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2991 and @option{-nographic} also multiplexes the console and the monitor to
2992 stdio.
2993
2994 There is currently no support for multiplexing in the other direction
2995 (where a single QEMU front end takes input and output from multiple chardevs).
2996
2997 Every backend supports the @option{logfile} option, which supplies the path
2998 to a file to record all data transmitted via the backend. The @option{logappend}
2999 option controls whether the log file will be truncated or appended to when
3000 opened.
3001
3002 @end table
3003
3004 The available backends are:
3005
3006 @table @option
3007 @item -chardev null,id=@var{id}
3008 A void device. This device will not emit any data, and will drop any data it
3009 receives. The null backend does not take any options.
3010
3011 @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}]
3012
3013 Create a two-way stream socket, which can be either a TCP or a unix socket. A
3014 unix socket will be created if @option{path} is specified. Behaviour is
3015 undefined if TCP options are specified for a unix socket.
3016
3017 @option{server} specifies that the socket shall be a listening socket.
3018
3019 @option{nowait} specifies that QEMU should not block waiting for a client to
3020 connect to a listening socket.
3021
3022 @option{telnet} specifies that traffic on the socket should interpret telnet
3023 escape sequences.
3024
3025 @option{websocket} specifies that the socket uses WebSocket protocol for
3026 communication.
3027
3028 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
3029 the remote end goes away.  qemu will delay this many seconds and then attempt
3030 to reconnect.  Zero disables reconnecting, and is the default.
3031
3032 @option{tls-creds} requests enablement of the TLS protocol for encryption,
3033 and specifies the id of the TLS credentials to use for the handshake. The
3034 credentials must be previously created with the @option{-object tls-creds}
3035 argument.
3036
3037 @option{tls-auth} provides the ID of the QAuthZ authorization object against
3038 which the client's x509 distinguished name will be validated. This object is
3039 only resolved at time of use, so can be deleted and recreated on the fly
3040 while the chardev server is active. If missing, it will default to denying
3041 access.
3042
3043 TCP and unix socket options are given below:
3044
3045 @table @option
3046
3047 @item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
3048
3049 @option{host} for a listening socket specifies the local address to be bound.
3050 For a connecting socket species the remote host to connect to. @option{host} is
3051 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
3052
3053 @option{port} for a listening socket specifies the local port to be bound. For a
3054 connecting socket specifies the port on the remote host to connect to.
3055 @option{port} can be given as either a port number or a service name.
3056 @option{port} is required.
3057
3058 @option{to} is only relevant to listening sockets. If it is specified, and
3059 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
3060 to and including @option{to} until it succeeds. @option{to} must be specified
3061 as a port number.
3062
3063 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
3064 If neither is specified the socket may use either protocol.
3065
3066 @option{nodelay} disables the Nagle algorithm.
3067
3068 @item unix options: path=@var{path}
3069
3070 @option{path} specifies the local path of the unix socket. @option{path} is
3071 required.
3072
3073 @end table
3074
3075 @item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6]
3076
3077 Sends all traffic from the guest to a remote host over UDP.
3078
3079 @option{host} specifies the remote host to connect to. If not specified it
3080 defaults to @code{localhost}.
3081
3082 @option{port} specifies the port on the remote host to connect to. @option{port}
3083 is required.
3084
3085 @option{localaddr} specifies the local address to bind to. If not specified it
3086 defaults to @code{0.0.0.0}.
3087
3088 @option{localport} specifies the local port to bind to. If not specified any
3089 available local port will be used.
3090
3091 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
3092 If neither is specified the device may use either protocol.
3093
3094 @item -chardev msmouse,id=@var{id}
3095
3096 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
3097 take any options.
3098
3099 @item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]]
3100
3101 Connect to a QEMU text console. @option{vc} may optionally be given a specific
3102 size.
3103
3104 @option{width} and @option{height} specify the width and height respectively of
3105 the console, in pixels.
3106
3107 @option{cols} and @option{rows} specify that the console be sized to fit a text
3108 console with the given dimensions.
3109
3110 @item -chardev ringbuf,id=@var{id}[,size=@var{size}]
3111
3112 Create a ring buffer with fixed size @option{size}.
3113 @var{size} must be a power of two and defaults to @code{64K}.
3114
3115 @item -chardev file,id=@var{id},path=@var{path}
3116
3117 Log all traffic received from the guest to a file.
3118
3119 @option{path} specifies the path of the file to be opened. This file will be
3120 created if it does not already exist, and overwritten if it does. @option{path}
3121 is required.
3122
3123 @item -chardev pipe,id=@var{id},path=@var{path}
3124
3125 Create a two-way connection to the guest. The behaviour differs slightly between
3126 Windows hosts and other hosts:
3127
3128 On Windows, a single duplex pipe will be created at
3129 @file{\\.pipe\@option{path}}.
3130
3131 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
3132 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
3133 received by the guest. Data written by the guest can be read from
3134 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
3135 be present.
3136
3137 @option{path} forms part of the pipe path as described above. @option{path} is
3138 required.
3139
3140 @item -chardev console,id=@var{id}
3141
3142 Send traffic from the guest to QEMU's standard output. @option{console} does not
3143 take any options.
3144
3145 @option{console} is only available on Windows hosts.
3146
3147 @item -chardev serial,id=@var{id},path=@option{path}
3148
3149 Send traffic from the guest to a serial device on the host.
3150
3151 On Unix hosts serial will actually accept any tty device,
3152 not only serial lines.
3153
3154 @option{path} specifies the name of the serial device to open.
3155
3156 @item -chardev pty,id=@var{id}
3157
3158 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
3159 not take any options.
3160
3161 @option{pty} is not available on Windows hosts.
3162
3163 @item -chardev stdio,id=@var{id}[,signal=on|off]
3164 Connect to standard input and standard output of the QEMU process.
3165
3166 @option{signal} controls if signals are enabled on the terminal, that includes
3167 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
3168 default, use @option{signal=off} to disable it.
3169
3170 @item -chardev braille,id=@var{id}
3171
3172 Connect to a local BrlAPI server. @option{braille} does not take any options.
3173
3174 @item -chardev tty,id=@var{id},path=@var{path}
3175
3176 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
3177 DragonFlyBSD hosts.  It is an alias for @option{serial}.
3178
3179 @option{path} specifies the path to the tty. @option{path} is required.
3180
3181 @item -chardev parallel,id=@var{id},path=@var{path}
3182 @itemx -chardev parport,id=@var{id},path=@var{path}
3183
3184 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
3185
3186 Connect to a local parallel port.
3187
3188 @option{path} specifies the path to the parallel port device. @option{path} is
3189 required.
3190
3191 @item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
3192
3193 @option{spicevmc} is only available when spice support is built in.
3194
3195 @option{debug} debug level for spicevmc
3196
3197 @option{name} name of spice channel to connect to
3198
3199 Connect to a spice virtual machine channel, such as vdiport.
3200
3201 @item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
3202
3203 @option{spiceport} is only available when spice support is built in.
3204
3205 @option{debug} debug level for spicevmc
3206
3207 @option{name} name of spice port to connect to
3208
3209 Connect to a spice port, allowing a Spice client to handle the traffic
3210 identified by a name (preferably a fqdn).
3211 ETEXI
3212
3213 STEXI
3214 @end table
3215 ETEXI
3216 DEFHEADING()
3217
3218 #ifdef CONFIG_TPM
3219 DEFHEADING(TPM device options:)
3220
3221 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3222     "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3223     "                use path to provide path to a character device; default is /dev/tpm0\n"
3224     "                use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3225     "                not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3226     "-tpmdev emulator,id=id,chardev=dev\n"
3227     "                configure the TPM device using chardev backend\n",
3228     QEMU_ARCH_ALL)
3229 STEXI
3230
3231 The general form of a TPM device option is:
3232 @table @option
3233
3234 @item -tpmdev @var{backend},id=@var{id}[,@var{options}]
3235 @findex -tpmdev
3236
3237 The specific backend type will determine the applicable options.
3238 The @code{-tpmdev} option creates the TPM backend and requires a
3239 @code{-device} option that specifies the TPM frontend interface model.
3240
3241 Use @code{-tpmdev help} to print all available TPM backend types.
3242
3243 @end table
3244
3245 The available backends are:
3246
3247 @table @option
3248
3249 @item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
3250
3251 (Linux-host only) Enable access to the host's TPM using the passthrough
3252 driver.
3253
3254 @option{path} specifies the path to the host's TPM device, i.e., on
3255 a Linux host this would be @code{/dev/tpm0}.
3256 @option{path} is optional and by default @code{/dev/tpm0} is used.
3257
3258 @option{cancel-path} specifies the path to the host TPM device's sysfs
3259 entry allowing for cancellation of an ongoing TPM command.
3260 @option{cancel-path} is optional and by default QEMU will search for the
3261 sysfs entry to use.
3262
3263 Some notes about using the host's TPM with the passthrough driver:
3264
3265 The TPM device accessed by the passthrough driver must not be
3266 used by any other application on the host.
3267
3268 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3269 the VM's firmware (BIOS/UEFI) will not be able to initialize the
3270 TPM again and may therefore not show a TPM-specific menu that would
3271 otherwise allow the user to configure the TPM, e.g., allow the user to
3272 enable/disable or activate/deactivate the TPM.
3273 Further, if TPM ownership is released from within a VM then the host's TPM
3274 will get disabled and deactivated. To enable and activate the
3275 TPM again afterwards, the host has to be rebooted and the user is
3276 required to enter the firmware's menu to enable and activate the TPM.
3277 If the TPM is left disabled and/or deactivated most TPM commands will fail.
3278
3279 To create a passthrough TPM use the following two options:
3280 @example
3281 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3282 @end example
3283 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3284 @code{tpmdev=tpm0} in the device option.
3285
3286 @item -tpmdev emulator,id=@var{id},chardev=@var{dev}
3287
3288 (Linux-host only) Enable access to a TPM emulator using Unix domain socket based
3289 chardev backend.
3290
3291 @option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
3292
3293 To create a TPM emulator backend device with chardev socket backend:
3294 @example
3295
3296 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3297
3298 @end example
3299
3300 ETEXI
3301
3302 STEXI
3303 @end table
3304 ETEXI
3305 DEFHEADING()
3306
3307 #endif
3308
3309 DEFHEADING(Linux/Multiboot boot specific:)
3310 STEXI
3311
3312 When using these options, you can use a given Linux or Multiboot
3313 kernel without installing it in the disk image. It can be useful
3314 for easier testing of various kernels.
3315
3316 @table @option
3317 ETEXI
3318
3319 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3320     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3321 STEXI
3322 @item -kernel @var{bzImage}
3323 @findex -kernel
3324 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3325 or in multiboot format.
3326 ETEXI
3327
3328 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3329     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3330 STEXI
3331 @item -append @var{cmdline}
3332 @findex -append
3333 Use @var{cmdline} as kernel command line
3334 ETEXI
3335
3336 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3337            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3338 STEXI
3339 @item -initrd @var{file}
3340 @findex -initrd
3341 Use @var{file} as initial ram disk.
3342
3343 @item -initrd "@var{file1} arg=foo,@var{file2}"
3344
3345 This syntax is only available with multiboot.
3346
3347 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3348 first module.
3349 ETEXI
3350
3351 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3352     "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
3353 STEXI
3354 @item -dtb @var{file}
3355 @findex -dtb
3356 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3357 on boot.
3358 ETEXI
3359
3360 STEXI
3361 @end table
3362 ETEXI
3363 DEFHEADING()
3364
3365 DEFHEADING(Debug/Expert options:)
3366 STEXI
3367 @table @option
3368 ETEXI
3369
3370 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3371     "-fw_cfg [name=]<name>,file=<file>\n"
3372     "                add named fw_cfg entry with contents from file\n"
3373     "-fw_cfg [name=]<name>,string=<str>\n"
3374     "                add named fw_cfg entry with contents from string\n",
3375     QEMU_ARCH_ALL)
3376 STEXI
3377
3378 @item -fw_cfg [name=]@var{name},file=@var{file}
3379 @findex -fw_cfg
3380 Add named fw_cfg entry with contents from file @var{file}.
3381
3382 @item -fw_cfg [name=]@var{name},string=@var{str}
3383 Add named fw_cfg entry with contents from string @var{str}.
3384
3385 The terminating NUL character of the contents of @var{str} will not be
3386 included as part of the fw_cfg item data. To insert contents with
3387 embedded NUL characters, you have to use the @var{file} parameter.
3388
3389 The fw_cfg entries are passed by QEMU through to the guest.
3390
3391 Example:
3392 @example
3393     -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3394 @end example
3395 creates an fw_cfg entry named opt/com.mycompany/blob with contents
3396 from ./my_blob.bin.
3397
3398 ETEXI
3399
3400 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3401     "-serial dev     redirect the serial port to char device 'dev'\n",
3402     QEMU_ARCH_ALL)
3403 STEXI
3404 @item -serial @var{dev}
3405 @findex -serial
3406 Redirect the virtual serial port to host character device
3407 @var{dev}. The default device is @code{vc} in graphical mode and
3408 @code{stdio} in non graphical mode.
3409
3410 This option can be used several times to simulate up to 4 serial
3411 ports.
3412
3413 Use @code{-serial none} to disable all serial ports.
3414
3415 Available character devices are:
3416 @table @option
3417 @item vc[:@var{W}x@var{H}]
3418 Virtual console. Optionally, a width and height can be given in pixel with
3419 @example
3420 vc:800x600
3421 @end example
3422 It is also possible to specify width or height in characters:
3423 @example
3424 vc:80Cx24C
3425 @end example
3426 @item pty
3427 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3428 @item none
3429 No device is allocated.
3430 @item null
3431 void device
3432 @item chardev:@var{id}
3433 Use a named character device defined with the @code{-chardev} option.
3434 @item /dev/XXX
3435 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3436 parameters are set according to the emulated ones.
3437 @item /dev/parport@var{N}
3438 [Linux only, parallel port only] Use host parallel port
3439 @var{N}. Currently SPP and EPP parallel port features can be used.
3440 @item file:@var{filename}
3441 Write output to @var{filename}. No character can be read.
3442 @item stdio
3443 [Unix only] standard input/output
3444 @item pipe:@var{filename}
3445 name pipe @var{filename}
3446 @item COM@var{n}
3447 [Windows only] Use host serial port @var{n}
3448 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3449 This implements UDP Net Console.
3450 When @var{remote_host} or @var{src_ip} are not specified
3451 they default to @code{0.0.0.0}.
3452 When not using a specified @var{src_port} a random port is automatically chosen.
3453
3454 If you just want a simple readonly console you can use @code{netcat} or
3455 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3456 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
3457 will appear in the netconsole session.
3458
3459 If you plan to send characters back via netconsole or you want to stop
3460 and start QEMU a lot of times, you should have QEMU use the same
3461 source port each time by using something like @code{-serial
3462 udp::4555@@:4556} to QEMU. Another approach is to use a patched
3463 version of netcat which can listen to a TCP port and send and receive
3464 characters via udp.  If you have a patched version of netcat which
3465 activates telnet remote echo and single char transfer, then you can
3466 use the following options to set up a netcat redirector to allow
3467 telnet on port 5555 to access the QEMU port.
3468 @table @code
3469 @item QEMU Options:
3470 -serial udp::4555@@:4556
3471 @item netcat options:
3472 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3473 @item telnet options:
3474 localhost 5555
3475 @end table
3476
3477 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3478 The TCP Net Console has two modes of operation.  It can send the serial
3479 I/O to a location or wait for a connection from a location.  By default
3480 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
3481 the @var{server} option QEMU will wait for a client socket application
3482 to connect to the port before continuing, unless the @code{nowait}
3483 option was specified.  The @code{nodelay} option disables the Nagle buffering
3484 algorithm.  The @code{reconnect} option only applies if @var{noserver} is
3485 set, if the connection goes down it will attempt to reconnect at the
3486 given interval.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
3487 one TCP connection at a time is accepted. You can use @code{telnet} to
3488 connect to the corresponding character device.
3489 @table @code
3490 @item Example to send tcp console to 192.168.0.2 port 4444
3491 -serial tcp:192.168.0.2:4444
3492 @item Example to listen and wait on port 4444 for connection
3493 -serial tcp::4444,server
3494 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3495 -serial tcp:192.168.0.100:4444,server,nowait
3496 @end table
3497
3498 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3499 The telnet protocol is used instead of raw tcp sockets.  The options
3500 work the same as if you had specified @code{-serial tcp}.  The
3501 difference is that the port acts like a telnet server or client using
3502 telnet option negotiation.  This will also allow you to send the
3503 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3504 sequence.  Typically in unix telnet you do it with Control-] and then
3505 type "send break" followed by pressing the enter key.
3506
3507 @item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
3508 The WebSocket protocol is used instead of raw tcp socket. The port acts as
3509 a WebSocket server. Client mode is not supported.
3510
3511 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3512 A unix domain socket is used instead of a tcp socket.  The option works the
3513 same as if you had specified @code{-serial tcp} except the unix domain socket
3514 @var{path} is used for connections.
3515
3516 @item mon:@var{dev_string}
3517 This is a special option to allow the monitor to be multiplexed onto
3518 another serial port.  The monitor is accessed with key sequence of
3519 @key{Control-a} and then pressing @key{c}.
3520 @var{dev_string} should be any one of the serial devices specified
3521 above.  An example to multiplex the monitor onto a telnet server
3522 listening on port 4444 would be:
3523 @table @code
3524 @item -serial mon:telnet::4444,server,nowait
3525 @end table
3526 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3527 QEMU any more but will be passed to the guest instead.
3528
3529 @item braille
3530 Braille device.  This will use BrlAPI to display the braille output on a real
3531 or fake device.
3532
3533 @item msmouse
3534 Three button serial mouse. Configure the guest to use Microsoft protocol.
3535 @end table
3536 ETEXI
3537
3538 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3539     "-parallel dev   redirect the parallel port to char device 'dev'\n",
3540     QEMU_ARCH_ALL)
3541 STEXI
3542 @item -parallel @var{dev}
3543 @findex -parallel
3544 Redirect the virtual parallel port to host device @var{dev} (same
3545 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3546 be used to use hardware devices connected on the corresponding host
3547 parallel port.
3548
3549 This option can be used several times to simulate up to 3 parallel
3550 ports.
3551
3552 Use @code{-parallel none} to disable all parallel ports.
3553 ETEXI
3554
3555 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3556     "-monitor dev    redirect the monitor to char device 'dev'\n",
3557     QEMU_ARCH_ALL)
3558 STEXI
3559 @item -monitor @var{dev}
3560 @findex -monitor
3561 Redirect the monitor to host device @var{dev} (same devices as the
3562 serial port).
3563 The default device is @code{vc} in graphical mode and @code{stdio} in
3564 non graphical mode.
3565 Use @code{-monitor none} to disable the default monitor.
3566 ETEXI
3567 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3568     "-qmp dev        like -monitor but opens in 'control' mode\n",
3569     QEMU_ARCH_ALL)
3570 STEXI
3571 @item -qmp @var{dev}
3572 @findex -qmp
3573 Like -monitor but opens in 'control' mode.
3574 ETEXI
3575 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3576     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3577     QEMU_ARCH_ALL)
3578 STEXI
3579 @item -qmp-pretty @var{dev}
3580 @findex -qmp-pretty
3581 Like -qmp but uses pretty JSON formatting.
3582 ETEXI
3583
3584 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3585     "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
3586 STEXI
3587 @item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
3588 @findex -mon
3589 Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3590 easing human reading and debugging.
3591 ETEXI
3592
3593 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3594     "-debugcon dev   redirect the debug console to char device 'dev'\n",
3595     QEMU_ARCH_ALL)
3596 STEXI
3597 @item -debugcon @var{dev}
3598 @findex -debugcon
3599 Redirect the debug console to host device @var{dev} (same devices as the
3600 serial port).  The debug console is an I/O port which is typically port
3601 0xe9; writing to that I/O port sends output to this device.
3602 The default device is @code{vc} in graphical mode and @code{stdio} in
3603 non graphical mode.
3604 ETEXI
3605
3606 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3607     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
3608 STEXI
3609 @item -pidfile @var{file}
3610 @findex -pidfile
3611 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3612 from a script.
3613 ETEXI
3614
3615 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3616     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
3617 STEXI
3618 @item -singlestep
3619 @findex -singlestep
3620 Run the emulation in single step mode.
3621 ETEXI
3622
3623 DEF("preconfig", 0, QEMU_OPTION_preconfig, \
3624     "--preconfig     pause QEMU before machine is initialized (experimental)\n",
3625     QEMU_ARCH_ALL)
3626 STEXI
3627 @item --preconfig
3628 @findex --preconfig
3629 Pause QEMU for interactive configuration before the machine is created,
3630 which allows querying and configuring properties that will affect
3631 machine initialization.  Use QMP command 'x-exit-preconfig' to exit
3632 the preconfig state and move to the next state (i.e. run guest if -S
3633 isn't used or pause the second time if -S is used).  This option is
3634 experimental.
3635 ETEXI
3636
3637 DEF("S", 0, QEMU_OPTION_S, \
3638     "-S              freeze CPU at startup (use 'c' to start execution)\n",
3639     QEMU_ARCH_ALL)
3640 STEXI
3641 @item -S
3642 @findex -S
3643 Do not start CPU at startup (you must type 'c' in the monitor).
3644 ETEXI
3645
3646 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3647     "-realtime [mlock=on|off]\n"
3648     "                run qemu with realtime features\n"
3649     "                mlock=on|off controls mlock support (default: on)\n",
3650     QEMU_ARCH_ALL)
3651 STEXI
3652 @item -realtime mlock=on|off
3653 @findex -realtime
3654 Run qemu with realtime features.
3655 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3656 (enabled by default).
3657 ETEXI
3658
3659 DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
3660     "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
3661     "                run qemu with overcommit hints\n"
3662     "                mem-lock=on|off controls memory lock support (default: off)\n"
3663     "                cpu-pm=on|off controls cpu power management (default: off)\n",
3664     QEMU_ARCH_ALL)
3665 STEXI
3666 @item -overcommit mem-lock=on|off
3667 @item -overcommit cpu-pm=on|off
3668 @findex -overcommit
3669 Run qemu with hints about host resource overcommit. The default is
3670 to assume that host overcommits all resources.
3671
3672 Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3673 by default).  This works when host memory is not overcommitted and reduces the
3674 worst-case latency for guest.  This is equivalent to @option{realtime}.
3675
3676 Guest ability to manage power state of host cpus (increasing latency for other
3677 processes on the same host cpu, but decreasing latency for guest) can be
3678 enabled via @option{cpu-pm=on} (disabled by default).  This works best when
3679 host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3680 utilization will be incorrect, not taking into account guest idle time.
3681 ETEXI
3682
3683 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3684     "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
3685 STEXI
3686 @item -gdb @var{dev}
3687 @findex -gdb
3688 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3689 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3690 stdio are reasonable use case. The latter is allowing to start QEMU from
3691 within gdb and establish the connection via a pipe:
3692 @example
3693 (gdb) target remote | exec @value{qemu_system} -gdb stdio ...
3694 @end example
3695 ETEXI
3696
3697 DEF("s", 0, QEMU_OPTION_s, \
3698     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3699     QEMU_ARCH_ALL)
3700 STEXI
3701 @item -s
3702 @findex -s
3703 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3704 (@pxref{gdb_usage}).
3705 ETEXI
3706
3707 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3708     "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
3709     QEMU_ARCH_ALL)
3710 STEXI
3711 @item -d @var{item1}[,...]
3712 @findex -d
3713 Enable logging of specified items. Use '-d help' for a list of log items.
3714 ETEXI
3715
3716 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3717     "-D logfile      output log to logfile (default stderr)\n",
3718     QEMU_ARCH_ALL)
3719 STEXI
3720 @item -D @var{logfile}
3721 @findex -D
3722 Output log in @var{logfile} instead of to stderr
3723 ETEXI
3724
3725 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3726     "-dfilter range,..  filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3727     QEMU_ARCH_ALL)
3728 STEXI
3729 @item -dfilter @var{range1}[,...]
3730 @findex -dfilter
3731 Filter debug output to that relevant to a range of target addresses. The filter
3732 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3733 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3734 addresses and sizes required. For example:
3735 @example
3736     -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3737 @end example
3738 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3739 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3740 block starting at 0xffffffc00005f000.
3741 ETEXI
3742
3743 DEF("seed", HAS_ARG, QEMU_OPTION_seed, \
3744     "-seed number       seed the pseudo-random number generator\n",
3745     QEMU_ARCH_ALL)
3746 STEXI
3747 @item -seed @var{number}
3748 @findex -seed
3749 Force the guest to use a deterministic pseudo-random number generator, seeded
3750 with @var{number}.  This does not affect crypto routines within the host.
3751 ETEXI
3752
3753 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3754     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
3755     QEMU_ARCH_ALL)
3756 STEXI
3757 @item -L  @var{path}
3758 @findex -L
3759 Set the directory for the BIOS, VGA BIOS and keymaps.
3760
3761 To list all the data directories, use @code{-L help}.
3762 ETEXI
3763
3764 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3765     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
3766 STEXI
3767 @item -bios @var{file}
3768 @findex -bios
3769 Set the filename for the BIOS.
3770 ETEXI
3771
3772 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3773     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3774 STEXI
3775 @item -enable-kvm
3776 @findex -enable-kvm
3777 Enable KVM full virtualization support. This option is only available
3778 if KVM support is enabled when compiling.
3779 ETEXI
3780
3781 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3782     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
3783 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3784     "-xen-attach     attach to existing xen domain\n"
3785     "                libxl will use this when starting QEMU\n",
3786     QEMU_ARCH_ALL)
3787 DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3788     "-xen-domid-restrict     restrict set of available xen operations\n"
3789     "                        to specified domain id. (Does not affect\n"
3790     "                        xenpv machine type).\n",
3791     QEMU_ARCH_ALL)
3792 STEXI
3793 @item -xen-domid @var{id}
3794 @findex -xen-domid
3795 Specify xen guest domain @var{id} (XEN only).
3796 @item -xen-attach
3797 @findex -xen-attach
3798 Attach to existing xen domain.
3799 libxl will use this when starting QEMU (XEN only).
3800 @findex -xen-domid-restrict
3801 Restrict set of available xen operations to specified domain id (XEN only).
3802 ETEXI
3803
3804 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3805     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
3806 STEXI
3807 @item -no-reboot
3808 @findex -no-reboot
3809 Exit instead of rebooting.
3810 ETEXI
3811
3812 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3813     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
3814 STEXI
3815 @item -no-shutdown
3816 @findex -no-shutdown
3817 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3818 This allows for instance switching to monitor to commit changes to the
3819 disk image.
3820 ETEXI
3821
3822 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3823     "-loadvm [tag|id]\n" \
3824     "                start right away with a saved state (loadvm in monitor)\n",
3825     QEMU_ARCH_ALL)
3826 STEXI
3827 @item -loadvm @var{file}
3828 @findex -loadvm
3829 Start right away with a saved state (@code{loadvm} in monitor)
3830 ETEXI
3831
3832 #ifndef _WIN32
3833 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3834     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3835 #endif
3836 STEXI
3837 @item -daemonize
3838 @findex -daemonize
3839 Daemonize the QEMU process after initialization.  QEMU will not detach from
3840 standard IO until it is ready to receive connections on any of its devices.
3841 This option is a useful way for external programs to launch QEMU without having
3842 to cope with initialization race conditions.
3843 ETEXI
3844
3845 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3846     "-option-rom rom load a file, rom, into the option ROM space\n",
3847     QEMU_ARCH_ALL)
3848 STEXI
3849 @item -option-rom @var{file}
3850 @findex -option-rom
3851 Load the contents of @var{file} as an option ROM.
3852 This option is useful to load things like EtherBoot.
3853 ETEXI
3854
3855 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3856     "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3857     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3858     QEMU_ARCH_ALL)
3859
3860 STEXI
3861
3862 @item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
3863 @findex -rtc
3864 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3865 UTC or local time, respectively. @code{localtime} is required for correct date in
3866 MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
3867 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3868
3869 By default the RTC is driven by the host system time. This allows using of the
3870 RTC as accurate reference clock inside the guest, specifically if the host
3871 time is smoothly following an accurate external reference clock, e.g. via NTP.