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