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