Update version for v2.10.0-rc3 release
[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{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     QEMU_ARCH_ALL)
3126 STEXI
3127
3128 The general form of a TPM device option is:
3129 @table @option
3130
3131 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
3132 @findex -tpmdev
3133 Backend type must be:
3134 @option{passthrough}.
3135
3136 The specific backend type will determine the applicable options.
3137 The @code{-tpmdev} option creates the TPM backend and requires a
3138 @code{-device} option that specifies the TPM frontend interface model.
3139
3140 Options to each backend are described below.
3141
3142 Use 'help' to print all available TPM backend types.
3143 @example
3144 qemu -tpmdev help
3145 @end example
3146
3147 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
3148
3149 (Linux-host only) Enable access to the host's TPM using the passthrough
3150 driver.
3151
3152 @option{path} specifies the path to the host's TPM device, i.e., on
3153 a Linux host this would be @code{/dev/tpm0}.
3154 @option{path} is optional and by default @code{/dev/tpm0} is used.
3155
3156 @option{cancel-path} specifies the path to the host TPM device's sysfs
3157 entry allowing for cancellation of an ongoing TPM command.
3158 @option{cancel-path} is optional and by default QEMU will search for the
3159 sysfs entry to use.
3160
3161 Some notes about using the host's TPM with the passthrough driver:
3162
3163 The TPM device accessed by the passthrough driver must not be
3164 used by any other application on the host.
3165
3166 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3167 the VM's firmware (BIOS/UEFI) will not be able to initialize the
3168 TPM again and may therefore not show a TPM-specific menu that would
3169 otherwise allow the user to configure the TPM, e.g., allow the user to
3170 enable/disable or activate/deactivate the TPM.
3171 Further, if TPM ownership is released from within a VM then the host's TPM
3172 will get disabled and deactivated. To enable and activate the
3173 TPM again afterwards, the host has to be rebooted and the user is
3174 required to enter the firmware's menu to enable and activate the TPM.
3175 If the TPM is left disabled and/or deactivated most TPM commands will fail.
3176
3177 To create a passthrough TPM use the following two options:
3178 @example
3179 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3180 @end example
3181 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3182 @code{tpmdev=tpm0} in the device option.
3183
3184 @end table
3185
3186 ETEXI
3187
3188 DEFHEADING()
3189
3190 #endif
3191
3192 DEFHEADING(Linux/Multiboot boot specific)
3193 STEXI
3194
3195 When using these options, you can use a given Linux or Multiboot
3196 kernel without installing it in the disk image. It can be useful
3197 for easier testing of various kernels.
3198
3199 @table @option
3200 ETEXI
3201
3202 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3203     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3204 STEXI
3205 @item -kernel @var{bzImage}
3206 @findex -kernel
3207 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3208 or in multiboot format.
3209 ETEXI
3210
3211 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3212     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3213 STEXI
3214 @item -append @var{cmdline}
3215 @findex -append
3216 Use @var{cmdline} as kernel command line
3217 ETEXI
3218
3219 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3220            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3221 STEXI
3222 @item -initrd @var{file}
3223 @findex -initrd
3224 Use @var{file} as initial ram disk.
3225
3226 @item -initrd "@var{file1} arg=foo,@var{file2}"
3227
3228 This syntax is only available with multiboot.
3229
3230 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3231 first module.
3232 ETEXI
3233
3234 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3235     "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
3236 STEXI
3237 @item -dtb @var{file}
3238 @findex -dtb
3239 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3240 on boot.
3241 ETEXI
3242
3243 STEXI
3244 @end table
3245 ETEXI
3246 DEFHEADING()
3247
3248 DEFHEADING(Debug/Expert options)
3249 STEXI
3250 @table @option
3251 ETEXI
3252
3253 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3254     "-fw_cfg [name=]<name>,file=<file>\n"
3255     "                add named fw_cfg entry with contents from file\n"
3256     "-fw_cfg [name=]<name>,string=<str>\n"
3257     "                add named fw_cfg entry with contents from string\n",
3258     QEMU_ARCH_ALL)
3259 STEXI
3260
3261 @item -fw_cfg [name=]@var{name},file=@var{file}
3262 @findex -fw_cfg
3263 Add named fw_cfg entry with contents from file @var{file}.
3264
3265 @item -fw_cfg [name=]@var{name},string=@var{str}
3266 Add named fw_cfg entry with contents from string @var{str}.
3267
3268 The terminating NUL character of the contents of @var{str} will not be
3269 included as part of the fw_cfg item data. To insert contents with
3270 embedded NUL characters, you have to use the @var{file} parameter.
3271
3272 The fw_cfg entries are passed by QEMU through to the guest.
3273
3274 Example:
3275 @example
3276     -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3277 @end example
3278 creates an fw_cfg entry named opt/com.mycompany/blob with contents
3279 from ./my_blob.bin.
3280
3281 ETEXI
3282
3283 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3284     "-serial dev     redirect the serial port to char device 'dev'\n",
3285     QEMU_ARCH_ALL)
3286 STEXI
3287 @item -serial @var{dev}
3288 @findex -serial
3289 Redirect the virtual serial port to host character device
3290 @var{dev}. The default device is @code{vc} in graphical mode and
3291 @code{stdio} in non graphical mode.
3292
3293 This option can be used several times to simulate up to 4 serial
3294 ports.
3295
3296 Use @code{-serial none} to disable all serial ports.
3297
3298 Available character devices are:
3299 @table @option
3300 @item vc[:@var{W}x@var{H}]
3301 Virtual console. Optionally, a width and height can be given in pixel with
3302 @example
3303 vc:800x600
3304 @end example
3305 It is also possible to specify width or height in characters:
3306 @example
3307 vc:80Cx24C
3308 @end example
3309 @item pty
3310 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3311 @item none
3312 No device is allocated.
3313 @item null
3314 void device
3315 @item chardev:@var{id}
3316 Use a named character device defined with the @code{-chardev} option.
3317 @item /dev/XXX
3318 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3319 parameters are set according to the emulated ones.
3320 @item /dev/parport@var{N}
3321 [Linux only, parallel port only] Use host parallel port
3322 @var{N}. Currently SPP and EPP parallel port features can be used.
3323 @item file:@var{filename}
3324 Write output to @var{filename}. No character can be read.
3325 @item stdio
3326 [Unix only] standard input/output
3327 @item pipe:@var{filename}
3328 name pipe @var{filename}
3329 @item COM@var{n}
3330 [Windows only] Use host serial port @var{n}
3331 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3332 This implements UDP Net Console.
3333 When @var{remote_host} or @var{src_ip} are not specified
3334 they default to @code{0.0.0.0}.
3335 When not using a specified @var{src_port} a random port is automatically chosen.
3336
3337 If you just want a simple readonly console you can use @code{netcat} or
3338 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3339 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
3340 will appear in the netconsole session.
3341
3342 If you plan to send characters back via netconsole or you want to stop
3343 and start QEMU a lot of times, you should have QEMU use the same
3344 source port each time by using something like @code{-serial
3345 udp::4555@@:4556} to QEMU. Another approach is to use a patched
3346 version of netcat which can listen to a TCP port and send and receive
3347 characters via udp.  If you have a patched version of netcat which
3348 activates telnet remote echo and single char transfer, then you can
3349 use the following options to set up a netcat redirector to allow
3350 telnet on port 5555 to access the QEMU port.
3351 @table @code
3352 @item QEMU Options:
3353 -serial udp::4555@@:4556
3354 @item netcat options:
3355 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3356 @item telnet options:
3357 localhost 5555
3358 @end table
3359
3360 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3361 The TCP Net Console has two modes of operation.  It can send the serial
3362 I/O to a location or wait for a connection from a location.  By default
3363 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
3364 the @var{server} option QEMU will wait for a client socket application
3365 to connect to the port before continuing, unless the @code{nowait}
3366 option was specified.  The @code{nodelay} option disables the Nagle buffering
3367 algorithm.  The @code{reconnect} option only applies if @var{noserver} is
3368 set, if the connection goes down it will attempt to reconnect at the
3369 given interval.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
3370 one TCP connection at a time is accepted. You can use @code{telnet} to
3371 connect to the corresponding character device.
3372 @table @code
3373 @item Example to send tcp console to 192.168.0.2 port 4444
3374 -serial tcp:192.168.0.2:4444
3375 @item Example to listen and wait on port 4444 for connection
3376 -serial tcp::4444,server
3377 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3378 -serial tcp:192.168.0.100:4444,server,nowait
3379 @end table
3380
3381 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3382 The telnet protocol is used instead of raw tcp sockets.  The options
3383 work the same as if you had specified @code{-serial tcp}.  The
3384 difference is that the port acts like a telnet server or client using
3385 telnet option negotiation.  This will also allow you to send the
3386 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3387 sequence.  Typically in unix telnet you do it with Control-] and then
3388 type "send break" followed by pressing the enter key.
3389
3390 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3391 A unix domain socket is used instead of a tcp socket.  The option works the
3392 same as if you had specified @code{-serial tcp} except the unix domain socket
3393 @var{path} is used for connections.
3394
3395 @item mon:@var{dev_string}
3396 This is a special option to allow the monitor to be multiplexed onto
3397 another serial port.  The monitor is accessed with key sequence of
3398 @key{Control-a} and then pressing @key{c}.
3399 @var{dev_string} should be any one of the serial devices specified
3400 above.  An example to multiplex the monitor onto a telnet server
3401 listening on port 4444 would be:
3402 @table @code
3403 @item -serial mon:telnet::4444,server,nowait
3404 @end table
3405 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3406 QEMU any more but will be passed to the guest instead.
3407
3408 @item braille
3409 Braille device.  This will use BrlAPI to display the braille output on a real
3410 or fake device.
3411
3412 @item msmouse
3413 Three button serial mouse. Configure the guest to use Microsoft protocol.
3414 @end table
3415 ETEXI
3416
3417 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3418     "-parallel dev   redirect the parallel port to char device 'dev'\n",
3419     QEMU_ARCH_ALL)
3420 STEXI
3421 @item -parallel @var{dev}
3422 @findex -parallel
3423 Redirect the virtual parallel port to host device @var{dev} (same
3424 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3425 be used to use hardware devices connected on the corresponding host
3426 parallel port.
3427
3428 This option can be used several times to simulate up to 3 parallel
3429 ports.
3430
3431 Use @code{-parallel none} to disable all parallel ports.
3432 ETEXI
3433
3434 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3435     "-monitor dev    redirect the monitor to char device 'dev'\n",
3436     QEMU_ARCH_ALL)
3437 STEXI
3438 @item -monitor @var{dev}
3439 @findex -monitor
3440 Redirect the monitor to host device @var{dev} (same devices as the
3441 serial port).
3442 The default device is @code{vc} in graphical mode and @code{stdio} in
3443 non graphical mode.
3444 Use @code{-monitor none} to disable the default monitor.
3445 ETEXI
3446 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3447     "-qmp dev        like -monitor but opens in 'control' mode\n",
3448     QEMU_ARCH_ALL)
3449 STEXI
3450 @item -qmp @var{dev}
3451 @findex -qmp
3452 Like -monitor but opens in 'control' mode.
3453 ETEXI
3454 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3455     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3456     QEMU_ARCH_ALL)
3457 STEXI
3458 @item -qmp-pretty @var{dev}
3459 @findex -qmp-pretty
3460 Like -qmp but uses pretty JSON formatting.
3461 ETEXI
3462
3463 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3464     "-mon [chardev=]name[,mode=readline|control]\n", QEMU_ARCH_ALL)
3465 STEXI
3466 @item -mon [chardev=]name[,mode=readline|control]
3467 @findex -mon
3468 Setup monitor on chardev @var{name}.
3469 ETEXI
3470
3471 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3472     "-debugcon dev   redirect the debug console to char device 'dev'\n",
3473     QEMU_ARCH_ALL)
3474 STEXI
3475 @item -debugcon @var{dev}
3476 @findex -debugcon
3477 Redirect the debug console to host device @var{dev} (same devices as the
3478 serial port).  The debug console is an I/O port which is typically port
3479 0xe9; writing to that I/O port sends output to this device.
3480 The default device is @code{vc} in graphical mode and @code{stdio} in
3481 non graphical mode.
3482 ETEXI
3483
3484 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3485     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
3486 STEXI
3487 @item -pidfile @var{file}
3488 @findex -pidfile
3489 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3490 from a script.
3491 ETEXI
3492
3493 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3494     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
3495 STEXI
3496 @item -singlestep
3497 @findex -singlestep
3498 Run the emulation in single step mode.
3499 ETEXI
3500
3501 DEF("S", 0, QEMU_OPTION_S, \
3502     "-S              freeze CPU at startup (use 'c' to start execution)\n",
3503     QEMU_ARCH_ALL)
3504 STEXI
3505 @item -S
3506 @findex -S
3507 Do not start CPU at startup (you must type 'c' in the monitor).
3508 ETEXI
3509
3510 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3511     "-realtime [mlock=on|off]\n"
3512     "                run qemu with realtime features\n"
3513     "                mlock=on|off controls mlock support (default: on)\n",
3514     QEMU_ARCH_ALL)
3515 STEXI
3516 @item -realtime mlock=on|off
3517 @findex -realtime
3518 Run qemu with realtime features.
3519 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3520 (enabled by default).
3521 ETEXI
3522
3523 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3524     "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
3525 STEXI
3526 @item -gdb @var{dev}
3527 @findex -gdb
3528 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3529 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3530 stdio are reasonable use case. The latter is allowing to start QEMU from
3531 within gdb and establish the connection via a pipe:
3532 @example
3533 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3534 @end example
3535 ETEXI
3536
3537 DEF("s", 0, QEMU_OPTION_s, \
3538     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3539     QEMU_ARCH_ALL)
3540 STEXI
3541 @item -s
3542 @findex -s
3543 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3544 (@pxref{gdb_usage}).
3545 ETEXI
3546
3547 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3548     "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
3549     QEMU_ARCH_ALL)
3550 STEXI
3551 @item -d @var{item1}[,...]
3552 @findex -d
3553 Enable logging of specified items. Use '-d help' for a list of log items.
3554 ETEXI
3555
3556 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3557     "-D logfile      output log to logfile (default stderr)\n",
3558     QEMU_ARCH_ALL)
3559 STEXI
3560 @item -D @var{logfile}
3561 @findex -D
3562 Output log in @var{logfile} instead of to stderr
3563 ETEXI
3564
3565 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3566     "-dfilter range,..  filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3567     QEMU_ARCH_ALL)
3568 STEXI
3569 @item -dfilter @var{range1}[,...]
3570 @findex -dfilter
3571 Filter debug output to that relevant to a range of target addresses. The filter
3572 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3573 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3574 addresses and sizes required. For example:
3575 @example
3576     -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3577 @end example
3578 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3579 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3580 block starting at 0xffffffc00005f000.
3581 ETEXI
3582
3583 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3584     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
3585     QEMU_ARCH_ALL)
3586 STEXI
3587 @item -L  @var{path}
3588 @findex -L
3589 Set the directory for the BIOS, VGA BIOS and keymaps.
3590
3591 To list all the data directories, use @code{-L help}.
3592 ETEXI
3593
3594 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3595     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
3596 STEXI
3597 @item -bios @var{file}
3598 @findex -bios
3599 Set the filename for the BIOS.
3600 ETEXI
3601
3602 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3603     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3604 STEXI
3605 @item -enable-kvm
3606 @findex -enable-kvm
3607 Enable KVM full virtualization support. This option is only available
3608 if KVM support is enabled when compiling.
3609 ETEXI
3610
3611 DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3612     "-enable-hax     enable HAX virtualization support\n", QEMU_ARCH_I386)
3613 STEXI
3614 @item -enable-hax
3615 @findex -enable-hax
3616 Enable HAX (Hardware-based Acceleration eXecution) support. This option
3617 is only available if HAX support is enabled when compiling. HAX is only
3618 applicable to MAC and Windows platform, and thus does not conflict with
3619 KVM.
3620 ETEXI
3621
3622 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3623     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
3624 DEF("xen-create", 0, QEMU_OPTION_xen_create,
3625     "-xen-create     create domain using xen hypercalls, bypassing xend\n"
3626     "                warning: should not be used when xend is in use\n",
3627     QEMU_ARCH_ALL)
3628 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3629     "-xen-attach     attach to existing xen domain\n"
3630     "                xend will use this when starting QEMU\n",
3631     QEMU_ARCH_ALL)
3632 DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3633     "-xen-domid-restrict     restrict set of available xen operations\n"
3634     "                        to specified domain id. (Does not affect\n"
3635     "                        xenpv machine type).\n",
3636     QEMU_ARCH_ALL)
3637 STEXI
3638 @item -xen-domid @var{id}
3639 @findex -xen-domid
3640 Specify xen guest domain @var{id} (XEN only).
3641 @item -xen-create
3642 @findex -xen-create
3643 Create domain using xen hypercalls, bypassing xend.
3644 Warning: should not be used when xend is in use (XEN only).
3645 @item -xen-attach
3646 @findex -xen-attach
3647 Attach to existing xen domain.
3648 xend will use this when starting QEMU (XEN only).
3649 @findex -xen-domid-restrict
3650 Restrict set of available xen operations to specified domain id (XEN only).
3651 ETEXI
3652
3653 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3654     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
3655 STEXI
3656 @item -no-reboot
3657 @findex -no-reboot
3658 Exit instead of rebooting.
3659 ETEXI
3660
3661 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3662     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
3663 STEXI
3664 @item -no-shutdown
3665 @findex -no-shutdown
3666 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3667 This allows for instance switching to monitor to commit changes to the
3668 disk image.
3669 ETEXI
3670
3671 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3672     "-loadvm [tag|id]\n" \
3673     "                start right away with a saved state (loadvm in monitor)\n",
3674     QEMU_ARCH_ALL)
3675 STEXI
3676 @item -loadvm @var{file}
3677 @findex -loadvm
3678 Start right away with a saved state (@code{loadvm} in monitor)
3679 ETEXI
3680
3681 #ifndef _WIN32
3682 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3683     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3684 #endif
3685 STEXI
3686 @item -daemonize
3687 @findex -daemonize
3688 Daemonize the QEMU process after initialization.  QEMU will not detach from
3689 standard IO until it is ready to receive connections on any of its devices.
3690 This option is a useful way for external programs to launch QEMU without having
3691 to cope with initialization race conditions.
3692 ETEXI
3693
3694 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3695     "-option-rom rom load a file, rom, into the option ROM space\n",
3696     QEMU_ARCH_ALL)
3697 STEXI
3698 @item -option-rom @var{file}
3699 @findex -option-rom
3700 Load the contents of @var{file} as an option ROM.
3701 This option is useful to load things like EtherBoot.
3702 ETEXI
3703
3704 HXCOMM Silently ignored for compatibility
3705 DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
3706
3707 HXCOMM Options deprecated by -rtc
3708 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3709 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
3710
3711 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3712     "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3713     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3714     QEMU_ARCH_ALL)
3715
3716 STEXI
3717
3718 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3719 @findex -rtc
3720 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3721 UTC or local time, respectively. @code{localtime} is required for correct date in
3722 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3723 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3724
3725 By default the RTC is driven by the host system time. This allows using of the
3726 RTC as accurate reference clock inside the guest, specifically if the host
3727 time is smoothly following an accurate external reference clock, e.g. via NTP.
3728 If you want to isolate the guest time from the host, you can set @option{clock}
3729 to @code{rt} instead.  To even prevent it from progressing during suspension,
3730 you can set it to @code{vm}.
3731
3732 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3733 specifically with Windows' ACPI HAL. This option will try to figure out how
3734 many timer interrupts were not processed by the Windows guest and will
3735 re-inject them.
3736 ETEXI
3737
3738 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
3739     "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
3740     "                enable virtual instruction counter with 2^N clock ticks per\n" \
3741     "                instruction, enable aligning the host and virtual clocks\n" \
3742     "                or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
3743 STEXI
3744 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
3745 @findex -icount
3746 Enable virtual instruction counter.  The virtual cpu will execute one
3747 instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
3748 then the virtual cpu speed will be automatically adjusted to keep virtual
3749 time within a few seconds of real time.
3750
3751 When the virtual cpu is sleeping, the virtual time will advance at default
3752 speed unless @option{sleep=on|off} is specified.
3753 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3754 instantly whenever the virtual cpu goes to sleep mode and will not advance
3755 if no timer is enabled. This behavior give deterministic execution times from
3756 the guest point of view.
3757
3758 Note that while this option can give deterministic behavior, it does not
3759 provide cycle accurate emulation.  Modern CPUs contain superscalar out of
3760 order cores with complex cache hierarchies.  The number of instructions
3761 executed often has little or no correlation with actual performance.
3762
3763 @option{align=on} will activate the delay algorithm which will try
3764 to synchronise the host clock and the virtual clock. The goal is to
3765 have a guest running at the real frequency imposed by the shift option.
3766 Whenever the guest clock is behind the host clock and if
3767 @option{align=on} is specified then we print a message to the user
3768 to inform about the delay.
3769 Currently this option does not work when @option{shift} is @code{auto}.
3770 Note: The sync algorithm will work for those shift values for which
3771 the guest clock runs ahead of the host clock. Typically this happens
3772 when the shift value is high (how high depends on the host machine).
3773
3774 When @option{rr} option is specified deterministic record/replay is enabled.
3775 Replay log is written into @var{filename} file in record mode and
3776 read from this file in replay mode.
3777
3778 Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3779 at the start of execution recording. In replay mode this option is used
3780 to load the initial VM state.
3781 ETEXI
3782
3783 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3784     "-watchdog model\n" \
3785     "                enable virtual hardware watchdog [default=none]\n",
3786     QEMU_ARCH_ALL)
3787 STEXI
3788 @item -watchdog @var{model}
3789 @findex -watchdog
3790 Create a virtual hardware watchdog device.  Once enabled (by a guest
3791 action), the watchdog must be periodically polled by an agent inside
3792 the guest or else the guest will be restarted. Choose a model for
3793 which your guest has drivers.
3794
3795 The @var{model} is the model of hardware watchdog to emulate. Use
3796 @code{-watchdog help} to list available hardware models. Only one
3797 watchdog can be enabled for a guest.
3798
3799 The following models may be available:
3800 @table @option
3801 @item ib700
3802 iBASE 700 is a very simple ISA watchdog with a single timer.
3803 @item i6300esb
3804 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3805 dual-timer watchdog.
3806 @item diag288
3807 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3808 (currently KVM only).
3809 @end table
3810 ETEXI
3811
3812 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3813     "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
3814     "                action when watchdog fires [default=reset]\n",
3815     QEMU_ARCH_ALL)
3816 STEXI
3817 @item -watchdog-action @var{action}
3818 @findex -watchdog-action
3819
3820 The @var{action} controls what QEMU will do when the watchdog timer
3821 expires.
3822 The default is
3823 @code{reset} (forcefully reset the guest).
3824 Other possible actions are:
3825 @code{shutdown} (attempt to gracefully shutdown the guest),
3826 @code{poweroff} (forcefully poweroff the guest),
3827 @code{pause} (pause the guest),
3828 @code{debug} (print a debug message and continue), or
3829 @code{none} (do nothing).
3830
3831 Note that the @code{shutdown} action requires that the guest responds
3832 to ACPI signals, which it may not be able to do in the sort of
3833 situations where the watchdog would have expired, and thus
3834 @code{-watchdog-action shutdown} is not recommended for production use.
3835
3836 Examples:
3837
3838 @table @code
3839 @item -watchdog i6300esb -watchdog-action pause
3840 @itemx -watchdog ib700
3841 @end table
3842 ETEXI
3843
3844 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
3845     "-echr chr       set terminal escape character instead of ctrl-a\n",
3846     QEMU_ARCH_ALL)
3847 STEXI
3848
3849 @item -echr @var{numeric_ascii_value}
3850 @findex -echr
3851 Change the escape character used for switching to the monitor when using
3852 monitor and serial sharing.  The default is @code{0x01} when using the
3853 @code{-nographic} option.  @code{0x01} is equal to pressing
3854 @code{Control-a}.  You can select a different character from the ascii
3855 control keys where 1 through 26 map to Control-a through Control-z.  For
3856 instance you could use the either of the following to change the escape
3857 character to Control-t.
3858 @table @code
3859 @item -echr 0x14
3860 @itemx -echr 20
3861 @end table
3862 ETEXI
3863
3864 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3865     "-virtioconsole c\n" \
3866     "                set virtio console\n", QEMU_ARCH_ALL)
3867 STEXI
3868 @item -virtioconsole @var{c}
3869 @findex -virtioconsole
3870 Set virtio console.
3871
3872 This option is maintained for backward compatibility.
3873
3874 Please use @code{-device virtconsole} for the new way of invocation.
3875 ETEXI
3876
3877 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
3878     "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
3879 STEXI
3880 @item -show-cursor
3881 @findex -show-cursor
3882 Show cursor.
3883 ETEXI
3884
3885 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
3886     "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
3887 STEXI
3888 @item -tb-size @var{n}
3889 @findex -tb-size
3890 Set TB size.
3891 ETEXI
3892
3893 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
3894     "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3895     "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3896     "-incoming unix:socketpath\n" \
3897     "                prepare for incoming migration, listen on\n" \
3898     "                specified protocol and socket address\n" \
3899     "-incoming fd:fd\n" \
3900     "-incoming exec:cmdline\n" \
3901     "                accept incoming migration on given file descriptor\n" \
3902     "                or from given external command\n" \
3903     "-incoming defer\n" \
3904     "                wait for the URI to be specified via migrate_incoming\n",
3905     QEMU_ARCH_ALL)
3906 STEXI
3907 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3908 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3909 @findex -incoming
3910 Prepare for incoming migration, listen on a given tcp port.
3911
3912 @item -incoming unix:@var{socketpath}
3913 Prepare for incoming migration, listen on a given unix socket.
3914
3915 @item -incoming fd:@var{fd}
3916 Accept incoming migration from a given filedescriptor.
3917
3918 @item -incoming exec:@var{cmdline}
3919 Accept incoming migration as an output from specified external command.
3920
3921 @item -incoming defer
3922 Wait for the URI to be specified via migrate_incoming.  The monitor can
3923 be used to change settings (such as migration parameters) prior to issuing
3924 the migrate_incoming to allow the migration to begin.
3925 ETEXI
3926
3927 DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3928     "-only-migratable     allow only migratable devices\n", QEMU_ARCH_ALL)
3929 STEXI
3930 @item -only-migratable
3931 @findex -only-migratable
3932 Only allow migratable devices. Devices will not be allowed to enter an
3933 unmigratable state.
3934 ETEXI
3935
3936 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
3937     "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
3938 STEXI
3939 @item -nodefaults
3940 @findex -nodefaults
3941 Don't create default devices. Normally, QEMU sets the default devices like serial
3942 port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3943 CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3944 default devices.
3945 ETEXI
3946
3947 #ifndef _WIN32
3948 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
3949     "-chroot dir     chroot to dir just before starting the VM\n",
3950     QEMU_ARCH_ALL)
3951 #endif
3952 STEXI
3953 @item -chroot @var{dir}
3954 @findex -chroot
3955 Immediately before starting guest execution, chroot to the specified
3956 directory.  Especially useful in combination with -runas.
3957 ETEXI
3958
3959 #ifndef _WIN32
3960 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
3961     "-runas user     change to user id user just before starting the VM\n",
3962     QEMU_ARCH_ALL)
3963 #endif
3964 STEXI
3965 @item -runas @var{user}
3966 @findex -runas
3967 Immediately before starting guest execution, drop root privileges, switching
3968 to the specified user.
3969 ETEXI
3970
3971 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3972     "-prom-env variable=value\n"
3973     "                set OpenBIOS nvram variables\n",
3974     QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
3975 STEXI
3976 @item -prom-env @var{variable}=@var{value}
3977 @findex -prom-env
3978 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3979 ETEXI
3980 DEF("semihosting", 0, QEMU_OPTION_semihosting,
3981     "-semihosting    semihosting mode\n",
3982     QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3983     QEMU_ARCH_MIPS)
3984 STEXI
3985 @item -semihosting
3986 @findex -semihosting
3987 Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
3988 ETEXI
3989 DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
3990     "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3991     "                semihosting configuration\n",
3992 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3993 QEMU_ARCH_MIPS)
3994 STEXI
3995 @item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
3996 @findex -semihosting-config
3997 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
3998 @table @option
3999 @item target=@code{native|gdb|auto}
4000 Defines where the semihosting calls will be addressed, to QEMU (@code{native})
4001 or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
4002 during debug sessions and @code{native} otherwise.
4003 @item arg=@var{str1},arg=@var{str2},...
4004 Allows the user to pass input arguments, and can be used multiple times to build
4005 up a list. The old-style @code{-kernel}/@code{-append} method of passing a
4006 command line is still supported for backward compatibility. If both the
4007 @code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
4008 specified, the former is passed to semihosting as it always takes precedence.
4009 @end table
4010 ETEXI
4011 DEF("old-param", 0, QEMU_OPTION_old_param,
4012     "-old-param      old param mode\n", QEMU_ARCH_ARM)
4013 STEXI
4014 @item -old-param
4015 @findex -old-param (ARM)
4016 Old param mode (ARM only).
4017 ETEXI
4018
4019 DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
4020     "-sandbox <arg>  Enable seccomp mode 2 system call filter (default 'off').\n",
4021     QEMU_ARCH_ALL)
4022 STEXI
4023 @item -sandbox @var{arg}
4024 @findex -sandbox
4025 Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
4026 disable it.  The default is 'off'.
4027 ETEXI
4028
4029 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
4030     "-readconfig <file>\n", QEMU_ARCH_ALL)
4031 STEXI
4032 @item -readconfig @var{file}
4033 @findex -readconfig
4034 Read device configuration from @var{file}. This approach is useful when you want to spawn
4035 QEMU process with many command line options but you don't want to exceed the command line
4036 character limit.
4037 ETEXI
4038 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
4039     "-writeconfig <file>\n"
4040     "                read/write config file\n", QEMU_ARCH_ALL)
4041 STEXI
4042 @item -writeconfig @var{file}
4043 @findex -writeconfig
4044 Write device configuration to @var{file}. The @var{file} can be either filename to save
4045 command line and device configuration into file or dash @code{-}) character to print the
4046 output to stdout. This can be later used as input file for @code{-readconfig} option.
4047 ETEXI
4048 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
4049     "-nodefconfig\n"
4050     "                do not load default config files at startup\n",
4051     QEMU_ARCH_ALL)
4052 STEXI
4053 @item -nodefconfig
4054 @findex -nodefconfig
4055 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
4056 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
4057 ETEXI
4058 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
4059     "-no-user-config\n"
4060     "                do not load user-provided config files at startup\n",
4061     QEMU_ARCH_ALL)
4062 STEXI
4063 @item -no-user-config
4064 @findex -no-user-config
4065 The @code{-no-user-config} option makes QEMU not load any of the user-provided
4066 config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
4067 files from @var{datadir}.
4068 ETEXI
4069 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
4070     "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
4071     "                specify tracing options\n",
4072     QEMU_ARCH_ALL)
4073 STEXI
4074 HXCOMM This line is not accurate, as some sub-options are backend-specific but
4075 HXCOMM HX does not support conditional compilation of text.
4076 @item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
4077 @findex -trace
4078 @include qemu-option-trace.texi
4079 ETEXI
4080
4081 HXCOMM Internal use
4082 DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
4083 DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
4084
4085 #ifdef __linux__
4086 DEF("enable-fips", 0, QEMU_OPTION_enablefips,
4087     "-enable-fips    enable FIPS 140-2 compliance\n",
4088     QEMU_ARCH_ALL)
4089 #endif
4090 STEXI
4091 @item -enable-fips
4092 @findex -enable-fips
4093 Enable FIPS 140-2 compliance mode.
4094 ETEXI
4095
4096 HXCOMM Deprecated by -machine accel=tcg property
4097 DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
4098
4099 HXCOMM Deprecated by kvm-pit driver properties
4100 DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
4101     "", QEMU_ARCH_I386)
4102
4103 HXCOMM Deprecated (ignored)
4104 DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
4105
4106 HXCOMM Deprecated by -machine kernel_irqchip=on|off property
4107 DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
4108
4109 HXCOMM Deprecated (ignored)
4110 DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
4111
4112 DEF("msg", HAS_ARG, QEMU_OPTION_msg,
4113     "-msg timestamp[=on|off]\n"
4114     "                change the format of messages\n"
4115     "                on|off controls leading timestamps (default:on)\n",
4116     QEMU_ARCH_ALL)
4117 STEXI
4118 @item -msg timestamp[=on|off]
4119 @findex -msg
4120 prepend a timestamp to each log message.(default:on)
4121 ETEXI
4122
4123 DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
4124     "-dump-vmstate <file>\n"
4125     "                Output vmstate information in JSON format to file.\n"
4126     "                Use the scripts/vmstate-static-checker.py file to\n"
4127     "                check for possible regressions in migration code\n"
4128     "                by comparing two such vmstate dumps.\n",
4129     QEMU_ARCH_ALL)
4130 STEXI
4131 @item -dump-vmstate @var{file}
4132 @findex -dump-vmstate
4133 Dump json-encoded vmstate information for current machine type to file
4134 in @var{file}
4135 ETEXI
4136
4137 STEXI
4138 @end table
4139 ETEXI
4140 DEFHEADING()
4141 DEFHEADING(Generic object creation)
4142 STEXI
4143 @table @option
4144 ETEXI
4145
4146 DEF("object", HAS_ARG, QEMU_OPTION_object,
4147     "-object TYPENAME[,PROP1=VALUE1,...]\n"
4148     "                create a new object of type TYPENAME setting properties\n"
4149     "                in the order they are specified.  Note that the 'id'\n"
4150     "                property must be set.  These objects are placed in the\n"
4151     "                '/objects' path.\n",
4152     QEMU_ARCH_ALL)
4153 STEXI
4154 @item -object @var{typename}[,@var{prop1}=@var{value1},...]
4155 @findex -object
4156 Create a new object of type @var{typename} setting properties
4157 in the order they are specified.  Note that the 'id'
4158 property must be set.  These objects are placed in the
4159 '/objects' path.
4160
4161 @table @option
4162
4163 @item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off}
4164
4165 Creates a memory file backend object, which can be used to back
4166 the guest RAM with huge pages. The @option{id} parameter is a
4167 unique ID that will be used to reference this memory region
4168 when configuring the @option{-numa} argument. The @option{size}
4169 option provides the size of the memory region, and accepts
4170 common suffixes, eg @option{500M}. The @option{mem-path} provides
4171 the path to either a shared memory or huge page filesystem mount.
4172 The @option{share} boolean option determines whether the memory
4173 region is marked as private to QEMU, or shared. The latter allows
4174 a co-operating external process to access the QEMU memory region.
4175
4176 @item -object rng-random,id=@var{id},filename=@var{/dev/random}
4177
4178 Creates a random number generator backend which obtains entropy from
4179 a device on the host. The @option{id} parameter is a unique ID that
4180 will be used to reference this entropy backend from the @option{virtio-rng}
4181 device. The @option{filename} parameter specifies which file to obtain
4182 entropy from and if omitted defaults to @option{/dev/random}.
4183
4184 @item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4185
4186 Creates a random number generator backend which obtains entropy from
4187 an external daemon running on the host. The @option{id} parameter is
4188 a unique ID that will be used to reference this entropy backend from
4189 the @option{virtio-rng} device. The @option{chardev} parameter is
4190 the unique ID of a character device backend that provides the connection
4191 to the RNG daemon.
4192
4193 @item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4194
4195 Creates a TLS anonymous credentials object, which can be used to provide
4196 TLS support on network backends. The @option{id} parameter is a unique
4197 ID which network backends will use to access the credentials. The
4198 @option{endpoint} is either @option{server} or @option{client} depending
4199 on whether the QEMU network backend that uses the credentials will be
4200 acting as a client or as a server. If @option{verify-peer} is enabled
4201 (the default) then once the handshake is completed, the peer credentials
4202 will be verified, though this is a no-op for anonymous credentials.
4203
4204 The @var{dir} parameter tells QEMU where to find the credential
4205 files. For server endpoints, this directory may contain a file
4206 @var{dh-params.pem} providing diffie-hellman parameters to use
4207 for the TLS server. If the file is missing, QEMU will generate
4208 a set of DH parameters at startup. This is a computationally
4209 expensive operation that consumes random pool entropy, so it is
4210 recommended that a persistent set of parameters be generated
4211 upfront and saved.
4212
4213 @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}
4214
4215 Creates a TLS anonymous credentials object, which can be used to provide
4216 TLS support on network backends. The @option{id} parameter is a unique
4217 ID which network backends will use to access the credentials. The
4218 @option{endpoint} is either @option{server} or @option{client} depending
4219 on whether the QEMU network backend that uses the credentials will be
4220 acting as a client or as a server. If @option{verify-peer} is enabled
4221 (the default) then once the handshake is completed, the peer credentials
4222 will be verified. With x509 certificates, this implies that the clients
4223 must be provided with valid client certificates too.
4224
4225 The @var{dir} parameter tells QEMU where to find the credential
4226 files. For server endpoints, this directory may contain a file
4227 @var{dh-params.pem} providing diffie-hellman parameters to use
4228 for the TLS server. If the file is missing, QEMU will generate
4229 a set of DH parameters at startup. This is a computationally
4230 expensive operation that consumes random pool entropy, so it is
4231 recommended that a persistent set of parameters be generated
4232 upfront and saved.
4233
4234 For x509 certificate credentials the directory will contain further files
4235 providing the x509 certificates. The certificates must be stored
4236 in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4237 @var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4238 @var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4239
4240 For the @var{server-key.pem} and @var{client-key.pem} files which
4241 contain sensitive private keys, it is possible to use an encrypted
4242 version by providing the @var{passwordid} parameter. This provides
4243 the ID of a previously created @code{secret} object containing the
4244 password for decryption.
4245
4246 @item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
4247
4248 Interval @var{t} can't be 0, this filter batches the packet delivery: all
4249 packets arriving in a given interval on netdev @var{netdevid} are delayed
4250 until the end of the interval. Interval is in microseconds.
4251 @option{status} is optional that indicate whether the netfilter is
4252 on (enabled) or off (disabled), the default status for netfilter will be 'on'.
4253
4254 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4255
4256 @option{all}: the filter is attached both to the receive and the transmit
4257               queue of the netdev (default).
4258
4259 @option{rx}: the filter is attached to the receive queue of the netdev,
4260              where it will receive packets sent to the netdev.
4261
4262 @option{tx}: the filter is attached to the transmit queue of the netdev,
4263              where it will receive packets sent by the netdev.
4264
4265 @item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
4266
4267 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.
4268
4269 @item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
4270
4271 filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
4272 @var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4273 filter-redirector will redirect packet with vnet_hdr_len.
4274 Create a filter-redirector we need to differ outdev id from indev id, id can not
4275 be the same. we can just use indev or outdev, but at least one of indev or outdev
4276 need to be specified.
4277
4278 @item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support]
4279
4280 Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4281 secondary from primary to keep secondary tcp connection,and rewrite
4282 tcp packet to primary from secondary make tcp packet can be handled by
4283 client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
4284
4285 usage:
4286 colo secondary:
4287 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4288 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4289 -object filter-rewriter,id=rew0,netdev=hn0,queue=all
4290
4291 @item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
4292
4293 Dump the network traffic on netdev @var{dev} to the file specified by
4294 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4295 The file format is libpcap, so it can be analyzed with tools such as tcpdump
4296 or Wireshark.
4297
4298 @item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid}[,vnet_hdr_support]
4299
4300 Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4301 secondary packet. If the packets are same, we will output primary
4302 packet to outdev@var{chardevid}, else we will notify colo-frame
4303 do checkpoint and send primary packet to outdev@var{chardevid}.
4304 if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
4305
4306 we must use it with the help of filter-mirror and filter-redirector.
4307
4308 @example
4309
4310 primary:
4311 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4312 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4313 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4314 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4315 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4316 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4317 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4318 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4319 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4320 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4321 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4322 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4323
4324 secondary:
4325 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4326 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4327 -chardev socket,id=red0,host=3.3.3.3,port=9003
4328 -chardev socket,id=red1,host=3.3.3.3,port=9004
4329 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4330 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4331
4332 @end example
4333
4334 If you want to know the detail of above command line, you can read
4335 the colo-compare git log.
4336
4337 @item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4338
4339 Creates a cryptodev backend which executes crypto opreation from
4340 the QEMU cipher APIS. The @var{id} parameter is
4341 a unique ID that will be used to reference this cryptodev backend from
4342 the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4343 which specify the queue number of cryptodev backend, the default of
4344 @var{queues} is 1.
4345
4346 @example
4347
4348  # qemu-system-x86_64 \
4349    [...] \
4350        -object cryptodev-backend-builtin,id=cryptodev0 \
4351        -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4352    [...]
4353 @end example
4354
4355 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4356 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4357
4358 Defines a secret to store a password, encryption key, or some other sensitive
4359 data. The sensitive data can either be passed directly via the @var{data}
4360 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4361 parameter is insecure unless the sensitive data is encrypted.
4362
4363 The sensitive data can be provided in raw format (the default), or base64.
4364 When encoded as JSON, the raw format only supports valid UTF-8 characters,
4365 so base64 is recommended for sending binary data. QEMU will convert from
4366 which ever format is provided to the format it needs internally. eg, an
4367 RBD password can be provided in raw format, even though it will be base64
4368 encoded when passed onto the RBD sever.
4369
4370 For added protection, it is possible to encrypt the data associated with
4371 a secret using the AES-256-CBC cipher. Use of encryption is indicated
4372 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4373 parameter provides the ID of a previously defined secret that contains
4374 the AES-256 decryption key. This key should be 32-bytes long and be
4375 base64 encoded. The @var{iv} parameter provides the random initialization
4376 vector used for encryption of this particular secret and should be a
4377 base64 encrypted string of the 16-byte IV.
4378
4379 The simplest (insecure) usage is to provide the secret inline
4380
4381 @example
4382
4383  # $QEMU -object secret,id=sec0,data=letmein,format=raw
4384
4385 @end example
4386
4387 The simplest secure usage is to provide the secret via a file
4388
4389  # printf "letmein" > mypasswd.txt
4390  # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4391
4392 For greater security, AES-256-CBC should be used. To illustrate usage,
4393 consider the openssl command line tool which can encrypt the data. Note
4394 that when encrypting, the plaintext must be padded to the cipher block
4395 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4396
4397 First a master key needs to be created in base64 encoding:
4398
4399 @example
4400  # openssl rand -base64 32 > key.b64
4401  # KEY=$(base64 -d key.b64 | hexdump  -v -e '/1 "%02X"')
4402 @end example
4403
4404 Each secret to be encrypted needs to have a random initialization vector
4405 generated. These do not need to be kept secret
4406
4407 @example
4408  # openssl rand -base64 16 > iv.b64
4409  # IV=$(base64 -d iv.b64 | hexdump  -v -e '/1 "%02X"')
4410 @end example
4411
4412 The secret to be defined can now be encrypted, in this case we're
4413 telling openssl to base64 encode the result, but it could be left
4414 as raw bytes if desired.
4415
4416 @example
4417  # SECRET=$(printf "letmein" |
4418             openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4419 @end example
4420
4421 When launching QEMU, create a master secret pointing to @code{key.b64}
4422 and specify that to be used to decrypt the user password. Pass the
4423 contents of @code{iv.b64} to the second secret
4424
4425 @example
4426  # $QEMU \
4427      -object secret,id=secmaster0,format=base64,file=key.b64 \
4428      -object secret,id=sec0,keyid=secmaster0,format=base64,\
4429          data=$SECRET,iv=$(<iv.b64)
4430 @end example
4431
4432 @end table
4433
4434 ETEXI
4435
4436
4437 HXCOMM This is the last statement. Insert new options before this line!
4438 STEXI
4439 @end table
4440 ETEXI