qxl: check release info object
[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     "                kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
36     "                vmport=on|off|auto controls emulation of vmport (default: auto)\n"
37     "                kvm_shadow_mem=size of KVM shadow MMU in bytes\n"
38     "                dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
39     "                mem-merge=on|off controls memory merge support (default: on)\n"
40     "                igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
41     "                aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
42     "                dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
43     "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
44     "                nvdimm=on|off controls NVDIMM support (default=off)\n"
45     "                enforce-config-section=on|off enforce configuration section migration (default=off)\n"
46     "                memory-encryption=@var{} memory encryption object to use (default=none)\n",
47     QEMU_ARCH_ALL)
48 STEXI
49 @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
50 @findex -machine
51 Select the emulated machine by @var{name}. Use @code{-machine help} to list
52 available machines.
53
54 For architectures which aim to support live migration compatibility
55 across releases, each release will introduce a new versioned machine
56 type. For example, the 2.8.0 release introduced machine types
57 ``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
58
59 To allow live migration of guests from QEMU version 2.8.0, to QEMU
60 version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
61 and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
62 to skip multiple intermediate releases when upgrading, new releases
63 of QEMU will support machine types from many previous versions.
64
65 Supported machine properties are:
66 @table @option
67 @item accel=@var{accels1}[:@var{accels2}[:...]]
68 This is used to enable an accelerator. Depending on the target architecture,
69 kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
70 more than one accelerator specified, the next one is used if the previous one
71 fails to initialize.
72 @item kernel_irqchip=on|off
73 Controls in-kernel irqchip support for the chosen accelerator when available.
74 @item gfx_passthru=on|off
75 Enables IGD GFX passthrough support for the chosen machine when available.
76 @item vmport=on|off|auto
77 Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
78 value based on accel. For accel=xen the default is off otherwise the default
79 is on.
80 @item kvm_shadow_mem=size
81 Defines the size of the KVM shadow MMU.
82 @item dump-guest-core=on|off
83 Include guest memory in a core dump. The default is on.
84 @item mem-merge=on|off
85 Enables or disables memory merge support. This feature, when supported by
86 the host, de-duplicates identical memory pages among VMs instances
87 (enabled by default).
88 @item aes-key-wrap=on|off
89 Enables or disables AES key wrapping support on s390-ccw hosts. This feature
90 controls whether AES wrapping keys will be created to allow
91 execution of AES cryptographic functions.  The default is on.
92 @item dea-key-wrap=on|off
93 Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
94 controls whether DEA wrapping keys will be created to allow
95 execution of DEA cryptographic functions.  The default is on.
96 @item nvdimm=on|off
97 Enables or disables NVDIMM support. The default is off.
98 @item enforce-config-section=on|off
99 If @option{enforce-config-section} is set to @var{on}, force migration
100 code to send configuration section even if the machine-type sets the
101 @option{migration.send-configuration} property to @var{off}.
102 NOTE: this parameter is deprecated. Please use @option{-global}
103 @option{migration.send-configuration}=@var{on|off} instead.
104 @item memory-encryption=@var{}
105 Memory encryption object to use. The default is none.
106 @end table
107 ETEXI
108
109 HXCOMM Deprecated by -machine
110 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
111
112 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
113     "-cpu cpu        select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
114 STEXI
115 @item -cpu @var{model}
116 @findex -cpu
117 Select CPU model (@code{-cpu help} for list and additional feature selection)
118 ETEXI
119
120 DEF("accel", HAS_ARG, QEMU_OPTION_accel,
121     "-accel [accel=]accelerator[,thread=single|multi]\n"
122     "                select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
123     "                thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
124 STEXI
125 @item -accel @var{name}[,prop=@var{value}[,...]]
126 @findex -accel
127 This is used to enable an accelerator. Depending on the target architecture,
128 kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
129 more than one accelerator specified, the next one is used if the previous one
130 fails to initialize.
131 @table @option
132 @item thread=single|multi
133 Controls number of TCG threads. When the TCG is multi-threaded there will be one
134 thread per vCPU therefor taking advantage of additional host cores. The default
135 is to enable multi-threading where both the back-end and front-ends support it and
136 no incompatible TCG features have been enabled (e.g. icount/replay).
137 @end table
138 ETEXI
139
140 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
141     "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
142     "                set the number of CPUs to 'n' [default=1]\n"
143     "                maxcpus= maximum number of total cpus, including\n"
144     "                offline CPUs for hotplug, etc\n"
145     "                cores= number of CPU cores on one socket\n"
146     "                threads= number of threads on one CPU core\n"
147     "                sockets= number of discrete sockets in the system\n",
148         QEMU_ARCH_ALL)
149 STEXI
150 @item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
151 @findex -smp
152 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
153 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
154 to 4.
155 For the PC target, the number of @var{cores} per socket, the number
156 of @var{threads} per cores and the total number of @var{sockets} can be
157 specified. Missing values will be computed. If any on the three values is
158 given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
159 specifies the maximum number of hotpluggable CPUs.
160 ETEXI
161
162 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
163     "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
164     "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
165     "-numa dist,src=source,dst=destination,val=distance\n"
166     "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n",
167     QEMU_ARCH_ALL)
168 STEXI
169 @item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
170 @itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
171 @itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
172 @itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
173 @findex -numa
174 Define a NUMA node and assign RAM and VCPUs to it.
175 Set the NUMA distance from a source node to a destination node.
176
177 Legacy VCPU assignment uses @samp{cpus} option where
178 @var{firstcpu} and @var{lastcpu} are CPU indexes. Each
179 @samp{cpus} option represent a contiguous range of CPU indexes
180 (or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
181 set of VCPUs can be represented by providing multiple @samp{cpus}
182 options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
183 split between them.
184
185 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
186 a NUMA node:
187 @example
188 -numa node,cpus=0-2,cpus=5
189 @end example
190
191 @samp{cpu} option is a new alternative to @samp{cpus} option
192 which uses @samp{socket-id|core-id|thread-id} properties to assign
193 CPU objects to a @var{node} using topology layout properties of CPU.
194 The set of properties is machine specific, and depends on used
195 machine type/@samp{smp} options. It could be queried with
196 @samp{hotpluggable-cpus} monitor command.
197 @samp{node-id} property specifies @var{node} to which CPU object
198 will be assigned, it's required for @var{node} to be declared
199 with @samp{node} option before it's used with @samp{cpu} option.
200
201 For example:
202 @example
203 -M pc \
204 -smp 1,sockets=2,maxcpus=2 \
205 -numa node,nodeid=0 -numa node,nodeid=1 \
206 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
207 @end example
208
209 @samp{mem} assigns a given RAM amount to a node. @samp{memdev}
210 assigns RAM from a given memory backend device to a node. If
211 @samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
212 split equally between them.
213
214 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
215 if one node uses @samp{memdev}, all of them have to use it.
216
217 @var{source} and @var{destination} are NUMA node IDs.
218 @var{distance} is the NUMA distance from @var{source} to @var{destination}.
219 The distance from a node to itself is always 10. If any pair of nodes is
220 given a distance, then all pairs must be given distances. Although, when
221 distances are only given in one direction for each pair of nodes, then
222 the distances in the opposite directions are assumed to be the same. If,
223 however, an asymmetrical pair of distances is given for even one node
224 pair, then all node pairs must be provided distance values for both
225 directions, even when they are symmetrical. When a node is unreachable
226 from another node, set the pair's distance to 255.
227
228 Note that the -@option{numa} option doesn't allocate any of the
229 specified resources, it just assigns existing resources to NUMA
230 nodes. This means that one still has to use the @option{-m},
231 @option{-smp} options to allocate RAM and VCPUs respectively.
232
233 ETEXI
234
235 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
236     "-add-fd fd=fd,set=set[,opaque=opaque]\n"
237     "                Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
238 STEXI
239 @item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
240 @findex -add-fd
241
242 Add a file descriptor to an fd set.  Valid options are:
243
244 @table @option
245 @item fd=@var{fd}
246 This option defines the file descriptor of which a duplicate is added to fd set.
247 The file descriptor cannot be stdin, stdout, or stderr.
248 @item set=@var{set}
249 This option defines the ID of the fd set to add the file descriptor to.
250 @item opaque=@var{opaque}
251 This option defines a free-form string that can be used to describe @var{fd}.
252 @end table
253
254 You can open an image using pre-opened file descriptors from an fd set:
255 @example
256 qemu-system-i386
257 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
258 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
259 -drive file=/dev/fdset/2,index=0,media=disk
260 @end example
261 ETEXI
262
263 DEF("set", HAS_ARG, QEMU_OPTION_set,
264     "-set group.id.arg=value\n"
265     "                set <arg> parameter for item <id> of type <group>\n"
266     "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
267 STEXI
268 @item -set @var{group}.@var{id}.@var{arg}=@var{value}
269 @findex -set
270 Set parameter @var{arg} for item @var{id} of type @var{group}
271 ETEXI
272
273 DEF("global", HAS_ARG, QEMU_OPTION_global,
274     "-global driver.property=value\n"
275     "-global driver=driver,property=property,value=value\n"
276     "                set a global default for a driver property\n",
277     QEMU_ARCH_ALL)
278 STEXI
279 @item -global @var{driver}.@var{prop}=@var{value}
280 @itemx -global driver=@var{driver},property=@var{property},value=@var{value}
281 @findex -global
282 Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
283
284 @example
285 qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
286 @end example
287
288 In particular, you can use this to set driver properties for devices which are
289 created automatically by the machine model. To create a device which is not
290 created automatically and set properties on it, use -@option{device}.
291
292 -global @var{driver}.@var{prop}=@var{value} is shorthand for -global
293 driver=@var{driver},property=@var{prop},value=@var{value}.  The
294 longhand syntax works even when @var{driver} contains a dot.
295 ETEXI
296
297 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
298     "-boot [order=drives][,once=drives][,menu=on|off]\n"
299     "      [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
300     "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
301     "                'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
302     "                'sp_time': the period that splash picture last if menu=on, unit is ms\n"
303     "                'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
304     QEMU_ARCH_ALL)
305 STEXI
306 @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]
307 @findex -boot
308 Specify boot order @var{drives} as a string of drive letters. Valid
309 drive letters depend on the target architecture. The x86 PC uses: a, b
310 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
311 from network adapter 1-4), hard disk boot is the default. To apply a
312 particular boot order only on the first startup, specify it via
313 @option{once}. Note that the @option{order} or @option{once} parameter
314 should not be used together with the @option{bootindex} property of
315 devices, since the firmware implementations normally do not support both
316 at the same time.
317
318 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
319 as firmware/BIOS supports them. The default is non-interactive boot.
320
321 A splash picture could be passed to bios, enabling user to show it as logo,
322 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
323 supports them. Currently Seabios for X86 system support it.
324 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
325 format(true color). The resolution should be supported by the SVGA mode, so
326 the recommended is 320x240, 640x480, 800x640.
327
328 A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
329 when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
330 reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
331 system support it.
332
333 Do strict boot via @option{strict=on} as far as firmware/BIOS
334 supports it. This only effects when boot priority is changed by
335 bootindex options. The default is non-strict boot.
336
337 @example
338 # try to boot from network first, then from hard disk
339 qemu-system-i386 -boot order=nc
340 # boot from CD-ROM first, switch back to default order after reboot
341 qemu-system-i386 -boot once=d
342 # boot with a splash picture for 5 seconds.
343 qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
344 @end example
345
346 Note: The legacy format '-boot @var{drives}' is still supported but its
347 use is discouraged as it may be removed from future versions.
348 ETEXI
349
350 DEF("m", HAS_ARG, QEMU_OPTION_m,
351     "-m [size=]megs[,slots=n,maxmem=size]\n"
352     "                configure guest RAM\n"
353     "                size: initial amount of guest memory\n"
354     "                slots: number of hotplug slots (default: none)\n"
355     "                maxmem: maximum amount of guest memory (default: none)\n"
356     "NOTE: Some architectures might enforce a specific granularity\n",
357     QEMU_ARCH_ALL)
358 STEXI
359 @item -m [size=]@var{megs}[,slots=n,maxmem=size]
360 @findex -m
361 Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
362 Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
363 megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
364 could be used to set amount of hotpluggable memory slots and maximum amount of
365 memory. Note that @var{maxmem} must be aligned to the page size.
366
367 For example, the following command-line sets the guest startup RAM size to
368 1GB, creates 3 slots to hotplug additional memory and sets the maximum
369 memory the guest can reach to 4GB:
370
371 @example
372 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
373 @end example
374
375 If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
376 be enabled and the guest startup RAM will never increase.
377 ETEXI
378
379 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
380     "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
381 STEXI
382 @item -mem-path @var{path}
383 @findex -mem-path
384 Allocate guest RAM from a temporarily created file in @var{path}.
385 ETEXI
386
387 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
388     "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
389     QEMU_ARCH_ALL)
390 STEXI
391 @item -mem-prealloc
392 @findex -mem-prealloc
393 Preallocate memory when using -mem-path.
394 ETEXI
395
396 DEF("k", HAS_ARG, QEMU_OPTION_k,
397     "-k language     use keyboard layout (for example 'fr' for French)\n",
398     QEMU_ARCH_ALL)
399 STEXI
400 @item -k @var{language}
401 @findex -k
402 Use keyboard layout @var{language} (for example @code{fr} for
403 French). This option is only needed where it is not easy to get raw PC
404 keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
405 display). You don't normally need to use it on PC/Linux or PC/Windows
406 hosts.
407
408 The available layouts are:
409 @example
410 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
411 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
412 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
413 @end example
414
415 The default is @code{en-us}.
416 ETEXI
417
418
419 HXCOMM Deprecated by -audiodev
420 DEF("audio-help", 0, QEMU_OPTION_audio_help,
421     "-audio-help     show -audiodev equivalent of the currently specified audio settings\n",
422     QEMU_ARCH_ALL)
423 STEXI
424 @item -audio-help
425 @findex -audio-help
426 Will show the -audiodev equivalent of the currently specified
427 (deprecated) environment variables.
428 ETEXI
429
430 DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
431     "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
432     "                specifies the audio backend to use\n"
433     "                id= identifier of the backend\n"
434     "                timer-period= timer period in microseconds\n"
435     "                in|out.fixed-settings= use fixed settings for host audio\n"
436     "                in|out.frequency= frequency to use with fixed settings\n"
437     "                in|out.channels= number of channels to use with fixed settings\n"
438     "                in|out.format= sample format to use with fixed settings\n"
439     "                valid values: s8, s16, s32, u8, u16, u32\n"
440     "                in|out.voices= number of voices to use\n"
441     "                in|out.buffer-len= length of buffer in microseconds\n"
442     "-audiodev none,id=id,[,prop[=value][,...]]\n"
443     "                dummy driver that discards all output\n"
444 #ifdef CONFIG_AUDIO_ALSA
445     "-audiodev alsa,id=id[,prop[=value][,...]]\n"
446     "                in|out.dev= name of the audio device to use\n"
447     "                in|out.period-len= length of period in microseconds\n"
448     "                in|out.try-poll= attempt to use poll mode\n"
449     "                threshold= threshold (in microseconds) when playback starts\n"
450 #endif
451 #ifdef CONFIG_AUDIO_COREAUDIO
452     "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
453     "                in|out.buffer-count= number of buffers\n"
454 #endif
455 #ifdef CONFIG_AUDIO_DSOUND
456     "-audiodev dsound,id=id[,prop[=value][,...]]\n"
457     "                latency= add extra latency to playback in microseconds\n"
458 #endif
459 #ifdef CONFIG_AUDIO_OSS
460     "-audiodev oss,id=id[,prop[=value][,...]]\n"
461     "                in|out.dev= path of the audio device to use\n"
462     "                in|out.buffer-count= number of buffers\n"
463     "                in|out.try-poll= attempt to use poll mode\n"
464     "                try-mmap= try using memory mapped access\n"
465     "                exclusive= open device in exclusive mode\n"
466     "                dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
467 #endif
468 #ifdef CONFIG_AUDIO_PA
469     "-audiodev pa,id=id[,prop[=value][,...]]\n"
470     "                server= PulseAudio server address\n"
471     "                in|out.name= source/sink device name\n"
472 #endif
473 #ifdef CONFIG_AUDIO_SDL
474     "-audiodev sdl,id=id[,prop[=value][,...]]\n"
475 #endif
476 #ifdef CONFIG_SPICE
477     "-audiodev spice,id=id[,prop[=value][,...]]\n"
478 #endif
479     "-audiodev wav,id=id[,prop[=value][,...]]\n"
480     "                path= path of wav file to record\n",
481     QEMU_ARCH_ALL)
482 STEXI
483 @item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]]
484 @findex -audiodev
485 Adds a new audio backend @var{driver} identified by @var{id}.  There are
486 global and driver specific properties.  Some values can be set
487 differently for input and output, they're marked with @code{in|out.}.
488 You can set the input's property with @code{in.@var{prop}} and the
489 output's property with @code{out.@var{prop}}. For example:
490 @example
491 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
492 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
493 @end example
494
495 Valid global options are:
496
497 @table @option
498 @item id=@var{identifier}
499 Identifies the audio backend.
500
501 @item timer-period=@var{period}
502 Sets the timer @var{period} used by the audio subsystem in microseconds.
503 Default is 10000 (10 ms).
504
505 @item in|out.fixed-settings=on|off
506 Use fixed settings for host audio.  When off, it will change based on
507 how the guest opens the sound card.  In this case you must not specify
508 @var{frequency}, @var{channels} or @var{format}.  Default is on.
509
510 @item in|out.frequency=@var{frequency}
511 Specify the @var{frequency} to use when using @var{fixed-settings}.
512 Default is 44100Hz.
513
514 @item in|out.channels=@var{channels}
515 Specify the number of @var{channels} to use when using
516 @var{fixed-settings}. Default is 2 (stereo).
517
518 @item in|out.format=@var{format}
519 Specify the sample @var{format} to use when using @var{fixed-settings}.
520 Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
521 @code{u16}, @code{u32}. Default is @code{s16}.
522
523 @item in|out.voices=@var{voices}
524 Specify the number of @var{voices} to use.  Default is 1.
525
526 @item in|out.buffer=@var{usecs}
527 Sets the size of the buffer in microseconds.
528
529 @end table
530
531 @item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]]
532 Creates a dummy backend that discards all outputs.  This backend has no
533 backend specific properties.
534
535 @item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
536 Creates backend using the ALSA.  This backend is only available on
537 Linux.
538
539 ALSA specific options are:
540
541 @table @option
542
543 @item in|out.dev=@var{device}
544 Specify the ALSA @var{device} to use for input and/or output.  Default
545 is @code{default}.
546
547 @item in|out.period-len=@var{usecs}
548 Sets the period length in microseconds.
549
550 @item in|out.try-poll=on|off
551 Attempt to use poll mode with the device.  Default is on.
552
553 @item threshold=@var{threshold}
554 Threshold (in microseconds) when playback starts.  Default is 0.
555
556 @end table
557
558 @item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]]
559 Creates a backend using Apple's Core Audio.  This backend is only
560 available on Mac OS and only supports playback.
561
562 Core Audio specific options are:
563
564 @table @option
565
566 @item in|out.buffer-count=@var{count}
567 Sets the @var{count} of the buffers.
568
569 @end table
570
571 @item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]]
572 Creates a backend using Microsoft's DirectSound.  This backend is only
573 available on Windows and only supports playback.
574
575 DirectSound specific options are:
576
577 @table @option
578
579 @item latency=@var{usecs}
580 Add extra @var{usecs} microseconds latency to playback.  Default is
581 10000 (10 ms).
582
583 @end table
584
585 @item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]]
586 Creates a backend using OSS.  This backend is available on most
587 Unix-like systems.
588
589 OSS specific options are:
590
591 @table @option
592
593 @item in|out.dev=@var{device}
594 Specify the file name of the OSS @var{device} to use.  Default is
595 @code{/dev/dsp}.
596
597 @item in|out.buffer-count=@var{count}
598 Sets the @var{count} of the buffers.
599
600 @item in|out.try-poll=on|of
601 Attempt to use poll mode with the device.  Default is on.
602
603 @item try-mmap=on|off
604 Try using memory mapped device access.  Default is off.
605
606 @item exclusive=on|off
607 Open the device in exclusive mode (vmix won't work in this case).
608 Default is off.
609
610 @item dsp-policy=@var{policy}
611 Sets the timing policy (between 0 and 10, where smaller number means
612 smaller latency but higher CPU usage).  Use -1 to use buffer sizes
613 specified by @code{buffer} and @code{buffer-count}.  This option is
614 ignored if you do not have OSS 4. Default is 5.
615
616 @end table
617
618 @item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
619 Creates a backend using PulseAudio.  This backend is available on most
620 systems.
621
622 PulseAudio specific options are:
623
624 @table @option
625
626 @item server=@var{server}
627 Sets the PulseAudio @var{server} to connect to.
628
629 @item in|out.name=@var{sink}
630 Use the specified source/sink for recording/playback.
631
632 @end table
633
634 @item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
635 Creates a backend using SDL.  This backend is available on most systems,
636 but you should use your platform's native backend if possible.  This
637 backend has no backend specific properties.
638
639 @item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]]
640 Creates a backend that sends audio through SPICE.  This backend requires
641 @code{-spice} and automatically selected in that case, so usually you
642 can ignore this option.  This backend has no backend specific
643 properties.
644
645 @item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
646 Creates a backend that writes audio to a WAV file.
647
648 Backend specific options are:
649
650 @table @option
651
652 @item path=@var{path}
653 Write recorded audio into the specified file.  Default is
654 @code{qemu.wav}.
655
656 @end table
657 ETEXI
658
659 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
660     "-soundhw c1,... enable audio support\n"
661     "                and only specified sound cards (comma separated list)\n"
662     "                use '-soundhw help' to get the list of supported cards\n"
663     "                use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
664 STEXI
665 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
666 @findex -soundhw
667 Enable audio and selected sound hardware. Use 'help' to print all
668 available sound hardware.
669
670 @example
671 qemu-system-i386 -soundhw sb16,adlib disk.img
672 qemu-system-i386 -soundhw es1370 disk.img
673 qemu-system-i386 -soundhw ac97 disk.img
674 qemu-system-i386 -soundhw hda disk.img
675 qemu-system-i386 -soundhw all disk.img
676 qemu-system-i386 -soundhw help
677 @end example
678
679 Note that Linux's i810_audio OSS kernel (for AC97) module might
680 require manually specifying clocking.
681
682 @example
683 modprobe i810_audio clocking=48000
684 @end example
685 ETEXI
686
687 DEF("device", HAS_ARG, QEMU_OPTION_device,
688     "-device driver[,prop[=value][,...]]\n"
689     "                add device (based on driver)\n"
690     "                prop=value,... sets driver properties\n"
691     "                use '-device help' to print all possible drivers\n"
692     "                use '-device driver,help' to print all possible properties\n",
693     QEMU_ARCH_ALL)
694 STEXI
695 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
696 @findex -device
697 Add device @var{driver}.  @var{prop}=@var{value} sets driver
698 properties.  Valid properties depend on the driver.  To get help on
699 possible drivers and properties, use @code{-device help} and
700 @code{-device @var{driver},help}.
701
702 Some drivers are:
703 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
704
705 Add an IPMI BMC.  This is a simulation of a hardware management
706 interface processor that normally sits on a system.  It provides
707 a watchdog and the ability to reset and power control the system.
708 You need to connect this to an IPMI interface to make it useful
709
710 The IPMI slave address to use for the BMC.  The default is 0x20.
711 This address is the BMC's address on the I2C network of management
712 controllers.  If you don't know what this means, it is safe to ignore
713 it.
714
715 @table @option
716 @item bmc=@var{id}
717 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
718 @item slave_addr=@var{val}
719 Define slave address to use for the BMC.  The default is 0x20.
720 @item sdrfile=@var{file}
721 file containing raw Sensor Data Records (SDR) data. The default is none.
722 @item fruareasize=@var{val}
723 size of a Field Replaceable Unit (FRU) area.  The default is 1024.
724 @item frudatafile=@var{file}
725 file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
726 @end table
727
728 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
729
730 Add a connection to an external IPMI BMC simulator.  Instead of
731 locally emulating the BMC like the above item, instead connect
732 to an external entity that provides the IPMI services.
733
734 A connection is made to an external BMC simulator.  If you do this, it
735 is strongly recommended that you use the "reconnect=" chardev option
736 to reconnect to the simulator if the connection is lost.  Note that if
737 this is not used carefully, it can be a security issue, as the
738 interface has the ability to send resets, NMIs, and power off the VM.
739 It's best if QEMU makes a connection to an external simulator running
740 on a secure port on localhost, so neither the simulator nor QEMU is
741 exposed to any outside network.
742
743 See the "lanserv/README.vm" file in the OpenIPMI library for more
744 details on the external interface.
745
746 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
747
748 Add a KCS IPMI interafce on the ISA bus.  This also adds a
749 corresponding ACPI and SMBIOS entries, if appropriate.
750
751 @table @option
752 @item bmc=@var{id}
753 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
754 @item ioport=@var{val}
755 Define the I/O address of the interface.  The default is 0xca0 for KCS.
756 @item irq=@var{val}
757 Define the interrupt to use.  The default is 5.  To disable interrupts,
758 set this to 0.
759 @end table
760
761 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
762
763 Like the KCS interface, but defines a BT interface.  The default port is
764 0xe4 and the default interrupt is 5.
765
766 ETEXI
767
768 DEF("name", HAS_ARG, QEMU_OPTION_name,
769     "-name string1[,process=string2][,debug-threads=on|off]\n"
770     "                set the name of the guest\n"
771     "                string1 sets the window title and string2 the process name\n"
772     "                When debug-threads is enabled, individual threads are given a separate name\n"
773     "                NOTE: The thread names are for debugging and not a stable API.\n",
774     QEMU_ARCH_ALL)
775 STEXI
776 @item -name @var{name}
777 @findex -name
778 Sets the @var{name} of the guest.
779 This name will be displayed in the SDL window caption.
780 The @var{name} will also be used for the VNC server.
781 Also optionally set the top visible process name in Linux.
782 Naming of individual threads can also be enabled on Linux to aid debugging.
783 ETEXI
784
785 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
786     "-uuid %08x-%04x-%04x-%04x-%012x\n"
787     "                specify machine UUID\n", QEMU_ARCH_ALL)
788 STEXI
789 @item -uuid @var{uuid}
790 @findex -uuid
791 Set system UUID.
792 ETEXI
793
794 STEXI
795 @end table
796 ETEXI
797 DEFHEADING()
798
799 DEFHEADING(Block device options:)
800 STEXI
801 @table @option
802 ETEXI
803
804 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
805     "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
806 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
807 STEXI
808 @item -fda @var{file}
809 @itemx -fdb @var{file}
810 @findex -fda
811 @findex -fdb
812 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
813 ETEXI
814
815 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
816     "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
817 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
818 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
819     "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
820 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
821 STEXI
822 @item -hda @var{file}
823 @itemx -hdb @var{file}
824 @itemx -hdc @var{file}
825 @itemx -hdd @var{file}
826 @findex -hda
827 @findex -hdb
828 @findex -hdc
829 @findex -hdd
830 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
831 ETEXI
832
833 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
834     "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
835     QEMU_ARCH_ALL)
836 STEXI
837 @item -cdrom @var{file}
838 @findex -cdrom
839 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
840 @option{-cdrom} at the same time). You can use the host CD-ROM by
841 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
842 ETEXI
843
844 DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
845     "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
846     "          [,cache.direct=on|off][,cache.no-flush=on|off]\n"
847     "          [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
848     "          [,driver specific parameters...]\n"
849     "                configure a block backend\n", QEMU_ARCH_ALL)
850 STEXI
851 @item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
852 @findex -blockdev
853
854 Define a new block driver node. Some of the options apply to all block drivers,
855 other options are only accepted for a specific block driver. See below for a
856 list of generic options and options for the most common block drivers.
857
858 Options that expect a reference to another node (e.g. @code{file}) can be
859 given in two ways. Either you specify the node name of an already existing node
860 (file=@var{node-name}), or you define a new node inline, adding options
861 for the referenced node after a dot (file.filename=@var{path},file.aio=native).
862
863 A block driver node created with @option{-blockdev} can be used for a guest
864 device by specifying its node name for the @code{drive} property in a
865 @option{-device} argument that defines a block device.
866
867 @table @option
868 @item Valid options for any block driver node:
869
870 @table @code
871 @item driver
872 Specifies the block driver to use for the given node.
873 @item node-name
874 This defines the name of the block driver node by which it will be referenced
875 later. The name must be unique, i.e. it must not match the name of a different
876 block driver node, or (if you use @option{-drive} as well) the ID of a drive.
877
878 If no node name is specified, it is automatically generated. The generated node
879 name is not intended to be predictable and changes between QEMU invocations.
880 For the top level, an explicit node name must be specified.
881 @item read-only
882 Open the node read-only. Guest write attempts will fail.
883 @item cache.direct
884 The host page cache can be avoided with @option{cache.direct=on}. This will
885 attempt to do disk IO directly to the guest's memory. QEMU may still perform an
886 internal copy of the data.
887 @item cache.no-flush
888 In case you don't care about data integrity over host failures, you can use
889 @option{cache.no-flush=on}. This option tells QEMU that it never needs to write
890 any data to the disk but can instead keep things in cache. If anything goes
891 wrong, like your host losing power, the disk storage getting disconnected
892 accidentally, etc. your image will most probably be rendered unusable.
893 @item discard=@var{discard}
894 @var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
895 whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
896 ignored or passed to the filesystem. Some machine types may not support
897 discard requests.
898 @item detect-zeroes=@var{detect-zeroes}
899 @var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
900 conversion of plain zero writes by the OS to driver specific optimized
901 zero write commands. You may even choose "unmap" if @var{discard} is set
902 to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
903 @end table
904
905 @item Driver-specific options for @code{file}
906
907 This is the protocol-level block driver for accessing regular files.
908
909 @table @code
910 @item filename
911 The path to the image file in the local filesystem
912 @item aio
913 Specifies the AIO backend (threads/native, default: threads)
914 @item locking
915 Specifies whether the image file is protected with Linux OFD / POSIX locks. The
916 default is to use the Linux Open File Descriptor API if available, otherwise no
917 lock is applied.  (auto/on/off, default: auto)
918 @end table
919 Example:
920 @example
921 -blockdev driver=file,node-name=disk,filename=disk.img
922 @end example
923
924 @item Driver-specific options for @code{raw}
925
926 This is the image format block driver for raw images. It is usually
927 stacked on top of a protocol level block driver such as @code{file}.
928
929 @table @code
930 @item file
931 Reference to or definition of the data source block driver node
932 (e.g. a @code{file} driver node)
933 @end table
934 Example 1:
935 @example
936 -blockdev driver=file,node-name=disk_file,filename=disk.img
937 -blockdev driver=raw,node-name=disk,file=disk_file
938 @end example
939 Example 2:
940 @example
941 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
942 @end example
943
944 @item Driver-specific options for @code{qcow2}
945
946 This is the image format block driver for qcow2 images. It is usually
947 stacked on top of a protocol level block driver such as @code{file}.
948
949 @table @code
950 @item file
951 Reference to or definition of the data source block driver node
952 (e.g. a @code{file} driver node)
953
954 @item backing
955 Reference to or definition of the backing file block device (default is taken
956 from the image file). It is allowed to pass @code{null} here in order to disable
957 the default backing file.
958
959 @item lazy-refcounts
960 Whether to enable the lazy refcounts feature (on/off; default is taken from the
961 image file)
962
963 @item cache-size
964 The maximum total size of the L2 table and refcount block caches in bytes
965 (default: the sum of l2-cache-size and refcount-cache-size)
966
967 @item l2-cache-size
968 The maximum size of the L2 table cache in bytes
969 (default: if cache-size is not specified - 32M on Linux platforms, and 8M on
970 non-Linux platforms; otherwise, as large as possible within the cache-size,
971 while permitting the requested or the minimal refcount cache size)
972
973 @item refcount-cache-size
974 The maximum size of the refcount block cache in bytes
975 (default: 4 times the cluster size; or if cache-size is specified, the part of
976 it which is not used for the L2 cache)
977
978 @item cache-clean-interval
979 Clean unused entries in the L2 and refcount caches. The interval is in seconds.
980 The default value is 600 on supporting platforms, and 0 on other platforms.
981 Setting it to 0 disables this feature.
982
983 @item pass-discard-request
984 Whether discard requests to the qcow2 device should be forwarded to the data
985 source (on/off; default: on if discard=unmap is specified, off otherwise)
986
987 @item pass-discard-snapshot
988 Whether discard requests for the data source should be issued when a snapshot
989 operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
990 default: on)
991
992 @item pass-discard-other
993 Whether discard requests for the data source should be issued on other
994 occasions where a cluster gets freed (on/off; default: off)
995
996 @item overlap-check
997 Which overlap checks to perform for writes to the image
998 (none/constant/cached/all; default: cached). For details or finer
999 granularity control refer to the QAPI documentation of @code{blockdev-add}.
1000 @end table
1001
1002 Example 1:
1003 @example
1004 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1005 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1006 @end example
1007 Example 2:
1008 @example
1009 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1010 @end example
1011
1012 @item Driver-specific options for other drivers
1013 Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
1014
1015 @end table
1016
1017 ETEXI
1018
1019 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
1020     "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
1021     "       [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
1022     "       [,snapshot=on|off][,rerror=ignore|stop|report]\n"
1023     "       [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
1024     "       [,readonly=on|off][,copy-on-read=on|off]\n"
1025     "       [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
1026     "       [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
1027     "       [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
1028     "       [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
1029     "       [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
1030     "       [[,iops_size=is]]\n"
1031     "       [[,group=g]]\n"
1032     "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
1033 STEXI
1034 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
1035 @findex -drive
1036
1037 Define a new drive. This includes creating a block driver node (the backend) as
1038 well as a guest device, and is mostly a shortcut for defining the corresponding
1039 @option{-blockdev} and @option{-device} options.
1040
1041 @option{-drive} accepts all options that are accepted by @option{-blockdev}. In
1042 addition, it knows the following options:
1043
1044 @table @option
1045 @item file=@var{file}
1046 This option defines which disk image (@pxref{disk_images}) to use with
1047 this drive. If the filename contains comma, you must double it
1048 (for instance, "file=my,,file" to use file "my,file").
1049
1050 Special files such as iSCSI devices can be specified using protocol
1051 specific URLs. See the section for "Device URL Syntax" for more information.
1052 @item if=@var{interface}
1053 This option defines on which type on interface the drive is connected.
1054 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
1055 @item bus=@var{bus},unit=@var{unit}
1056 These options define where is connected the drive by defining the bus number and
1057 the unit id.
1058 @item index=@var{index}
1059 This option defines where is connected the drive by using an index in the list
1060 of available connectors of a given interface type.
1061 @item media=@var{media}
1062 This option defines the type of the media: disk or cdrom.
1063 @item snapshot=@var{snapshot}
1064 @var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
1065 (see @option{-snapshot}).
1066 @item cache=@var{cache}
1067 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
1068 and controls how the host cache is used to access block data. This is a
1069 shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
1070 options (as in @option{-blockdev}), and additionally @option{cache.writeback},
1071 which provides a default for the @option{write-cache} option of block guest
1072 devices (as in @option{-device}). The modes correspond to the following
1073 settings:
1074
1075 @c Our texi2pod.pl script doesn't support @multitable, so fall back to using
1076 @c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
1077 @c and the HTML output.
1078 @example
1079 @             │ cache.writeback   cache.direct   cache.no-flush
1080 ─────────────┼─────────────────────────────────────────────────
1081 writeback    │ on                off            off
1082 none         │ on                on             off
1083 writethrough │ off               off            off
1084 directsync   │ off               on             off
1085 unsafe       │ on                off            on
1086 @end example
1087
1088 The default mode is @option{cache=writeback}.
1089
1090 @item aio=@var{aio}
1091 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
1092 @item format=@var{format}
1093 Specify which disk @var{format} will be used rather than detecting
1094 the format.  Can be used to specify format=raw to avoid interpreting
1095 an untrusted format header.
1096 @item werror=@var{action},rerror=@var{action}
1097 Specify which @var{action} to take on write and read errors. Valid actions are:
1098 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
1099 "report" (report the error to the guest), "enospc" (pause QEMU only if the
1100 host disk is full; report the error to the guest otherwise).
1101 The default setting is @option{werror=enospc} and @option{rerror=report}.
1102 @item copy-on-read=@var{copy-on-read}
1103 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
1104 file sectors into the image file.
1105 @item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
1106 Specify bandwidth throttling limits in bytes per second, either for all request
1107 types or for reads or writes only.  Small values can lead to timeouts or hangs
1108 inside the guest.  A safe minimum for disks is 2 MB/s.
1109 @item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
1110 Specify bursts in bytes per second, either for all request types or for reads
1111 or writes only.  Bursts allow the guest I/O to spike above the limit
1112 temporarily.
1113 @item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
1114 Specify request rate limits in requests per second, either for all request
1115 types or for reads or writes only.
1116 @item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
1117 Specify bursts in requests per second, either for all request types or for reads
1118 or writes only.  Bursts allow the guest I/O to spike above the limit
1119 temporarily.
1120 @item iops_size=@var{is}
1121 Let every @var{is} bytes of a request count as a new request for iops
1122 throttling purposes.  Use this option to prevent guests from circumventing iops
1123 limits by sending fewer but larger requests.
1124 @item group=@var{g}
1125 Join a throttling quota group with given name @var{g}.  All drives that are
1126 members of the same group are accounted for together.  Use this option to
1127 prevent guests from circumventing throttling limits by using many small disks
1128 instead of a single larger disk.
1129 @end table
1130
1131 By default, the @option{cache.writeback=on} mode is used. It will report data
1132 writes as completed as soon as the data is present in the host page cache.
1133 This is safe as long as your guest OS makes sure to correctly flush disk caches
1134 where needed. If your guest OS does not handle volatile disk write caches
1135 correctly and your host crashes or loses power, then the guest may experience
1136 data corruption.
1137
1138 For such guests, you should consider using @option{cache.writeback=off}. This
1139 means that the host page cache will be used to read and write data, but write
1140 notification will be sent to the guest only after QEMU has made sure to flush
1141 each write to the disk. Be aware that this has a major impact on performance.
1142
1143 When using the @option{-snapshot} option, unsafe caching is always used.
1144
1145 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
1146 useful when the backing file is over a slow network.  By default copy-on-read
1147 is off.
1148
1149 Instead of @option{-cdrom} you can use:
1150 @example
1151 qemu-system-i386 -drive file=file,index=2,media=cdrom
1152 @end example
1153
1154 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
1155 use:
1156 @example
1157 qemu-system-i386 -drive file=file,index=0,media=disk
1158 qemu-system-i386 -drive file=file,index=1,media=disk
1159 qemu-system-i386 -drive file=file,index=2,media=disk
1160 qemu-system-i386 -drive file=file,index=3,media=disk
1161 @end example
1162
1163 You can open an image using pre-opened file descriptors from an fd set:
1164 @example
1165 qemu-system-i386
1166 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
1167 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
1168 -drive file=/dev/fdset/2,index=0,media=disk
1169 @end example
1170
1171 You can connect a CDROM to the slave of ide0:
1172 @example
1173 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
1174 @end example
1175
1176 If you don't specify the "file=" argument, you define an empty drive:
1177 @example
1178 qemu-system-i386 -drive if=ide,index=1,media=cdrom
1179 @end example
1180
1181 Instead of @option{-fda}, @option{-fdb}, you can use:
1182 @example
1183 qemu-system-i386 -drive file=file,index=0,if=floppy
1184 qemu-system-i386 -drive file=file,index=1,if=floppy
1185 @end example
1186
1187 By default, @var{interface} is "ide" and @var{index} is automatically
1188 incremented:
1189 @example
1190 qemu-system-i386 -drive file=a -drive file=b"
1191 @end example
1192 is interpreted like:
1193 @example
1194 qemu-system-i386 -hda a -hdb b
1195 @end example
1196 ETEXI
1197
1198 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
1199     "-mtdblock file  use 'file' as on-board Flash memory image\n",
1200     QEMU_ARCH_ALL)
1201 STEXI
1202 @item -mtdblock @var{file}
1203 @findex -mtdblock
1204 Use @var{file} as on-board Flash memory image.
1205 ETEXI
1206
1207 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
1208     "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
1209 STEXI
1210 @item -sd @var{file}
1211 @findex -sd
1212 Use @var{file} as SecureDigital card image.
1213 ETEXI
1214
1215 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
1216     "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
1217 STEXI
1218 @item -pflash @var{file}
1219 @findex -pflash
1220 Use @var{file} as a parallel flash image.
1221 ETEXI
1222
1223 DEF("snapshot", 0, QEMU_OPTION_snapshot,
1224     "-snapshot       write to temporary files instead of disk image files\n",
1225     QEMU_ARCH_ALL)
1226 STEXI
1227 @item -snapshot
1228 @findex -snapshot
1229 Write to temporary files instead of disk image files. In this case,
1230 the raw disk image you use is not written back. You can however force
1231 the write back by pressing @key{C-a s} (@pxref{disk_images}).
1232 ETEXI
1233
1234 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
1235     "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
1236     " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
1237     " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1238     " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1239     " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1240     " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1241     " [[,throttling.iops-size=is]]\n",
1242     QEMU_ARCH_ALL)
1243
1244 STEXI
1245
1246 @item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}]
1247 @findex -fsdev
1248 Define a new file system device. Valid options are:
1249 @table @option
1250 @item @var{fsdriver}
1251 This option specifies the fs driver backend to use.
1252 Currently "local" and "proxy" file system drivers are supported.
1253 @item id=@var{id}
1254 Specifies identifier for this device
1255 @item path=@var{path}
1256 Specifies the export path for the file system device. Files under
1257 this path will be available to the 9p client on the guest.
1258 @item security_model=@var{security_model}
1259 Specifies the security model to be used for this export path.
1260 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
1261 In "passthrough" security model, files are stored using the same
1262 credentials as they are created on the guest. This requires QEMU
1263 to run as root. In "mapped-xattr" security model, some of the file
1264 attributes like uid, gid, mode bits and link target are stored as
1265 file attributes. For "mapped-file" these attributes are stored in the
1266 hidden .virtfs_metadata directory. Directories exported by this security model cannot
1267 interact with other unix tools. "none" security model is same as
1268 passthrough except the sever won't report failures if it fails to
1269 set file attributes like ownership. Security model is mandatory
1270 only for local fsdriver. Other fsdrivers (like proxy) don't take
1271 security model as a parameter.
1272 @item writeout=@var{writeout}
1273 This is an optional argument. The only supported value is "immediate".
1274 This means that host page cache will be used to read and write data but
1275 write notification will be sent to the guest only when the data has been
1276 reported as written by the storage subsystem.
1277 @item readonly
1278 Enables exporting 9p share as a readonly mount for guests. By default
1279 read-write access is given.
1280 @item socket=@var{socket}
1281 Enables proxy filesystem driver to use passed socket file for communicating
1282 with virtfs-proxy-helper
1283 @item sock_fd=@var{sock_fd}
1284 Enables proxy filesystem driver to use passed socket descriptor for
1285 communicating with virtfs-proxy-helper. Usually a helper like libvirt
1286 will create socketpair and pass one of the fds as sock_fd
1287 @item fmode=@var{fmode}
1288 Specifies the default mode for newly created files on the host. Works only
1289 with security models "mapped-xattr" and "mapped-file".
1290 @item dmode=@var{dmode}
1291 Specifies the default mode for newly created directories on the host. Works
1292 only with security models "mapped-xattr" and "mapped-file".
1293 @end table
1294
1295 -fsdev option is used along with -device driver "virtio-9p-pci".
1296 @item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1297 Options for virtio-9p-pci driver are:
1298 @table @option
1299 @item fsdev=@var{id}
1300 Specifies the id value specified along with -fsdev option
1301 @item mount_tag=@var{mount_tag}
1302 Specifies the tag name to be used by the guest to mount this export point
1303 @end table
1304
1305 ETEXI
1306
1307 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
1308     "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
1309     "        [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
1310     QEMU_ARCH_ALL)
1311
1312 STEXI
1313
1314 @item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}]
1315 @findex -virtfs
1316
1317 The general form of a Virtual File system pass-through options are:
1318 @table @option
1319 @item @var{fsdriver}
1320 This option specifies the fs driver backend to use.
1321 Currently "local" and "proxy" file system drivers are supported.
1322 @item id=@var{id}
1323 Specifies identifier for this device
1324 @item path=@var{path}
1325 Specifies the export path for the file system device. Files under
1326 this path will be available to the 9p client on the guest.
1327 @item security_model=@var{security_model}
1328 Specifies the security model to be used for this export path.
1329 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
1330 In "passthrough" security model, files are stored using the same
1331 credentials as they are created on the guest. This requires QEMU
1332 to run as root. In "mapped-xattr" security model, some of the file
1333 attributes like uid, gid, mode bits and link target are stored as
1334 file attributes. For "mapped-file" these attributes are stored in the
1335 hidden .virtfs_metadata directory. Directories exported by this security model cannot
1336 interact with other unix tools. "none" security model is same as
1337 passthrough except the sever won't report failures if it fails to
1338 set file attributes like ownership. Security model is mandatory only
1339 for local fsdriver. Other fsdrivers (like proxy) don't take security
1340 model as a parameter.
1341 @item writeout=@var{writeout}
1342 This is an optional argument. The only supported value is "immediate".
1343 This means that host page cache will be used to read and write data but
1344 write notification will be sent to the guest only when the data has been
1345 reported as written by the storage subsystem.
1346 @item readonly
1347 Enables exporting 9p share as a readonly mount for guests. By default
1348 read-write access is given.
1349 @item socket=@var{socket}
1350 Enables proxy filesystem driver to use passed socket file for
1351 communicating with virtfs-proxy-helper. Usually a helper like libvirt
1352 will create socketpair and pass one of the fds as sock_fd
1353 @item sock_fd
1354 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1355 descriptor for interfacing with virtfs-proxy-helper
1356 @item fmode=@var{fmode}
1357 Specifies the default mode for newly created files on the host. Works only
1358 with security models "mapped-xattr" and "mapped-file".
1359 @item dmode=@var{dmode}
1360 Specifies the default mode for newly created directories on the host. Works
1361 only with security models "mapped-xattr" and "mapped-file".
1362 @end table
1363 ETEXI
1364
1365 DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1366     "-virtfs_synth Create synthetic file system image\n",
1367     QEMU_ARCH_ALL)
1368 STEXI
1369 @item -virtfs_synth
1370 @findex -virtfs_synth
1371 Create synthetic file system image
1372 ETEXI
1373
1374 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1375     "-iscsi [user=user][,password=password]\n"
1376     "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1377     "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1378     "       [,timeout=timeout]\n"
1379     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
1380
1381 STEXI
1382 @item -iscsi
1383 @findex -iscsi
1384 Configure iSCSI session parameters.
1385 ETEXI
1386
1387 STEXI
1388 @end table
1389 ETEXI
1390 DEFHEADING()
1391
1392 DEFHEADING(USB options:)
1393 STEXI
1394 @table @option
1395 ETEXI
1396
1397 DEF("usb", 0, QEMU_OPTION_usb,
1398     "-usb            enable the USB driver (if it is not used by default yet)\n",
1399     QEMU_ARCH_ALL)
1400 STEXI
1401 @item -usb
1402 @findex -usb
1403 Enable the USB driver (if it is not used by default yet).
1404 ETEXI
1405
1406 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1407     "-usbdevice name add the host or guest USB device 'name'\n",
1408     QEMU_ARCH_ALL)
1409 STEXI
1410
1411 @item -usbdevice @var{devname}
1412 @findex -usbdevice
1413 Add the USB device @var{devname}. Note that this option is deprecated,
1414 please use @code{-device usb-...} instead. @xref{usb_devices}.
1415
1416 @table @option
1417
1418 @item mouse
1419 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1420
1421 @item tablet
1422 Pointer device that uses absolute coordinates (like a touchscreen). This
1423 means QEMU is able to report the mouse position without having to grab the
1424 mouse. Also overrides the PS/2 mouse emulation when activated.
1425
1426 @item braille
1427 Braille device.  This will use BrlAPI to display the braille output on a real
1428 or fake device.
1429
1430 @end table
1431 ETEXI
1432
1433 STEXI
1434 @end table
1435 ETEXI
1436 DEFHEADING()
1437
1438 DEFHEADING(Display options:)
1439 STEXI
1440 @table @option
1441 ETEXI
1442
1443 DEF("display", HAS_ARG, QEMU_OPTION_display,
1444     "-display spice-app[,gl=on|off]\n"
1445     "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
1446     "            [,window_close=on|off][,gl=on|core|es|off]\n"
1447     "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1448     "-display vnc=<display>[,<optargs>]\n"
1449     "-display curses[,charset=<encoding>]\n"
1450     "-display none\n"
1451     "-display egl-headless[,rendernode=<file>]"
1452     "                select display type\n"
1453     "The default display is equivalent to\n"
1454 #if defined(CONFIG_GTK)
1455             "\t\"-display gtk\"\n"
1456 #elif defined(CONFIG_SDL)
1457             "\t\"-display sdl\"\n"
1458 #elif defined(CONFIG_COCOA)
1459             "\t\"-display cocoa\"\n"
1460 #elif defined(CONFIG_VNC)
1461             "\t\"-vnc localhost:0,to=99,id=default\"\n"
1462 #else
1463             "\t\"-display none\"\n"
1464 #endif
1465     , QEMU_ARCH_ALL)
1466 STEXI
1467 @item -display @var{type}
1468 @findex -display
1469 Select type of display to use. This option is a replacement for the
1470 old style -sdl/-curses/... options. Valid values for @var{type} are
1471 @table @option
1472 @item sdl
1473 Display video output via SDL (usually in a separate graphics
1474 window; see the SDL documentation for other possibilities).
1475 @item curses
1476 Display video output via curses. For graphics device models which
1477 support a text mode, QEMU can display this output using a
1478 curses/ncurses interface. Nothing is displayed when the graphics
1479 device is in graphical mode or if the graphics device does not support
1480 a text mode. Generally only the VGA device models support text mode.
1481 The font charset used by the guest can be specified with the
1482 @code{charset} option, for example @code{charset=CP850} for IBM CP850
1483 encoding. The default is @code{CP437}.
1484 @item none
1485 Do not display video output. The guest will still see an emulated
1486 graphics card, but its output will not be displayed to the QEMU
1487 user. This option differs from the -nographic option in that it
1488 only affects what is done with video output; -nographic also changes
1489 the destination of the serial and parallel port data.
1490 @item gtk
1491 Display video output in a GTK window. This interface provides drop-down
1492 menus and other UI elements to configure and control the VM during
1493 runtime.
1494 @item vnc
1495 Start a VNC server on display <arg>
1496 @item egl-headless
1497 Offload all OpenGL operations to a local DRI device. For any graphical display,
1498 this display needs to be paired with either VNC or SPICE displays.
1499 @item spice-app
1500 Start QEMU as a Spice server and launch the default Spice client
1501 application. The Spice server will redirect the serial consoles and
1502 QEMU monitors. (Since 4.0)
1503 @end table
1504 ETEXI
1505
1506 DEF("nographic", 0, QEMU_OPTION_nographic,
1507     "-nographic      disable graphical output and redirect serial I/Os to console\n",
1508     QEMU_ARCH_ALL)
1509 STEXI
1510 @item -nographic
1511 @findex -nographic
1512 Normally, if QEMU is compiled with graphical window support, it displays
1513 output such as guest graphics, guest console, and the QEMU monitor in a
1514 window. With this option, you can totally disable graphical output so
1515 that QEMU is a simple command line application. The emulated serial port
1516 is redirected on the console and muxed with the monitor (unless
1517 redirected elsewhere explicitly). Therefore, you can still use QEMU to
1518 debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1519 switching between the console and monitor.
1520 ETEXI
1521
1522 DEF("curses", 0, QEMU_OPTION_curses,
1523     "-curses         shorthand for -display curses\n",
1524     QEMU_ARCH_ALL)
1525 STEXI
1526 @item -curses
1527 @findex -curses
1528 Normally, if QEMU is compiled with graphical window support, it displays
1529 output such as guest graphics, guest console, and the QEMU monitor in a
1530 window. With this option, QEMU can display the VGA output when in text
1531 mode using a curses/ncurses interface. Nothing is displayed in graphical
1532 mode.
1533 ETEXI
1534
1535 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
1536     "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1537     QEMU_ARCH_ALL)
1538 STEXI
1539 @item -alt-grab
1540 @findex -alt-grab
1541 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1542 affects the special keys (for fullscreen, monitor-mode switching, etc).
1543 ETEXI
1544
1545 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
1546     "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1547     QEMU_ARCH_ALL)
1548 STEXI
1549 @item -ctrl-grab
1550 @findex -ctrl-grab
1551 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1552 affects the special keys (for fullscreen, monitor-mode switching, etc).
1553 ETEXI
1554
1555 DEF("no-quit", 0, QEMU_OPTION_no_quit,
1556     "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
1557 STEXI
1558 @item -no-quit
1559 @findex -no-quit
1560 Disable SDL window close capability.
1561 ETEXI
1562
1563 DEF("sdl", 0, QEMU_OPTION_sdl,
1564     "-sdl            shorthand for -display sdl\n", QEMU_ARCH_ALL)
1565 STEXI
1566 @item -sdl
1567 @findex -sdl
1568 Enable SDL.
1569 ETEXI
1570
1571 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
1572     "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1573     "       [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1574     "       [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
1575     "       [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
1576     "       [,tls-ciphers=<list>]\n"
1577     "       [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1578     "       [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1579     "       [,sasl][,password=<secret>][,disable-ticketing]\n"
1580     "       [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1581     "       [,jpeg-wan-compression=[auto|never|always]]\n"
1582     "       [,zlib-glz-wan-compression=[auto|never|always]]\n"
1583     "       [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
1584     "       [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1585     "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
1586     "       [,gl=[on|off]][,rendernode=<file>]\n"
1587     "   enable spice\n"
1588     "   at least one of {port, tls-port} is mandatory\n",
1589     QEMU_ARCH_ALL)
1590 STEXI
1591 @item -spice @var{option}[,@var{option}[,...]]
1592 @findex -spice
1593 Enable the spice remote desktop protocol. Valid options are
1594
1595 @table @option
1596
1597 @item port=<nr>
1598 Set the TCP port spice is listening on for plaintext channels.
1599
1600 @item addr=<addr>
1601 Set the IP address spice is listening on.  Default is any address.
1602
1603 @item ipv4
1604 @itemx ipv6
1605 @itemx unix
1606 Force using the specified IP version.
1607
1608 @item password=<secret>
1609 Set the password you need to authenticate.
1610
1611 @item sasl
1612 Require that the client use SASL to authenticate with the spice.
1613 The exact choice of authentication method used is controlled from the
1614 system / user's SASL configuration file for the 'qemu' service. This
1615 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1616 unprivileged user, an environment variable SASL_CONF_PATH can be used
1617 to make it search alternate locations for the service config.
1618 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1619 it is recommended that SASL always be combined with the 'tls' and
1620 'x509' settings to enable use of SSL and server certificates. This
1621 ensures a data encryption preventing compromise of authentication
1622 credentials.
1623
1624 @item disable-ticketing
1625 Allow client connects without authentication.
1626
1627 @item disable-copy-paste
1628 Disable copy paste between the client and the guest.
1629
1630 @item disable-agent-file-xfer
1631 Disable spice-vdagent based file-xfer between the client and the guest.
1632
1633 @item tls-port=<nr>
1634 Set the TCP port spice is listening on for encrypted channels.
1635
1636 @item x509-dir=<dir>
1637 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1638
1639 @item x509-key-file=<file>
1640 @itemx x509-key-password=<file>
1641 @itemx x509-cert-file=<file>
1642 @itemx x509-cacert-file=<file>
1643 @itemx x509-dh-key-file=<file>
1644 The x509 file names can also be configured individually.
1645
1646 @item tls-ciphers=<list>
1647 Specify which ciphers to use.
1648
1649 @item tls-channel=[main|display|cursor|inputs|record|playback]
1650 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
1651 Force specific channel to be used with or without TLS encryption.  The
1652 options can be specified multiple times to configure multiple
1653 channels.  The special name "default" can be used to set the default
1654 mode.  For channels which are not explicitly forced into one mode the
1655 spice client is allowed to pick tls/plaintext as he pleases.
1656
1657 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1658 Configure image compression (lossless).
1659 Default is auto_glz.
1660
1661 @item jpeg-wan-compression=[auto|never|always]
1662 @itemx zlib-glz-wan-compression=[auto|never|always]
1663 Configure wan image compression (lossy for slow links).
1664 Default is auto.
1665
1666 @item streaming-video=[off|all|filter]
1667 Configure video stream detection.  Default is off.
1668
1669 @item agent-mouse=[on|off]
1670 Enable/disable passing mouse events via vdagent.  Default is on.
1671
1672 @item playback-compression=[on|off]
1673 Enable/disable audio stream compression (using celt 0.5.1).  Default is on.
1674
1675 @item seamless-migration=[on|off]
1676 Enable/disable spice seamless migration. Default is off.
1677
1678 @item gl=[on|off]
1679 Enable/disable OpenGL context. Default is off.
1680
1681 @item rendernode=<file>
1682 DRM render node for OpenGL rendering. If not specified, it will pick
1683 the first available. (Since 2.9)
1684
1685 @end table
1686 ETEXI
1687
1688 DEF("portrait", 0, QEMU_OPTION_portrait,
1689     "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
1690     QEMU_ARCH_ALL)
1691 STEXI
1692 @item -portrait
1693 @findex -portrait
1694 Rotate graphical output 90 deg left (only PXA LCD).
1695 ETEXI
1696
1697 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1698     "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
1699     QEMU_ARCH_ALL)
1700 STEXI
1701 @item -rotate @var{deg}
1702 @findex -rotate
1703 Rotate graphical output some deg left (only PXA LCD).
1704 ETEXI
1705
1706 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
1707     "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
1708     "                select video card type\n", QEMU_ARCH_ALL)
1709 STEXI
1710 @item -vga @var{type}
1711 @findex -vga
1712 Select type of VGA card to emulate. Valid values for @var{type} are
1713 @table @option
1714 @item cirrus
1715 Cirrus Logic GD5446 Video card. All Windows versions starting from
1716 Windows 95 should recognize and use this graphic card. For optimal
1717 performances, use 16 bit color depth in the guest and the host OS.
1718 (This card was the default before QEMU 2.2)
1719 @item std
1720 Standard VGA card with Bochs VBE extensions.  If your guest OS
1721 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1722 to use high resolution modes (>= 1280x1024x16) then you should use
1723 this option. (This card is the default since QEMU 2.2)
1724 @item vmware
1725 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1726 recent XFree86/XOrg server or Windows guest with a driver for this
1727 card.
1728 @item qxl
1729 QXL paravirtual graphic card.  It is VGA compatible (including VESA
1730 2.0 VBE support).  Works best with qxl guest drivers installed though.
1731 Recommended choice when using the spice protocol.
1732 @item tcx
1733 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1734 sun4m machines and offers both 8-bit and 24-bit colour depths at a
1735 fixed resolution of 1024x768.
1736 @item cg3
1737 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1738 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1739 resolutions aimed at people wishing to run older Solaris versions.
1740 @item virtio
1741 Virtio VGA card.
1742 @item none
1743 Disable VGA card.
1744 @end table
1745 ETEXI
1746
1747 DEF("full-screen", 0, QEMU_OPTION_full_screen,
1748     "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
1749 STEXI
1750 @item -full-screen
1751 @findex -full-screen
1752 Start in full screen.
1753 ETEXI
1754
1755 DEF("g", 1, QEMU_OPTION_g ,
1756     "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
1757     QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
1758 STEXI
1759 @item -g @var{width}x@var{height}[x@var{depth}]
1760 @findex -g
1761 Set the initial graphical resolution and depth (PPC, SPARC only).
1762 ETEXI
1763
1764 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1765     "-vnc <display>  shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
1766 STEXI
1767 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1768 @findex -vnc
1769 Normally, if QEMU is compiled with graphical window support, it displays
1770 output such as guest graphics, guest console, and the QEMU monitor in a
1771 window. With this option, you can have QEMU listen on VNC display
1772 @var{display} and redirect the VGA display over the VNC session. It is
1773 very useful to enable the usb tablet device when using this option
1774 (option @option{-device usb-tablet}). When using the VNC display, you
1775 must use the @option{-k} parameter to set the keyboard layout if you are
1776 not using en-us. Valid syntax for the @var{display} is
1777
1778 @table @option
1779
1780 @item to=@var{L}
1781
1782 With this option, QEMU will try next available VNC @var{display}s, until the
1783 number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1784 available, e.g. port 5900+@var{display} is already used by another
1785 application. By default, to=0.
1786
1787 @item @var{host}:@var{d}
1788
1789 TCP connections will only be allowed from @var{host} on display @var{d}.
1790 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1791 be omitted in which case the server will accept connections from any host.
1792
1793 @item unix:@var{path}
1794
1795 Connections will be allowed over UNIX domain sockets where @var{path} is the
1796 location of a unix socket to listen for connections on.
1797
1798 @item none
1799
1800 VNC is initialized but not started. The monitor @code{change} command
1801 can be used to later start the VNC server.
1802
1803 @end table
1804
1805 Following the @var{display} value there may be one or more @var{option} flags
1806 separated by commas. Valid options are
1807
1808 @table @option
1809
1810 @item reverse
1811
1812 Connect to a listening VNC client via a ``reverse'' connection. The
1813 client is specified by the @var{display}. For reverse network
1814 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1815 is a TCP port number, not a display number.
1816
1817 @item websocket
1818
1819 Opens an additional TCP listening port dedicated to VNC Websocket connections.
1820 If a bare @var{websocket} option is given, the Websocket port is
1821 5700+@var{display}. An alternative port can be specified with the
1822 syntax @code{websocket}=@var{port}.
1823
1824 If @var{host} is specified connections will only be allowed from this host.
1825 It is possible to control the websocket listen address independently, using
1826 the syntax @code{websocket}=@var{host}:@var{port}.
1827
1828 If no TLS credentials are provided, the websocket connection runs in
1829 unencrypted mode. If TLS credentials are provided, the websocket connection
1830 requires encrypted client connections.
1831
1832 @item password
1833
1834 Require that password based authentication is used for client connections.
1835
1836 The password must be set separately using the @code{set_password} command in
1837 the @ref{pcsys_monitor}. The syntax to change your password is:
1838 @code{set_password <protocol> <password>} where <protocol> could be either
1839 "vnc" or "spice".
1840
1841 If you would like to change <protocol> password expiration, you should use
1842 @code{expire_password <protocol> <expiration-time>} where expiration time could
1843 be one of the following options: now, never, +seconds or UNIX time of
1844 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1845 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1846 date and time).
1847
1848 You can also use keywords "now" or "never" for the expiration time to
1849 allow <protocol> password to expire immediately or never expire.
1850
1851 @item tls-creds=@var{ID}
1852
1853 Provides the ID of a set of TLS credentials to use to secure the
1854 VNC server. They will apply to both the normal VNC server socket
1855 and the websocket socket (if enabled). Setting TLS credentials
1856 will cause the VNC server socket to enable the VeNCrypt auth
1857 mechanism.  The credentials should have been previously created
1858 using the @option{-object tls-creds} argument.
1859
1860 @item tls-authz=@var{ID}
1861
1862 Provides the ID of the QAuthZ authorization object against which
1863 the client's x509 distinguished name will validated. This object is
1864 only resolved at time of use, so can be deleted and recreated on the
1865 fly while the VNC server is active. If missing, it will default
1866 to denying access.
1867
1868 @item sasl
1869
1870 Require that the client use SASL to authenticate with the VNC server.
1871 The exact choice of authentication method used is controlled from the
1872 system / user's SASL configuration file for the 'qemu' service. This
1873 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1874 unprivileged user, an environment variable SASL_CONF_PATH can be used
1875 to make it search alternate locations for the service config.
1876 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1877 it is recommended that SASL always be combined with the 'tls' and
1878 'x509' settings to enable use of SSL and server certificates. This
1879 ensures a data encryption preventing compromise of authentication
1880 credentials. See the @ref{vnc_security} section for details on using
1881 SASL authentication.
1882
1883 @item sasl-authz=@var{ID}
1884
1885 Provides the ID of the QAuthZ authorization object against which
1886 the client's SASL username will validated. This object is
1887 only resolved at time of use, so can be deleted and recreated on the
1888 fly while the VNC server is active. If missing, it will default
1889 to denying access.
1890
1891 @item acl
1892
1893 Legacy method for enabling authorization of clients against the
1894 x509 distinguished name and SASL username. It results in the creation
1895 of two @code{authz-list} objects with IDs of @code{vnc.username} and
1896 @code{vnc.x509dname}. The rules for these objects must be configured
1897 with the HMP ACL commands.
1898
1899 This option is deprecated and should no longer be used. The new
1900 @option{sasl-authz} and @option{tls-authz} options are a
1901 replacement.
1902
1903 @item lossy
1904
1905 Enable lossy compression methods (gradient, JPEG, ...). If this
1906 option is set, VNC client may receive lossy framebuffer updates
1907 depending on its encoding settings. Enabling this option can save
1908 a lot of bandwidth at the expense of quality.
1909
1910 @item non-adaptive
1911
1912 Disable adaptive encodings. Adaptive encodings are enabled by default.
1913 An adaptive encoding will try to detect frequently updated screen regions,
1914 and send updates in these regions using a lossy encoding (like JPEG).
1915 This can be really helpful to save bandwidth when playing videos. Disabling
1916 adaptive encodings restores the original static behavior of encodings
1917 like Tight.
1918
1919 @item share=[allow-exclusive|force-shared|ignore]
1920
1921 Set display sharing policy.  'allow-exclusive' allows clients to ask
1922 for exclusive access.  As suggested by the rfb spec this is
1923 implemented by dropping other connections.  Connecting multiple
1924 clients in parallel requires all clients asking for a shared session
1925 (vncviewer: -shared switch).  This is the default.  'force-shared'
1926 disables exclusive client access.  Useful for shared desktop sessions,
1927 where you don't want someone forgetting specify -shared disconnect
1928 everybody else.  'ignore' completely ignores the shared flag and
1929 allows everybody connect unconditionally.  Doesn't conform to the rfb
1930 spec but is traditional QEMU behavior.
1931
1932 @item key-delay-ms
1933
1934 Set keyboard delay, for key down and key up events, in milliseconds.
1935 Default is 10.  Keyboards are low-bandwidth devices, so this slowdown
1936 can help the device and guest to keep up and not lose events in case
1937 events are arriving in bulk.  Possible causes for the latter are flaky
1938 network connections, or scripts for automated testing.
1939
1940 @end table
1941 ETEXI
1942
1943 STEXI
1944 @end table
1945 ETEXI
1946 ARCHHEADING(, QEMU_ARCH_I386)
1947
1948 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1949 STEXI
1950 @table @option
1951 ETEXI
1952
1953 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1954     "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
1955     QEMU_ARCH_I386)
1956 STEXI
1957 @item -win2k-hack
1958 @findex -win2k-hack
1959 Use it when installing Windows 2000 to avoid a disk full bug. After
1960 Windows 2000 is installed, you no longer need this option (this option
1961 slows down the IDE transfers).
1962 ETEXI
1963
1964 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1965     "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
1966     QEMU_ARCH_I386)
1967 STEXI
1968 @item -no-fd-bootchk
1969 @findex -no-fd-bootchk
1970 Disable boot signature checking for floppy disks in BIOS. May
1971 be needed to boot from old floppy disks.
1972 ETEXI
1973
1974 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1975            "-no-acpi        disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1976 STEXI
1977 @item -no-acpi
1978 @findex -no-acpi
1979 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1980 it if your guest OS complains about ACPI problems (PC target machine
1981 only).
1982 ETEXI
1983
1984 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1985     "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
1986 STEXI
1987 @item -no-hpet
1988 @findex -no-hpet
1989 Disable HPET support.
1990 ETEXI
1991
1992 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1993     "-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"
1994     "                ACPI table description\n", QEMU_ARCH_I386)
1995 STEXI
1996 @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}]...]
1997 @findex -acpitable
1998 Add ACPI table with specified header fields and context from specified files.
1999 For file=, take whole ACPI table from the specified files, including all
2000 ACPI headers (possible overridden by other options).
2001 For data=, only data
2002 portion of the table is used, all header information is specified in the
2003 command line.
2004 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
2005 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
2006 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
2007 spec.
2008 ETEXI
2009
2010 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2011     "-smbios file=binary\n"
2012     "                load SMBIOS entry from binary file\n"
2013     "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2014     "              [,uefi=on|off]\n"
2015     "                specify SMBIOS type 0 fields\n"
2016     "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2017     "              [,uuid=uuid][,sku=str][,family=str]\n"
2018     "                specify SMBIOS type 1 fields\n"
2019     "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2020     "              [,asset=str][,location=str]\n"
2021     "                specify SMBIOS type 2 fields\n"
2022     "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2023     "              [,sku=str]\n"
2024     "                specify SMBIOS type 3 fields\n"
2025     "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2026     "              [,asset=str][,part=str]\n"
2027     "                specify SMBIOS type 4 fields\n"
2028     "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
2029     "               [,asset=str][,part=str][,speed=%d]\n"
2030     "                specify SMBIOS type 17 fields\n",
2031     QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2032 STEXI
2033 @item -smbios file=@var{binary}
2034 @findex -smbios
2035 Load SMBIOS entry from binary file.
2036
2037 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
2038 Specify SMBIOS type 0 fields
2039
2040 @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}]
2041 Specify SMBIOS type 1 fields
2042
2043 @item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}]
2044 Specify SMBIOS type 2 fields
2045
2046 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
2047 Specify SMBIOS type 3 fields
2048
2049 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
2050 Specify SMBIOS type 4 fields
2051
2052 @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}]
2053 Specify SMBIOS type 17 fields
2054 ETEXI
2055
2056 STEXI
2057 @end table
2058 ETEXI
2059 DEFHEADING()
2060
2061 DEFHEADING(Network options:)
2062 STEXI
2063 @table @option
2064 ETEXI
2065
2066 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
2067 #ifdef CONFIG_SLIRP
2068     "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
2069     "         [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2070     "         [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
2071     "         [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
2072     "         [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
2073 #ifndef _WIN32
2074                                              "[,smb=dir[,smbserver=addr]]\n"
2075 #endif
2076     "                configure a user mode network backend with ID 'str',\n"
2077     "                its DHCP server and optional services\n"
2078 #endif
2079 #ifdef _WIN32
2080     "-netdev tap,id=str,ifname=name\n"
2081     "                configure a host TAP network backend with ID 'str'\n"
2082 #else
2083     "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
2084     "         [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
2085     "         [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
2086     "         [,poll-us=n]\n"
2087     "                configure a host TAP network backend with ID 'str'\n"
2088     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2089     "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2090     "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2091     "                to deconfigure it\n"
2092     "                use '[down]script=no' to disable script execution\n"
2093     "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2094     "                configure it\n"
2095     "                use 'fd=h' to connect to an already opened TAP interface\n"
2096     "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
2097     "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
2098     "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
2099     "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2100     "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
2101     "                use vhost=on to enable experimental in kernel accelerator\n"
2102     "                    (only has effect for virtio guests which use MSIX)\n"
2103     "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
2104     "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
2105     "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
2106     "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
2107     "                use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
2108     "                spent on busy polling for vhost net\n"
2109     "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2110     "                configure a host TAP network backend with ID 'str' that is\n"
2111     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2112     "                using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
2113 #endif
2114 #ifdef __linux__
2115     "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2116     "         [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
2117     "         [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
2118     "         [,rxcookie=rxcookie][,offset=offset]\n"
2119     "                configure a network backend with ID 'str' connected to\n"
2120     "                an Ethernet over L2TPv3 pseudowire.\n"
2121     "                Linux kernel 3.3+ as well as most routers can talk\n"
2122     "                L2TPv3. This transport allows connecting a VM to a VM,\n"
2123     "                VM to a router and even VM to Host. It is a nearly-universal\n"
2124     "                standard (RFC3391). Note - this implementation uses static\n"
2125     "                pre-configured tunnels (same as the Linux kernel).\n"
2126     "                use 'src=' to specify source address\n"
2127     "                use 'dst=' to specify destination address\n"
2128     "                use 'udp=on' to specify udp encapsulation\n"
2129     "                use 'srcport=' to specify source udp port\n"
2130     "                use 'dstport=' to specify destination udp port\n"
2131     "                use 'ipv6=on' to force v6\n"
2132     "                L2TPv3 uses cookies to prevent misconfiguration as\n"
2133     "                well as a weak security measure\n"
2134     "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
2135     "                use 'txcookie=0x012345678' to specify a txcookie\n"
2136     "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2137     "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2138     "                use 'pincounter=on' to work around broken counter handling in peer\n"
2139     "                use 'offset=X' to add an extra offset between header and data\n"
2140 #endif
2141     "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2142     "                configure a network backend to connect to another network\n"
2143     "                using a socket connection\n"
2144     "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2145     "                configure a network backend to connect to a multicast maddr and port\n"
2146     "                use 'localaddr=addr' to specify the host address to send packets from\n"
2147     "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2148     "                configure a network backend to connect to another network\n"
2149     "                using an UDP tunnel\n"
2150 #ifdef CONFIG_VDE
2151     "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2152     "                configure a network backend to connect to port 'n' of a vde switch\n"
2153     "                running on host and listening for incoming connections on 'socketpath'.\n"
2154     "                Use group 'groupname' and mode 'octalmode' to change default\n"
2155     "                ownership and permissions for communication port.\n"
2156 #endif
2157 #ifdef CONFIG_NETMAP
2158     "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
2159     "                attach to the existing netmap-enabled network interface 'name', or to a\n"
2160     "                VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2161     "                netmap device, defaults to '/dev/netmap')\n"
2162 #endif
2163 #ifdef CONFIG_POSIX
2164     "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2165     "                configure a vhost-user network, backed by a chardev 'dev'\n"
2166 #endif
2167     "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
2168     "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
2169 DEF("nic", HAS_ARG, QEMU_OPTION_nic,
2170     "-nic [tap|bridge|"
2171 #ifdef CONFIG_SLIRP
2172     "user|"
2173 #endif
2174 #ifdef __linux__
2175     "l2tpv3|"
2176 #endif
2177 #ifdef CONFIG_VDE
2178     "vde|"
2179 #endif
2180 #ifdef CONFIG_NETMAP
2181     "netmap|"
2182 #endif
2183 #ifdef CONFIG_POSIX
2184     "vhost-user|"
2185 #endif
2186     "socket][,option][,...][mac=macaddr]\n"
2187     "                initialize an on-board / default host NIC (using MAC address\n"
2188     "                macaddr) and connect it to the given host network backend\n"
2189     "-nic none       use it alone to have zero network devices (the default is to\n"
2190     "                provided a 'user' network connection)\n",
2191     QEMU_ARCH_ALL)
2192 DEF("net", HAS_ARG, QEMU_OPTION_net,
2193     "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2194     "                configure or create an on-board (or machine default) NIC and\n"
2195     "                connect it to hub 0 (please use -nic unless you need a hub)\n"
2196     "-net ["
2197 #ifdef CONFIG_SLIRP
2198     "user|"
2199 #endif
2200     "tap|"
2201     "bridge|"
2202 #ifdef CONFIG_VDE
2203     "vde|"
2204 #endif
2205 #ifdef CONFIG_NETMAP
2206     "netmap|"
2207 #endif
2208     "socket][,option][,option][,...]\n"
2209     "                old way to initialize a host network interface\n"
2210     "                (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2211 STEXI
2212 @item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2213 @findex -nic
2214 This option is a shortcut for configuring both the on-board (default) guest
2215 NIC hardware and the host network backend in one go. The host backend options
2216 are the same as with the corresponding @option{-netdev} options below.
2217 The guest NIC model can be set with @option{model=@var{modelname}}.
2218 Use @option{model=help} to list the available device types.
2219 The hardware MAC address can be set with @option{mac=@var{macaddr}}.
2220
2221 The following two example do exactly the same, to show how @option{-nic} can
2222 be used to shorten the command line length (note that the e1000 is the default
2223 on i386, so the @option{model=e1000} parameter could even be omitted here, too):
2224 @example
2225 qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2226 qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2227 @end example
2228
2229 @item -nic none
2230 Indicate that no network devices should be configured. It is used to override
2231 the default configuration (default NIC with ``user'' host network backend)
2232 which is activated if no other networking options are provided.
2233
2234 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
2235 @findex -netdev
2236 Configure user mode host network backend which requires no administrator
2237 privilege to run. Valid options are:
2238
2239 @table @option
2240 @item id=@var{id}
2241 Assign symbolic name for use in monitor commands.
2242
2243 @item ipv4=on|off and ipv6=on|off
2244 Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2245 both protocols are enabled.
2246
2247 @item net=@var{addr}[/@var{mask}]
2248 Set IP network address the guest will see. Optionally specify the netmask,
2249 either in the form a.b.c.d or as number of valid top-most bits. Default is
2250 10.0.2.0/24.
2251
2252 @item host=@var{addr}
2253 Specify the guest-visible address of the host. Default is the 2nd IP in the
2254 guest network, i.e. x.x.x.2.
2255
2256 @item ipv6-net=@var{addr}[/@var{int}]
2257 Set IPv6 network address the guest will see (default is fec0::/64). The
2258 network prefix is given in the usual hexadecimal IPv6 address
2259 notation. The prefix size is optional, and is given as the number of
2260 valid top-most bits (default is 64).
2261
2262 @item ipv6-host=@var{addr}
2263 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2264 the guest network, i.e. xxxx::2.
2265
2266 @item restrict=on|off
2267 If this option is enabled, the guest will be isolated, i.e. it will not be
2268 able to contact the host and no guest IP packets will be routed over the host
2269 to the outside. This option does not affect any explicitly set forwarding rules.
2270
2271 @item hostname=@var{name}
2272 Specifies the client hostname reported by the built-in DHCP server.
2273
2274 @item dhcpstart=@var{addr}
2275 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
2276 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
2277
2278 @item dns=@var{addr}
2279 Specify the guest-visible address of the virtual nameserver. The address must
2280 be different from the host address. Default is the 3rd IP in the guest network,
2281 i.e. x.x.x.3.
2282
2283 @item ipv6-dns=@var{addr}
2284 Specify the guest-visible address of the IPv6 virtual nameserver. The address
2285 must be different from the host address. Default is the 3rd IP in the guest
2286 network, i.e. xxxx::3.
2287
2288 @item dnssearch=@var{domain}
2289 Provides an entry for the domain-search list sent by the built-in
2290 DHCP server. More than one domain suffix can be transmitted by specifying
2291 this option multiple times. If supported, this will cause the guest to
2292 automatically try to append the given domain suffix(es) in case a domain name
2293 can not be resolved.
2294
2295 Example:
2296 @example
2297 qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2298 @end example
2299
2300 @item domainname=@var{domain}
2301 Specifies the client domain name reported by the built-in DHCP server.
2302
2303 @item tftp=@var{dir}
2304 When using the user mode network stack, activate a built-in TFTP
2305 server. The files in @var{dir} will be exposed as the root of a TFTP server.
2306 The TFTP client on the guest must be configured in binary mode (use the command
2307 @code{bin} of the Unix TFTP client).
2308
2309 @item tftp-server-name=@var{name}
2310 In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
2311 66). This can be used to advise the guest to load boot files or configurations
2312 from a different server than the host address.
2313
2314 @item bootfile=@var{file}
2315 When using the user mode network stack, broadcast @var{file} as the BOOTP
2316 filename. In conjunction with @option{tftp}, this can be used to network boot
2317 a guest from a local directory.
2318
2319 Example (using pxelinux):
2320 @example
2321 qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
2322     -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2323 @end example
2324
2325 @item smb=@var{dir}[,smbserver=@var{addr}]
2326 When using the user mode network stack, activate a built-in SMB
2327 server so that Windows OSes can access to the host files in @file{@var{dir}}
2328 transparently. The IP address of the SMB server can be set to @var{addr}. By
2329 default the 4th IP in the guest network is used, i.e. x.x.x.4.
2330
2331 In the guest Windows OS, the line:
2332 @example
2333 10.0.2.4 smbserver
2334 @end example
2335 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2336 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2337
2338 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2339
2340 Note that a SAMBA server must be installed on the host OS.
2341
2342 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
2343 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2344 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2345 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
2346 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2347 be bound to a specific host interface. If no connection type is set, TCP is
2348 used. This option can be given multiple times.
2349
2350 For example, to redirect host X11 connection from screen 1 to guest
2351 screen 0, use the following:
2352
2353 @example
2354 # on the host
2355 qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2356 # this host xterm should open in the guest X11 server
2357 xterm -display :1
2358 @end example
2359
2360 To redirect telnet connections from host port 5555 to telnet port on
2361 the guest, use the following:
2362
2363 @example
2364 # on the host
2365 qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
2366 telnet localhost 5555
2367 @end example
2368
2369 Then when you use on the host @code{telnet localhost 5555}, you
2370 connect to the guest telnet server.
2371
2372 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
2373 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
2374 Forward guest TCP connections to the IP address @var{server} on port @var{port}
2375 to the character device @var{dev} or to a program executed by @var{cmd:command}
2376 which gets spawned for each connection. This option can be given multiple times.
2377
2378 You can either use a chardev directly and have that one used throughout QEMU's
2379 lifetime, like in the following example:
2380
2381 @example
2382 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2383 # the guest accesses it
2384 qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2385 @end example
2386
2387 Or you can execute a command on every TCP connection established by the guest,
2388 so that QEMU behaves similar to an inetd process for that virtual server:
2389
2390 @example
2391 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2392 # and connect the TCP stream to its stdin/stdout
2393 qemu-system-i386 -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2394 @end example
2395
2396 @end table
2397
2398 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2399 Configure a host TAP network backend with ID @var{id}.
2400
2401 Use the network script @var{file} to configure it and the network script
2402 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
2403 automatically provides one. The default network configure script is
2404 @file{/etc/qemu-ifup} and the default network deconfigure script is
2405 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2406 to disable script execution.
2407
2408 If running QEMU as an unprivileged user, use the network helper
2409 @var{helper} to configure the TAP interface and attach it to the bridge.
2410 The default network helper executable is @file{/path/to/qemu-bridge-helper}
2411 and the default bridge device is @file{br0}.
2412
2413 @option{fd}=@var{h} can be used to specify the handle of an already
2414 opened host TAP interface.
2415
2416 Examples:
2417
2418 @example
2419 #launch a QEMU instance with the default network script
2420 qemu-system-i386 linux.img -nic tap
2421 @end example
2422
2423 @example
2424 #launch a QEMU instance with two NICs, each one connected
2425 #to a TAP device
2426 qemu-system-i386 linux.img \
2427         -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2428         -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2429 @end example
2430
2431 @example
2432 #launch a QEMU instance with the default network helper to
2433 #connect a TAP device to bridge br0
2434 qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
2435         -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2436 @end example
2437
2438 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
2439 Connect a host TAP network interface to a host bridge device.
2440
2441 Use the network helper @var{helper} to configure the TAP interface and
2442 attach it to the bridge. The default network helper executable is
2443 @file{/path/to/qemu-bridge-helper} and the default bridge
2444 device is @file{br0}.
2445
2446 Examples:
2447
2448 @example
2449 #launch a QEMU instance with the default network helper to
2450 #connect a TAP device to bridge br0
2451 qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2452 @end example
2453
2454 @example
2455 #launch a QEMU instance with the default network helper to
2456 #connect a TAP device to bridge qemubr0
2457 qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2458 @end example
2459
2460 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
2461
2462 This host network backend can be used to connect the guest's network to
2463 another QEMU virtual machine using a TCP socket connection. If @option{listen}
2464 is specified, QEMU waits for incoming connections on @var{port}
2465 (@var{host} is optional). @option{connect} is used to connect to
2466 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2467 specifies an already opened TCP socket.
2468
2469 Example:
2470 @example
2471 # launch a first QEMU instance
2472 qemu-system-i386 linux.img \
2473                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2474                  -netdev socket,id=n1,listen=:1234
2475 # connect the network of this instance to the network of the first instance
2476 qemu-system-i386 linux.img \
2477                  -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2478                  -netdev socket,id=n2,connect=127.0.0.1:1234
2479 @end example
2480
2481 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
2482
2483 Configure a socket host network backend to share the guest's network traffic
2484 with another QEMU virtual machines using a UDP multicast socket, effectively
2485 making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
2486 NOTES:
2487 @enumerate
2488 @item
2489 Several QEMU can be running on different hosts and share same bus (assuming
2490 correct multicast setup for these hosts).
2491 @item
2492 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2493 @url{http://user-mode-linux.sf.net}.
2494 @item
2495 Use @option{fd=h} to specify an already opened UDP multicast socket.
2496 @end enumerate
2497
2498 Example:
2499 @example
2500 # launch one QEMU instance
2501 qemu-system-i386 linux.img \
2502                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2503                  -netdev socket,id=n1,mcast=230.0.0.1:1234
2504 # launch another QEMU instance on same "bus"
2505 qemu-system-i386 linux.img \
2506                  -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2507                  -netdev socket,id=n2,mcast=230.0.0.1:1234
2508 # launch yet another QEMU instance on same "bus"
2509 qemu-system-i386 linux.img \
2510                  -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
2511                  -netdev socket,id=n3,mcast=230.0.0.1:1234
2512 @end example
2513
2514 Example (User Mode Linux compat.):
2515 @example
2516 # launch QEMU instance (note mcast address selected is UML's default)
2517 qemu-system-i386 linux.img \
2518                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2519                  -netdev socket,id=n1,mcast=239.192.168.1:1102
2520 # launch UML
2521 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2522 @end example
2523
2524 Example (send packets from host's 1.2.3.4):
2525 @example
2526 qemu-system-i386 linux.img \
2527                  -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2528                  -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2529 @end example
2530
2531 @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}]
2532 Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
2533 popular protocol to transport Ethernet (and other Layer 2) data frames between
2534 two systems. It is present in routers, firewalls and the Linux kernel
2535 (from version 3.3 onwards).
2536
2537 This transport allows a VM to communicate to another VM, router or firewall directly.
2538
2539 @table @option
2540 @item src=@var{srcaddr}
2541     source address (mandatory)
2542 @item dst=@var{dstaddr}
2543     destination address (mandatory)
2544 @item udp
2545     select udp encapsulation (default is ip).
2546 @item srcport=@var{srcport}
2547     source udp port.
2548 @item dstport=@var{dstport}
2549     destination udp port.
2550 @item ipv6
2551     force v6, otherwise defaults to v4.
2552 @item rxcookie=@var{rxcookie}
2553 @itemx txcookie=@var{txcookie}
2554     Cookies are a weak form of security in the l2tpv3 specification.
2555 Their function is mostly to prevent misconfiguration. By default they are 32
2556 bit.
2557 @item cookie64
2558     Set cookie size to 64 bit instead of the default 32
2559 @item counter=off
2560     Force a 'cut-down' L2TPv3 with no counter as in
2561 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2562 @item pincounter=on
2563     Work around broken counter handling in peer. This may also help on
2564 networks which have packet reorder.
2565 @item offset=@var{offset}
2566     Add an extra offset between header and data
2567 @end table
2568
2569 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2570 on the remote Linux host 1.2.3.4:
2571 @example
2572 # Setup tunnel on linux host using raw ip as encapsulation
2573 # on 1.2.3.4
2574 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2575     encap udp udp_sport 16384 udp_dport 16384
2576 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2577     0xFFFFFFFF peer_session_id 0xFFFFFFFF
2578 ifconfig vmtunnel0 mtu 1500
2579 ifconfig vmtunnel0 up
2580 brctl addif br-lan vmtunnel0
2581
2582
2583 # on 4.3.2.1
2584 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2585
2586 qemu-system-i386 linux.img -device e1000,netdev=n1 \
2587     -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2588
2589 @end example
2590
2591 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2592 Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
2593 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2594 and MODE @var{octalmode} to change default ownership and permissions for
2595 communication port. This option is only available if QEMU has been compiled
2596 with vde support enabled.
2597
2598 Example:
2599 @example
2600 # launch vde switch
2601 vde_switch -F -sock /tmp/myswitch
2602 # launch QEMU instance
2603 qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
2604 @end example
2605
2606 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2607
2608 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2609 be a unix domain socket backed one. The vhost-user uses a specifically defined
2610 protocol to pass vhost ioctl replacement messages to an application on the other
2611 end of the socket. On non-MSIX guests, the feature can be forced with
2612 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2613 be created for multiqueue vhost-user.
2614
2615 Example:
2616 @example
2617 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2618      -numa node,memdev=mem \
2619      -chardev socket,id=chr0,path=/path/to/socket \
2620      -netdev type=vhost-user,id=net0,chardev=chr0 \
2621      -device virtio-net-pci,netdev=net0
2622 @end example
2623
2624 @item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
2625
2626 Create a hub port on the emulated hub with ID @var{hubid}.
2627
2628 The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
2629 single netdev. Alternatively, you can also connect the hubport to another
2630 netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
2631
2632 @item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
2633 @findex -net
2634 Legacy option to configure or create an on-board (or machine default) Network
2635 Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2636 the default hub), or to the netdev @var{nd}.
2637 The NIC is an e1000 by default on the PC target. Optionally, the MAC address
2638 can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
2639 only), and a @var{name} can be assigned for use in monitor commands.
2640 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2641 that the card should have; this option currently only affects virtio cards; set
2642 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2643 NIC is created.  QEMU can emulate several different models of network card.
2644 Use @code{-net nic,model=help} for a list of available devices for your target.
2645
2646 @item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
2647 Configure a host network backend (with the options corresponding to the same
2648 @option{-netdev} option) and connect it to the emulated hub 0 (the default
2649 hub). Use @var{name} to specify the name of the hub port.
2650 ETEXI
2651
2652 STEXI
2653 @end table
2654 ETEXI
2655 DEFHEADING()
2656
2657 DEFHEADING(Character device options:)
2658
2659 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
2660     "-chardev help\n"
2661     "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2662     "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2663     "         [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n"
2664     "         [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
2665     "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n"
2666     "         [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
2667     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
2668     "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
2669     "         [,logfile=PATH][,logappend=on|off]\n"
2670     "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2671     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
2672     "         [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2673     "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2674     "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2675     "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2676 #ifdef _WIN32
2677     "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2678     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2679 #else
2680     "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2681     "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
2682 #endif
2683 #ifdef CONFIG_BRLAPI
2684     "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2685 #endif
2686 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2687         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2688     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2689     "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2690 #endif
2691 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2692     "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2693     "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2694 #endif
2695 #if defined(CONFIG_SPICE)
2696     "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2697     "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2698 #endif
2699     , QEMU_ARCH_ALL
2700 )
2701
2702 STEXI
2703
2704 The general form of a character device option is:
2705 @table @option
2706 @item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
2707 @findex -chardev
2708 Backend is one of:
2709 @option{null},
2710 @option{socket},
2711 @option{udp},
2712 @option{msmouse},
2713 @option{vc},
2714 @option{ringbuf},
2715 @option{file},
2716 @option{pipe},
2717 @option{console},
2718 @option{serial},
2719 @option{pty},
2720 @option{stdio},
2721 @option{braille},
2722 @option{tty},
2723 @option{parallel},
2724 @option{parport},
2725 @option{spicevmc},
2726 @option{spiceport}.
2727 The specific backend will determine the applicable options.
2728
2729 Use @code{-chardev help} to print all available chardev backend types.
2730
2731 All devices must have an id, which can be any string up to 127 characters long.
2732 It is used to uniquely identify this device in other command line directives.
2733
2734 A character device may be used in multiplexing mode by multiple front-ends.
2735 Specify @option{mux=on} to enable this mode.
2736 A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2737 backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2738 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2739 create a multiplexer with your specified ID, and you can then configure multiple
2740 front ends to use that chardev ID for their input/output. Up to four different
2741 front ends can be connected to a single multiplexed chardev. (Without
2742 multiplexing enabled, a chardev can only be used by a single front end.)
2743 For instance you could use this to allow a single stdio chardev to be used by
2744 two serial ports and the QEMU monitor:
2745
2746 @example
2747 -chardev stdio,mux=on,id=char0 \
2748 -mon chardev=char0,mode=readline \
2749 -serial chardev:char0 \
2750 -serial chardev:char0
2751 @end example
2752
2753 You can have more than one multiplexer in a system configuration; for instance
2754 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2755 multiplexed between the QEMU monitor and a parallel port:
2756
2757 @example
2758 -chardev stdio,mux=on,id=char0 \
2759 -mon chardev=char0,mode=readline \
2760 -parallel chardev:char0 \
2761 -chardev tcp,...,mux=on,id=char1 \
2762 -serial chardev:char1 \
2763 -serial chardev:char1
2764 @end example
2765
2766 When you're using a multiplexed character device, some escape sequences are
2767 interpreted in the input. @xref{mux_keys, Keys in the character backend
2768 multiplexer}.
2769
2770 Note that some other command line options may implicitly create multiplexed
2771 character backends; for instance @option{-serial mon:stdio} creates a
2772 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2773 and @option{-nographic} also multiplexes the console and the monitor to
2774 stdio.
2775
2776 There is currently no support for multiplexing in the other direction
2777 (where a single QEMU front end takes input and output from multiple chardevs).
2778
2779 Every backend supports the @option{logfile} option, which supplies the path
2780 to a file to record all data transmitted via the backend. The @option{logappend}
2781 option controls whether the log file will be truncated or appended to when
2782 opened.
2783
2784 @end table
2785
2786 The available backends are:
2787
2788 @table @option
2789 @item -chardev null,id=@var{id}
2790 A void device. This device will not emit any data, and will drop any data it
2791 receives. The null backend does not take any options.
2792
2793 @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}]
2794
2795 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2796 unix socket will be created if @option{path} is specified. Behaviour is
2797 undefined if TCP options are specified for a unix socket.
2798
2799 @option{server} specifies that the socket shall be a listening socket.
2800
2801 @option{nowait} specifies that QEMU should not block waiting for a client to
2802 connect to a listening socket.
2803
2804 @option{telnet} specifies that traffic on the socket should interpret telnet
2805 escape sequences.
2806
2807 @option{websocket} specifies that the socket uses WebSocket protocol for
2808 communication.
2809
2810 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2811 the remote end goes away.  qemu will delay this many seconds and then attempt
2812 to reconnect.  Zero disables reconnecting, and is the default.
2813
2814 @option{tls-creds} requests enablement of the TLS protocol for encryption,
2815 and specifies the id of the TLS credentials to use for the handshake. The
2816 credentials must be previously created with the @option{-object tls-creds}
2817 argument.
2818
2819 @option{tls-auth} provides the ID of the QAuthZ authorization object against
2820 which the client's x509 distinguished name will be validated. This object is
2821 only resolved at time of use, so can be deleted and recreated on the fly
2822 while the chardev server is active. If missing, it will default to denying
2823 access.
2824
2825 TCP and unix socket options are given below:
2826
2827 @table @option
2828
2829 @item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
2830
2831 @option{host} for a listening socket specifies the local address to be bound.
2832 For a connecting socket species the remote host to connect to. @option{host} is
2833 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2834
2835 @option{port} for a listening socket specifies the local port to be bound. For a
2836 connecting socket specifies the port on the remote host to connect to.
2837 @option{port} can be given as either a port number or a service name.
2838 @option{port} is required.
2839
2840 @option{to} is only relevant to listening sockets. If it is specified, and
2841 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2842 to and including @option{to} until it succeeds. @option{to} must be specified
2843 as a port number.
2844
2845 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2846 If neither is specified the socket may use either protocol.
2847
2848 @option{nodelay} disables the Nagle algorithm.
2849
2850 @item unix options: path=@var{path}
2851
2852 @option{path} specifies the local path of the unix socket. @option{path} is
2853 required.
2854
2855 @end table
2856
2857 @item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6]
2858
2859 Sends all traffic from the guest to a remote host over UDP.
2860
2861 @option{host} specifies the remote host to connect to. If not specified it
2862 defaults to @code{localhost}.
2863
2864 @option{port} specifies the port on the remote host to connect to. @option{port}
2865 is required.
2866
2867 @option{localaddr} specifies the local address to bind to. If not specified it
2868 defaults to @code{0.0.0.0}.
2869
2870 @option{localport} specifies the local port to bind to. If not specified any
2871 available local port will be used.
2872
2873 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2874 If neither is specified the device may use either protocol.
2875
2876 @item -chardev msmouse,id=@var{id}
2877
2878 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2879 take any options.
2880
2881 @item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]]
2882
2883 Connect to a QEMU text console. @option{vc} may optionally be given a specific
2884 size.
2885
2886 @option{width} and @option{height} specify the width and height respectively of
2887 the console, in pixels.
2888
2889 @option{cols} and @option{rows} specify that the console be sized to fit a text
2890 console with the given dimensions.
2891
2892 @item -chardev ringbuf,id=@var{id}[,size=@var{size}]
2893
2894 Create a ring buffer with fixed size @option{size}.
2895 @var{size} must be a power of two and defaults to @code{64K}.
2896
2897 @item -chardev file,id=@var{id},path=@var{path}
2898
2899 Log all traffic received from the guest to a file.
2900
2901 @option{path} specifies the path of the file to be opened. This file will be
2902 created if it does not already exist, and overwritten if it does. @option{path}
2903 is required.
2904
2905 @item -chardev pipe,id=@var{id},path=@var{path}
2906
2907 Create a two-way connection to the guest. The behaviour differs slightly between
2908 Windows hosts and other hosts:
2909
2910 On Windows, a single duplex pipe will be created at
2911 @file{\\.pipe\@option{path}}.
2912
2913 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2914 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2915 received by the guest. Data written by the guest can be read from
2916 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2917 be present.
2918
2919 @option{path} forms part of the pipe path as described above. @option{path} is
2920 required.
2921
2922 @item -chardev console,id=@var{id}
2923
2924 Send traffic from the guest to QEMU's standard output. @option{console} does not
2925 take any options.
2926
2927 @option{console} is only available on Windows hosts.
2928
2929 @item -chardev serial,id=@var{id},path=@option{path}
2930
2931 Send traffic from the guest to a serial device on the host.
2932
2933 On Unix hosts serial will actually accept any tty device,
2934 not only serial lines.
2935
2936 @option{path} specifies the name of the serial device to open.
2937
2938 @item -chardev pty,id=@var{id}
2939
2940 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2941 not take any options.
2942
2943 @option{pty} is not available on Windows hosts.
2944
2945 @item -chardev stdio,id=@var{id}[,signal=on|off]
2946 Connect to standard input and standard output of the QEMU process.
2947
2948 @option{signal} controls if signals are enabled on the terminal, that includes
2949 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2950 default, use @option{signal=off} to disable it.
2951
2952 @item -chardev braille,id=@var{id}
2953
2954 Connect to a local BrlAPI server. @option{braille} does not take any options.
2955
2956 @item -chardev tty,id=@var{id},path=@var{path}
2957
2958 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2959 DragonFlyBSD hosts.  It is an alias for @option{serial}.
2960
2961 @option{path} specifies the path to the tty. @option{path} is required.
2962
2963 @item -chardev parallel,id=@var{id},path=@var{path}
2964 @itemx -chardev parport,id=@var{id},path=@var{path}
2965
2966 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2967
2968 Connect to a local parallel port.
2969
2970 @option{path} specifies the path to the parallel port device. @option{path} is
2971 required.
2972
2973 @item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
2974
2975 @option{spicevmc} is only available when spice support is built in.
2976
2977 @option{debug} debug level for spicevmc
2978
2979 @option{name} name of spice channel to connect to
2980
2981 Connect to a spice virtual machine channel, such as vdiport.
2982
2983 @item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
2984
2985 @option{spiceport} is only available when spice support is built in.
2986
2987 @option{debug} debug level for spicevmc
2988
2989 @option{name} name of spice port to connect to
2990
2991 Connect to a spice port, allowing a Spice client to handle the traffic
2992 identified by a name (preferably a fqdn).
2993 ETEXI
2994
2995 STEXI
2996 @end table
2997 ETEXI
2998 DEFHEADING()
2999
3000 DEFHEADING(Bluetooth(R) options:)
3001 STEXI
3002 @table @option
3003 ETEXI
3004
3005 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
3006     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
3007     "-bt hci,host[:id]\n" \
3008     "                use host's HCI with the given name\n" \
3009     "-bt hci[,vlan=n]\n" \
3010     "                emulate a standard HCI in virtual scatternet 'n'\n" \
3011     "-bt vhci[,vlan=n]\n" \
3012     "                add host computer to virtual scatternet 'n' using VHCI\n" \
3013     "-bt device:dev[,vlan=n]\n" \
3014     "                emulate a bluetooth device 'dev' in scatternet 'n'\n",
3015     QEMU_ARCH_ALL)
3016 STEXI
3017 @item -bt hci[...]
3018 @findex -bt
3019 Defines the function of the corresponding Bluetooth HCI.  -bt options
3020 are matched with the HCIs present in the chosen machine type.  For
3021 example when emulating a machine with only one HCI built into it, only
3022 the first @code{-bt hci[...]} option is valid and defines the HCI's
3023 logic.  The Transport Layer is decided by the machine type.  Currently
3024 the machines @code{n800} and @code{n810} have one HCI and all other
3025 machines have none.
3026
3027 Note: This option and the whole bluetooth subsystem is considered as deprecated.
3028 If you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where
3029 you describe your usecase.
3030
3031 @anchor{bt-hcis}
3032 The following three types are recognized:
3033
3034 @table @option
3035 @item -bt hci,null
3036 (default) The corresponding Bluetooth HCI assumes no internal logic
3037 and will not respond to any HCI commands or emit events.
3038
3039 @item -bt hci,host[:@var{id}]
3040 (@code{bluez} only) The corresponding HCI passes commands / events
3041 to / from the physical HCI identified by the name @var{id} (default:
3042 @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
3043 capable systems like Linux.
3044
3045 @item -bt hci[,vlan=@var{n}]
3046 Add a virtual, standard HCI that will participate in the Bluetooth
3047 scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
3048 VLANs, devices inside a bluetooth network @var{n} can only communicate
3049 with other devices in the same network (scatternet).
3050 @end table
3051
3052 @item -bt vhci[,vlan=@var{n}]
3053 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
3054 to the host bluetooth stack instead of to the emulated target.  This
3055 allows the host and target machines to participate in a common scatternet
3056 and communicate.  Requires the Linux @code{vhci} driver installed.  Can
3057 be used as following:
3058
3059 @example
3060 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
3061 @end example
3062
3063 @item -bt device:@var{dev}[,vlan=@var{n}]
3064 Emulate a bluetooth device @var{dev} and place it in network @var{n}
3065 (default @code{0}).  QEMU can only emulate one type of bluetooth devices
3066 currently:
3067
3068 @table @option
3069 @item keyboard
3070 Virtual wireless keyboard implementing the HIDP bluetooth profile.
3071 @end table
3072 ETEXI
3073
3074 STEXI
3075 @end table
3076 ETEXI
3077 DEFHEADING()
3078
3079 #ifdef CONFIG_TPM
3080 DEFHEADING(TPM device options:)
3081
3082 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3083     "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3084     "                use path to provide path to a character device; default is /dev/tpm0\n"
3085     "                use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3086     "                not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3087     "-tpmdev emulator,id=id,chardev=dev\n"
3088     "                configure the TPM device using chardev backend\n",
3089     QEMU_ARCH_ALL)
3090 STEXI
3091
3092 The general form of a TPM device option is:
3093 @table @option
3094
3095 @item -tpmdev @var{backend},id=@var{id}[,@var{options}]
3096 @findex -tpmdev
3097
3098 The specific backend type will determine the applicable options.
3099 The @code{-tpmdev} option creates the TPM backend and requires a
3100 @code{-device} option that specifies the TPM frontend interface model.
3101
3102 Use @code{-tpmdev help} to print all available TPM backend types.
3103
3104 @end table
3105
3106 The available backends are:
3107
3108 @table @option
3109
3110 @item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
3111
3112 (Linux-host only) Enable access to the host's TPM using the passthrough
3113 driver.
3114
3115 @option{path} specifies the path to the host's TPM device, i.e., on
3116 a Linux host this would be @code{/dev/tpm0}.
3117 @option{path} is optional and by default @code{/dev/tpm0} is used.
3118
3119 @option{cancel-path} specifies the path to the host TPM device's sysfs
3120 entry allowing for cancellation of an ongoing TPM command.
3121 @option{cancel-path} is optional and by default QEMU will search for the
3122 sysfs entry to use.
3123
3124 Some notes about using the host's TPM with the passthrough driver:
3125
3126 The TPM device accessed by the passthrough driver must not be
3127 used by any other application on the host.
3128
3129 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3130 the VM's firmware (BIOS/UEFI) will not be able to initialize the
3131 TPM again and may therefore not show a TPM-specific menu that would
3132 otherwise allow the user to configure the TPM, e.g., allow the user to
3133 enable/disable or activate/deactivate the TPM.
3134 Further, if TPM ownership is released from within a VM then the host's TPM
3135 will get disabled and deactivated. To enable and activate the
3136 TPM again afterwards, the host has to be rebooted and the user is
3137 required to enter the firmware's menu to enable and activate the TPM.
3138 If the TPM is left disabled and/or deactivated most TPM commands will fail.
3139
3140 To create a passthrough TPM use the following two options:
3141 @example
3142 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3143 @end example
3144 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3145 @code{tpmdev=tpm0} in the device option.
3146
3147 @item -tpmdev emulator,id=@var{id},chardev=@var{dev}
3148
3149 (Linux-host only) Enable access to a TPM emulator using Unix domain socket based
3150 chardev backend.
3151
3152 @option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
3153
3154 To create a TPM emulator backend device with chardev socket backend:
3155 @example
3156
3157 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3158
3159 @end example
3160
3161 ETEXI
3162
3163 STEXI
3164 @end table
3165 ETEXI
3166 DEFHEADING()
3167
3168 #endif
3169
3170 DEFHEADING(Linux/Multiboot boot specific:)
3171 STEXI
3172
3173 When using these options, you can use a given Linux or Multiboot
3174 kernel without installing it in the disk image. It can be useful
3175 for easier testing of various kernels.
3176
3177 @table @option
3178 ETEXI
3179
3180 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3181     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3182 STEXI
3183 @item -kernel @var{bzImage}
3184 @findex -kernel
3185 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3186 or in multiboot format.
3187 ETEXI
3188
3189 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3190     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3191 STEXI
3192 @item -append @var{cmdline}
3193 @findex -append
3194 Use @var{cmdline} as kernel command line
3195 ETEXI
3196
3197 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3198            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3199 STEXI
3200 @item -initrd @var{file}
3201 @findex -initrd
3202 Use @var{file} as initial ram disk.
3203
3204 @item -initrd "@var{file1} arg=foo,@var{file2}"
3205
3206 This syntax is only available with multiboot.
3207
3208 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3209 first module.
3210 ETEXI
3211
3212 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3213     "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
3214 STEXI
3215 @item -dtb @var{file}
3216 @findex -dtb
3217 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3218 on boot.
3219 ETEXI
3220
3221 STEXI
3222 @end table
3223 ETEXI
3224 DEFHEADING()
3225
3226 DEFHEADING(Debug/Expert options:)
3227 STEXI
3228 @table @option
3229 ETEXI
3230
3231 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3232     "-fw_cfg [name=]<name>,file=<file>\n"
3233     "                add named fw_cfg entry with contents from file\n"
3234     "-fw_cfg [name=]<name>,string=<str>\n"
3235     "                add named fw_cfg entry with contents from string\n",
3236     QEMU_ARCH_ALL)
3237 STEXI
3238
3239 @item -fw_cfg [name=]@var{name},file=@var{file}
3240 @findex -fw_cfg
3241 Add named fw_cfg entry with contents from file @var{file}.
3242
3243 @item -fw_cfg [name=]@var{name},string=@var{str}
3244 Add named fw_cfg entry with contents from string @var{str}.
3245
3246 The terminating NUL character of the contents of @var{str} will not be
3247 included as part of the fw_cfg item data. To insert contents with
3248 embedded NUL characters, you have to use the @var{file} parameter.
3249
3250 The fw_cfg entries are passed by QEMU through to the guest.
3251
3252 Example:
3253 @example
3254     -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3255 @end example
3256 creates an fw_cfg entry named opt/com.mycompany/blob with contents
3257 from ./my_blob.bin.
3258
3259 ETEXI
3260
3261 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3262     "-serial dev     redirect the serial port to char device 'dev'\n",
3263     QEMU_ARCH_ALL)
3264 STEXI
3265 @item -serial @var{dev}
3266 @findex -serial
3267 Redirect the virtual serial port to host character device
3268 @var{dev}. The default device is @code{vc} in graphical mode and
3269 @code{stdio} in non graphical mode.
3270
3271 This option can be used several times to simulate up to 4 serial
3272 ports.
3273
3274 Use @code{-serial none} to disable all serial ports.
3275
3276 Available character devices are:
3277 @table @option
3278 @item vc[:@var{W}x@var{H}]
3279 Virtual console. Optionally, a width and height can be given in pixel with
3280 @example
3281 vc:800x600
3282 @end example
3283 It is also possible to specify width or height in characters:
3284 @example
3285 vc:80Cx24C
3286 @end example
3287 @item pty
3288 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3289 @item none
3290 No device is allocated.
3291 @item null
3292 void device
3293 @item chardev:@var{id}
3294 Use a named character device defined with the @code{-chardev} option.
3295 @item /dev/XXX
3296 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3297 parameters are set according to the emulated ones.
3298 @item /dev/parport@var{N}
3299 [Linux only, parallel port only] Use host parallel port
3300 @var{N}. Currently SPP and EPP parallel port features can be used.
3301 @item file:@var{filename}
3302 Write output to @var{filename}. No character can be read.
3303 @item stdio
3304 [Unix only] standard input/output
3305 @item pipe:@var{filename}
3306 name pipe @var{filename}
3307 @item COM@var{n}
3308 [Windows only] Use host serial port @var{n}
3309 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3310 This implements UDP Net Console.
3311 When @var{remote_host} or @var{src_ip} are not specified
3312 they default to @code{0.0.0.0}.
3313 When not using a specified @var{src_port} a random port is automatically chosen.
3314
3315 If you just want a simple readonly console you can use @code{netcat} or
3316 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3317 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
3318 will appear in the netconsole session.
3319
3320 If you plan to send characters back via netconsole or you want to stop
3321 and start QEMU a lot of times, you should have QEMU use the same
3322 source port each time by using something like @code{-serial
3323 udp::4555@@:4556} to QEMU. Another approach is to use a patched
3324 version of netcat which can listen to a TCP port and send and receive
3325 characters via udp.  If you have a patched version of netcat which
3326 activates telnet remote echo and single char transfer, then you can
3327 use the following options to set up a netcat redirector to allow
3328 telnet on port 5555 to access the QEMU port.
3329 @table @code
3330 @item QEMU Options:
3331 -serial udp::4555@@:4556
3332 @item netcat options:
3333 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3334 @item telnet options:
3335 localhost 5555
3336 @end table
3337
3338 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3339 The TCP Net Console has two modes of operation.  It can send the serial
3340 I/O to a location or wait for a connection from a location.  By default
3341 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
3342 the @var{server} option QEMU will wait for a client socket application
3343 to connect to the port before continuing, unless the @code{nowait}
3344 option was specified.  The @code{nodelay} option disables the Nagle buffering
3345 algorithm.  The @code{reconnect} option only applies if @var{noserver} is
3346 set, if the connection goes down it will attempt to reconnect at the
3347 given interval.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
3348 one TCP connection at a time is accepted. You can use @code{telnet} to
3349 connect to the corresponding character device.
3350 @table @code
3351 @item Example to send tcp console to 192.168.0.2 port 4444
3352 -serial tcp:192.168.0.2:4444
3353 @item Example to listen and wait on port 4444 for connection
3354 -serial tcp::4444,server
3355 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3356 -serial tcp:192.168.0.100:4444,server,nowait
3357 @end table
3358
3359 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3360 The telnet protocol is used instead of raw tcp sockets.  The options
3361 work the same as if you had specified @code{-serial tcp}.  The
3362 difference is that the port acts like a telnet server or client using
3363 telnet option negotiation.  This will also allow you to send the
3364 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3365 sequence.  Typically in unix telnet you do it with Control-] and then
3366 type "send break" followed by pressing the enter key.
3367
3368 @item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
3369 The WebSocket protocol is used instead of raw tcp socket. The port acts as
3370 a WebSocket server. Client mode is not supported.
3371
3372 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3373 A unix domain socket is used instead of a tcp socket.  The option works the
3374 same as if you had specified @code{-serial tcp} except the unix domain socket
3375 @var{path} is used for connections.
3376
3377 @item mon:@var{dev_string}
3378 This is a special option to allow the monitor to be multiplexed onto
3379 another serial port.  The monitor is accessed with key sequence of
3380 @key{Control-a} and then pressing @key{c}.
3381 @var{dev_string} should be any one of the serial devices specified
3382 above.  An example to multiplex the monitor onto a telnet server
3383 listening on port 4444 would be:
3384 @table @code
3385 @item -serial mon:telnet::4444,server,nowait
3386 @end table
3387 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3388 QEMU any more but will be passed to the guest instead.
3389
3390 @item braille
3391 Braille device.  This will use BrlAPI to display the braille output on a real
3392 or fake device.
3393
3394 @item msmouse
3395 Three button serial mouse. Configure the guest to use Microsoft protocol.
3396 @end table
3397 ETEXI
3398
3399 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3400     "-parallel dev   redirect the parallel port to char device 'dev'\n",
3401     QEMU_ARCH_ALL)
3402 STEXI
3403 @item -parallel @var{dev}
3404 @findex -parallel
3405 Redirect the virtual parallel port to host device @var{dev} (same
3406 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3407 be used to use hardware devices connected on the corresponding host
3408 parallel port.
3409
3410 This option can be used several times to simulate up to 3 parallel
3411 ports.
3412
3413 Use @code{-parallel none} to disable all parallel ports.
3414 ETEXI
3415
3416 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3417     "-monitor dev    redirect the monitor to char device 'dev'\n",
3418     QEMU_ARCH_ALL)
3419 STEXI
3420 @item -monitor @var{dev}
3421 @findex -monitor
3422 Redirect the monitor to host device @var{dev} (same devices as the
3423 serial port).
3424 The default device is @code{vc} in graphical mode and @code{stdio} in
3425 non graphical mode.
3426 Use @code{-monitor none} to disable the default monitor.
3427 ETEXI
3428 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3429     "-qmp dev        like -monitor but opens in 'control' mode\n",
3430     QEMU_ARCH_ALL)
3431 STEXI
3432 @item -qmp @var{dev}
3433 @findex -qmp
3434 Like -monitor but opens in 'control' mode.
3435 ETEXI
3436 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3437     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3438     QEMU_ARCH_ALL)
3439 STEXI
3440 @item -qmp-pretty @var{dev}
3441 @findex -qmp-pretty
3442 Like -qmp but uses pretty JSON formatting.
3443 ETEXI
3444
3445 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3446     "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
3447 STEXI
3448 @item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
3449 @findex -mon
3450 Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3451 easing human reading and debugging.
3452 ETEXI
3453
3454 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3455     "-debugcon dev   redirect the debug console to char device 'dev'\n",
3456     QEMU_ARCH_ALL)
3457 STEXI
3458 @item -debugcon @var{dev}
3459 @findex -debugcon
3460 Redirect the debug console to host device @var{dev} (same devices as the
3461 serial port).  The debug console is an I/O port which is typically port
3462 0xe9; writing to that I/O port sends output to this device.
3463 The default device is @code{vc} in graphical mode and @code{stdio} in
3464 non graphical mode.
3465 ETEXI
3466
3467 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3468     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
3469 STEXI
3470 @item -pidfile @var{file}
3471 @findex -pidfile
3472 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3473 from a script.
3474 ETEXI
3475
3476 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3477     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
3478 STEXI
3479 @item -singlestep
3480 @findex -singlestep
3481 Run the emulation in single step mode.
3482 ETEXI
3483
3484 DEF("preconfig", 0, QEMU_OPTION_preconfig, \
3485     "--preconfig     pause QEMU before machine is initialized (experimental)\n",
3486     QEMU_ARCH_ALL)
3487 STEXI
3488 @item --preconfig
3489 @findex --preconfig
3490 Pause QEMU for interactive configuration before the machine is created,
3491 which allows querying and configuring properties that will affect
3492 machine initialization.  Use QMP command 'x-exit-preconfig' to exit
3493 the preconfig state and move to the next state (i.e. run guest if -S
3494 isn't used or pause the second time if -S is used).  This option is
3495 experimental.
3496 ETEXI
3497
3498 DEF("S", 0, QEMU_OPTION_S, \
3499     "-S              freeze CPU at startup (use 'c' to start execution)\n",
3500     QEMU_ARCH_ALL)
3501 STEXI
3502 @item -S
3503 @findex -S
3504 Do not start CPU at startup (you must type 'c' in the monitor).
3505 ETEXI
3506
3507 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3508     "-realtime [mlock=on|off]\n"
3509     "                run qemu with realtime features\n"
3510     "                mlock=on|off controls mlock support (default: on)\n",
3511     QEMU_ARCH_ALL)
3512 STEXI
3513 @item -realtime mlock=on|off
3514 @findex -realtime
3515 Run qemu with realtime features.
3516 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3517 (enabled by default).
3518 ETEXI
3519
3520 DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
3521     "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
3522     "                run qemu with overcommit hints\n"
3523     "                mem-lock=on|off controls memory lock support (default: off)\n"
3524     "                cpu-pm=on|off controls cpu power management (default: off)\n",
3525     QEMU_ARCH_ALL)
3526 STEXI
3527 @item -overcommit mem-lock=on|off
3528 @item -overcommit cpu-pm=on|off
3529 @findex -overcommit
3530 Run qemu with hints about host resource overcommit. The default is
3531 to assume that host overcommits all resources.
3532
3533 Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3534 by default).  This works when host memory is not overcommitted and reduces the
3535 worst-case latency for guest.  This is equivalent to @option{realtime}.
3536
3537 Guest ability to manage power state of host cpus (increasing latency for other
3538 processes on the same host cpu, but decreasing latency for guest) can be
3539 enabled via @option{cpu-pm=on} (disabled by default).  This works best when
3540 host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3541 utilization will be incorrect, not taking into account guest idle time.
3542 ETEXI
3543
3544 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3545     "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
3546 STEXI
3547 @item -gdb @var{dev}
3548 @findex -gdb
3549 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3550 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3551 stdio are reasonable use case. The latter is allowing to start QEMU from
3552 within gdb and establish the connection via a pipe:
3553 @example
3554 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3555 @end example
3556 ETEXI
3557
3558 DEF("s", 0, QEMU_OPTION_s, \
3559     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3560     QEMU_ARCH_ALL)
3561 STEXI
3562 @item -s
3563 @findex -s
3564 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3565 (@pxref{gdb_usage}).
3566 ETEXI
3567
3568 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3569     "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
3570     QEMU_ARCH_ALL)
3571 STEXI
3572 @item -d @var{item1}[,...]
3573 @findex -d
3574 Enable logging of specified items. Use '-d help' for a list of log items.
3575 ETEXI
3576
3577 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3578     "-D logfile      output log to logfile (default stderr)\n",
3579     QEMU_ARCH_ALL)
3580 STEXI
3581 @item -D @var{logfile}
3582 @findex -D
3583 Output log in @var{logfile} instead of to stderr
3584 ETEXI
3585
3586 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3587     "-dfilter range,..  filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3588     QEMU_ARCH_ALL)
3589 STEXI
3590 @item -dfilter @var{range1}[,...]
3591 @findex -dfilter
3592 Filter debug output to that relevant to a range of target addresses. The filter
3593 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3594 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3595 addresses and sizes required. For example:
3596 @example
3597     -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3598 @end example
3599 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3600 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3601 block starting at 0xffffffc00005f000.
3602 ETEXI
3603
3604 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3605     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
3606     QEMU_ARCH_ALL)
3607 STEXI
3608 @item -L  @var{path}
3609 @findex -L
3610 Set the directory for the BIOS, VGA BIOS and keymaps.
3611
3612 To list all the data directories, use @code{-L help}.
3613 ETEXI
3614
3615 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3616     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
3617 STEXI
3618 @item -bios @var{file}
3619 @findex -bios
3620 Set the filename for the BIOS.
3621 ETEXI
3622
3623 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3624     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3625 STEXI
3626 @item -enable-kvm
3627 @findex -enable-kvm
3628 Enable KVM full virtualization support. This option is only available
3629 if KVM support is enabled when compiling.
3630 ETEXI
3631
3632 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3633     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
3634 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3635     "-xen-attach     attach to existing xen domain\n"
3636     "                libxl will use this when starting QEMU\n",
3637     QEMU_ARCH_ALL)
3638 DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3639     "-xen-domid-restrict     restrict set of available xen operations\n"
3640     "                        to specified domain id. (Does not affect\n"
3641     "                        xenpv machine type).\n",
3642     QEMU_ARCH_ALL)
3643 STEXI
3644 @item -xen-domid @var{id}
3645 @findex -xen-domid
3646 Specify xen guest domain @var{id} (XEN only).
3647 @item -xen-attach
3648 @findex -xen-attach
3649 Attach to existing xen domain.
3650 libxl will use this when starting QEMU (XEN only).
3651 @findex -xen-domid-restrict
3652 Restrict set of available xen operations to specified domain id (XEN only).
3653 ETEXI
3654
3655 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3656     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
3657 STEXI
3658 @item -no-reboot
3659 @findex -no-reboot
3660 Exit instead of rebooting.
3661 ETEXI
3662
3663 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3664     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
3665 STEXI
3666 @item -no-shutdown
3667 @findex -no-shutdown
3668 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3669 This allows for instance switching to monitor to commit changes to the
3670 disk image.
3671 ETEXI
3672
3673 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3674     "-loadvm [tag|id]\n" \
3675     "                start right away with a saved state (loadvm in monitor)\n",
3676     QEMU_ARCH_ALL)
3677 STEXI
3678 @item -loadvm @var{file}
3679 @findex -loadvm
3680 Start right away with a saved state (@code{loadvm} in monitor)
3681 ETEXI
3682
3683 #ifndef _WIN32
3684 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3685     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3686 #endif
3687 STEXI
3688 @item -daemonize
3689 @findex -daemonize
3690 Daemonize the QEMU process after initialization.  QEMU will not detach from
3691 standard IO until it is ready to receive connections on any of its devices.
3692 This option is a useful way for external programs to launch QEMU without having
3693 to cope with initialization race conditions.
3694 ETEXI
3695
3696 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3697     "-option-rom rom load a file, rom, into the option ROM space\n",
3698     QEMU_ARCH_ALL)
3699 STEXI
3700 @item -option-rom @var{file}
3701 @findex -option-rom
3702 Load the contents of @var{file} as an option ROM.
3703 This option is useful to load things like EtherBoot.
3704 ETEXI
3705
3706 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3707     "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3708     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3709     QEMU_ARCH_ALL)
3710
3711 STEXI
3712
3713 @item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
3714 @findex -rtc
3715 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3716 UTC or local time, respectively. @code{localtime} is required for correct date in
3717 MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
3718 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3719
3720 By default the RTC is driven by the host system time. This allows using of the
3721 RTC as accurate reference clock inside the guest, specifically if the host
3722 time is smoothly following an accurate external reference clock, e.g. via NTP.
3723 If you want to isolate the guest time from the host, you can set @option{clock}
3724 to @code{rt} instead, which provides a host monotonic clock if host support it.
3725 To even prevent the RTC from progressing during suspension, you can set @option{clock}
3726 to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
3727 icount mode in order to preserve determinism; however, note that in icount mode
3728 the speed of the virtual clock is variable and can in general differ from the
3729 host clock.
3730
3731 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3732 specifically with Windows' ACPI HAL. This option will try to figure out how
3733 many timer interrupts were not processed by the Windows guest and will
3734 re-inject them.
3735 ETEXI
3736
3737 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
3738     "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
3739     "                enable virtual instruction counter with 2^N clock ticks per\n" \
3740     "                instruction, enable aligning the host and virtual clocks\n" \
3741     "                or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
3742 STEXI
3743 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
3744 @findex -icount
3745 Enable virtual instruction counter.  The virtual cpu will execute one
3746 instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
3747 then the virtual cpu speed will be automatically adjusted to keep virtual
3748 time within a few seconds of real time.
3749
3750 When the virtual cpu is sleeping, the virtual time will advance at default
3751 speed unless @option{sleep=on|off} is specified.
3752 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3753 instantly whenever the virtual cpu goes to sleep mode and will not advance
3754 if no timer is enabled. This behavior give deterministic execution times from
3755 the guest point of view.
3756
3757 Note that while this option can give deterministic behavior, it does not
3758 provide cycle accurate emulation.  Modern CPUs contain superscalar out of
3759 order cores with complex cache hierarchies.  The number of instructions
3760 executed often has little or no correlation with actual performance.
3761
3762 @option{align=on} will activate the delay algorithm which will try
3763 to synchronise the host clock and the virtual clock. The goal is to
3764 have a guest running at the real frequency imposed by the shift option.
3765 Whenever the guest clock is behind the host clock and if
3766 @option{align=on} is specified then we print a message to the user
3767 to inform about the delay.
3768 Currently this option does not work when @option{shift} is @code{auto}.
3769 Note: The sync algorithm will work for those shift values for which
3770 the guest clock runs ahead of the host clock. Typically this happens
3771 when the shift value is high (how high depends on the host machine).
3772
3773 When @option{rr} option is specified deterministic record/replay is enabled.
3774 Replay log is written into @var{filename} file in record mode and
3775 read from this file in replay mode.
3776
3777 Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3778 at the start of execution recording. In replay mode this option is used
3779 to load the initial VM state.
3780 ETEXI
3781
3782 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3783     "-watchdog model\n" \
3784     "                enable virtual hardware watchdog [default=none]\n",
3785     QEMU_ARCH_ALL)
3786 STEXI
3787 @item -watchdog @var{model}
3788 @findex -watchdog
3789 Create a virtual hardware watchdog device.  Once enabled (by a guest
3790 action), the watchdog must be periodically polled by an agent inside
3791 the guest or else the guest will be restarted. Choose a model for
3792 which your guest has drivers.
3793
3794 The @var{model} is the model of hardware watchdog to emulate. Use
3795 @code{-watchdog help} to list available hardware models. Only one
3796 watchdog can be enabled for a guest.
3797
3798 The following models may be available:
3799 @table @option
3800 @item ib700
3801 iBASE 700 is a very simple ISA watchdog with a single timer.
3802 @item i6300esb
3803 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3804 dual-timer watchdog.
3805 @item diag288
3806 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3807 (currently KVM only).
3808 @end table
3809 ETEXI
3810
3811 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3812     "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
3813     "                action when watchdog fires [default=reset]\n",
3814     QEMU_ARCH_ALL)
3815 STEXI
3816 @item -watchdog-action @var{action}
3817 @findex -watchdog-action
3818
3819 The @var{action} controls what QEMU will do when the watchdog timer
3820 expires.
3821 The default is
3822 @code{reset} (forcefully reset the guest).
3823 Other possible actions are:
3824 @code{shutdown} (attempt to gracefully shutdown the guest),
3825 @code{poweroff} (forcefully poweroff the guest),
3826 @code{inject-nmi} (inject a NMI into the guest),
3827 @code{pause} (pause the guest),
3828 @code{debug} (print a debug message and continue), or
3829 @code{none} (do nothing).
3830
3831 Note that the @code{shutdown} action requires that the guest responds
3832 to ACPI signals, which it may not be able to do in the sort of
3833 situations where the watchdog would have expired, and thus
3834 @code{-watchdog-action shutdown} is not recommended for production use.
3835
3836 Examples:
3837
3838 @table @code
3839 @item -watchdog i6300esb -watchdog-action pause
3840 @itemx -watchdog ib700
3841 @end table
3842 ETEXI
3843
3844 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
3845     "-echr chr       set terminal escape character instead of ctrl-a\n",
3846     QEMU_ARCH_ALL)
3847 STEXI
3848
3849 @item -echr @var{numeric_ascii_value}
3850 @findex -echr
3851 Change the escape character used for switching to the monitor when using
3852 monitor and serial sharing.  The default is @code{0x01} when using the
3853 @code{-nographic} option.  @code{0x01} is equal to pressing
3854 @code{Control-a}.  You can select a different character from the ascii
3855 control keys where 1 through 26 map to Control-a through Control-z.  For
3856 instance you could use the either of the following to change the escape
3857 character to Control-t.
3858 @table @code
3859 @item -echr 0x14
3860 @itemx -echr 20
3861 @end table
3862 ETEXI
3863
3864 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
3865     "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
3866 STEXI
3867 @item -show-cursor
3868 @findex -show-cursor
3869 Show cursor.
3870 ETEXI
3871
3872 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
3873     "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
3874 STEXI
3875 @item -tb-size @var{n}
3876 @findex -tb-size
3877 Set TB size.
3878 ETEXI
3879
3880 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
3881     "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3882     "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3883     "-incoming unix:socketpath\n" \
3884     "                prepare for incoming migration, listen on\n" \
3885     "                specified protocol and socket address\n" \
3886     "-incoming fd:fd\n" \
3887     "-incoming exec:cmdline\n" \
3888     "                accept incoming migration on given file descriptor\n" \
3889     "                or from given external command\n" \
3890     "-incoming defer\n" \
3891