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