fw_cfg: follow CODING_STYLE
[qemu/ar7.git] / qemu-options.hx
blob272630f639c7e7b37da1388166820614749f4e48
1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
6 HXCOMM architectures.
7 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
9 DEFHEADING(Standard options:)
10 STEXI
11 @table @option
12 ETEXI
14 DEF("help", 0, QEMU_OPTION_h,
15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL)
16 STEXI
17 @item -h
18 @findex -h
19 Display help and exit
20 ETEXI
22 DEF("version", 0, QEMU_OPTION_version,
23 "-version display version information and exit\n", QEMU_ARCH_ALL)
24 STEXI
25 @item -version
26 @findex -version
27 Display version information and exit
28 ETEXI
30 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31 "-machine [type=]name[,prop[=value][,...]]\n"
32 " selects emulated machine ('-machine help' for list)\n"
33 " property accel=accel1[:accel2[:...]] selects accelerator\n"
34 " supported accelerators are kvm, xen, 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 in bytes\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
91 HXCOMM Deprecated by -machine
92 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
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
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
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.
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
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
150 Add a file descriptor to an fd set. Valid options are:
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
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
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
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.:
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
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}.
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
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}.
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.
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.
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.
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.
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
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
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.
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:
276 @example
277 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
278 @end example
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
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
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
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.
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
320 The default is @code{en-us}.
321 ETEXI
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
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.
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
354 Note that Linux's i810_audio OSS kernel (for AC97) module might
355 require manually specifying clocking.
357 @example
358 modprobe i810_audio clocking=48000
359 @end example
360 ETEXI
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
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}.
390 Some drivers are:
391 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}]
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
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
403 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
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.
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.
418 See the "lanserv/README.vm" file in the OpenIPMI library for more
419 details on the external interface.
421 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
423 Add a KCS IPMI interafce on the ISA bus. This also adds a
424 corresponding ACPI and SMBIOS entries, if appropriate.
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
436 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
438 Like the KCS interface, but defines a BT interface. The default port is
439 0xe4 and the default interrupt is 5.
441 ETEXI
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
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
469 STEXI
470 @end table
471 ETEXI
472 DEFHEADING()
474 DEFHEADING(Block device options:)
475 STEXI
476 @table @option
477 ETEXI
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
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
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
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
538 Define a new drive. Valid options are:
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").
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 specify 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
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.
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.
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.
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}.
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.
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.
629 Instead of @option{-cdrom} you can use:
630 @example
631 qemu-system-i386 -drive file=file,index=2,media=cdrom
632 @end example
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
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
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
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
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
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
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
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
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
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
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
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
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)
739 STEXI
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
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
794 ETEXI
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)
801 STEXI
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
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
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
857 STEXI
858 @end table
859 ETEXI
860 DEFHEADING()
862 DEFHEADING(USB options:)
863 STEXI
864 @table @option
865 ETEXI
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
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
881 @item -usbdevice @var{devname}
882 @findex -usbdevice
883 Add the USB device @var{devname}. @xref{usb_devices}.
885 @table @option
887 @item mouse
888 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
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.
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 specify
898 @code{format=raw} to avoid interpreting an untrusted format header.
900 @item host:@var{bus}.@var{addr}
901 Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
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).
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.
911 @item braille
912 Braille device. This will use BrlAPI to display the braille output on a real
913 or fake device.
915 @item net:@var{options}
916 Network adapter that supports CDC ethernet and RNDIS protocols.
918 @end table
919 ETEXI
921 STEXI
922 @end table
923 ETEXI
924 DEFHEADING()
926 DEFHEADING(Display options:)
927 STEXI
928 @table @option
929 ETEXI
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
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
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
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
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
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
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
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
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
1064 @table @option
1066 @item port=<nr>
1067 Set the TCP port spice is listening on for plaintext channels.
1069 @item addr=<addr>
1070 Set the IP address spice is listening on. Default is any address.
1072 @item ipv4
1073 @itemx ipv6
1074 @itemx unix
1075 Force using the specified IP version.
1077 @item password=<secret>
1078 Set the password you need to authenticate.
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.
1093 @item disable-ticketing
1094 Allow client connects without authentication.
1096 @item disable-copy-paste
1097 Disable copy paste between the client and the guest.
1099 @item disable-agent-file-xfer
1100 Disable spice-vdagent based file-xfer between the client and the guest.
1102 @item tls-port=<nr>
1103 Set the TCP port spice is listening on for encrypted channels.
1105 @item x509-dir=<dir>
1106 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
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.
1115 @item tls-ciphers=<list>
1116 Specify which ciphers to use.
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.
1126 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1127 Configure image compression (lossless).
1128 Default is auto_glz.
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.
1135 @item streaming-video=[off|all|filter]
1136 Configure video stream detection. Default is filter.
1138 @item agent-mouse=[on|off]
1139 Enable/disable passing mouse events via vdagent. Default is on.
1141 @item playback-compression=[on|off]
1142 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1144 @item seamless-migration=[on|off]
1145 Enable/disable spice seamless migration. Default is off.
1147 @item gl=[on|off]
1148 Enable/disable OpenGL context. Default is off.
1150 @end table
1151 ETEXI
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
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
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
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
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
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
1242 @table @option
1244 @item @var{host}:@var{d}
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.
1250 @item unix:@var{path}
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.
1255 @item none
1257 VNC is initialized but not started. The monitor @code{change} command
1258 can be used to later start the VNC server.
1260 @end table
1262 Following the @var{display} value there may be one or more @var{option} flags
1263 separated by commas. Valid options are
1265 @table @option
1267 @item reverse
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.
1274 @item websocket
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.
1285 @item password
1287 Require that password based authentication is used for client connections.
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".
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).
1301 You can also use keywords "now" or "never" for the expiration time to
1302 allow <protocol> password to expire immediately or never expire.
1304 @item tls-creds=@var{ID}
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.
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.
1318 @item tls
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.
1325 This option is now deprecated in favor of using the @option{tls-creds}
1326 argument.
1328 @item x509=@var{/path/to/certificate/dir}
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.
1337 This option is now deprecated in favour of using the @option{tls-creds}
1338 argument.
1340 @item x509verify=@var{/path/to/certificate/dir}
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.
1353 This option is now deprecated in favour of using the @option{tls-creds}
1354 argument.
1356 @item sasl
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.
1371 @item acl
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.
1384 @item lossy
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.
1391 @item non-adaptive
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.
1400 @item share=[allow-exclusive|force-shared|ignore]
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.
1413 @item key-delay-ms
1415 Set keyboard delay, for key down and key up events, in milliseconds.
1416 Default is 1. Keyboards are low-bandwidth devices, so this slowdown
1417 can help the device and guest to keep up and not lose events in case
1418 events are arriving in bulk. Possible causes for the latter are flaky
1419 network connections, or scripts for automated testing.
1421 @end table
1422 ETEXI
1424 STEXI
1425 @end table
1426 ETEXI
1427 ARCHHEADING(, QEMU_ARCH_I386)
1429 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1430 STEXI
1431 @table @option
1432 ETEXI
1434 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1435 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1436 QEMU_ARCH_I386)
1437 STEXI
1438 @item -win2k-hack
1439 @findex -win2k-hack
1440 Use it when installing Windows 2000 to avoid a disk full bug. After
1441 Windows 2000 is installed, you no longer need this option (this option
1442 slows down the IDE transfers).
1443 ETEXI
1445 HXCOMM Deprecated by -rtc
1446 DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1448 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1449 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1450 QEMU_ARCH_I386)
1451 STEXI
1452 @item -no-fd-bootchk
1453 @findex -no-fd-bootchk
1454 Disable boot signature checking for floppy disks in BIOS. May
1455 be needed to boot from old floppy disks.
1456 ETEXI
1458 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1459 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1460 STEXI
1461 @item -no-acpi
1462 @findex -no-acpi
1463 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1464 it if your guest OS complains about ACPI problems (PC target machine
1465 only).
1466 ETEXI
1468 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1469 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
1470 STEXI
1471 @item -no-hpet
1472 @findex -no-hpet
1473 Disable HPET support.
1474 ETEXI
1476 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1477 "-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"
1478 " ACPI table description\n", QEMU_ARCH_I386)
1479 STEXI
1480 @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}]...]
1481 @findex -acpitable
1482 Add ACPI table with specified header fields and context from specified files.
1483 For file=, take whole ACPI table from the specified files, including all
1484 ACPI headers (possible overridden by other options).
1485 For data=, only data
1486 portion of the table is used, all header information is specified in the
1487 command line.
1488 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1489 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1490 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1491 spec.
1492 ETEXI
1494 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1495 "-smbios file=binary\n"
1496 " load SMBIOS entry from binary file\n"
1497 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1498 " [,uefi=on|off]\n"
1499 " specify SMBIOS type 0 fields\n"
1500 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1501 " [,uuid=uuid][,sku=str][,family=str]\n"
1502 " specify SMBIOS type 1 fields\n"
1503 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1504 " [,asset=str][,location=str]\n"
1505 " specify SMBIOS type 2 fields\n"
1506 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1507 " [,sku=str]\n"
1508 " specify SMBIOS type 3 fields\n"
1509 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1510 " [,asset=str][,part=str]\n"
1511 " specify SMBIOS type 4 fields\n"
1512 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
1513 " [,asset=str][,part=str][,speed=%d]\n"
1514 " specify SMBIOS type 17 fields\n",
1515 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1516 STEXI
1517 @item -smbios file=@var{binary}
1518 @findex -smbios
1519 Load SMBIOS entry from binary file.
1521 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
1522 Specify SMBIOS type 0 fields
1524 @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}]
1525 Specify SMBIOS type 1 fields
1527 @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}]
1528 Specify SMBIOS type 2 fields
1530 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1531 Specify SMBIOS type 3 fields
1533 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1534 Specify SMBIOS type 4 fields
1536 @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}]
1537 Specify SMBIOS type 17 fields
1538 ETEXI
1540 STEXI
1541 @end table
1542 ETEXI
1543 DEFHEADING()
1545 DEFHEADING(Network options:)
1546 STEXI
1547 @table @option
1548 ETEXI
1550 HXCOMM Legacy slirp options (now moved to -net user):
1551 #ifdef CONFIG_SLIRP
1552 DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1553 DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1554 DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1555 #ifndef _WIN32
1556 DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1557 #endif
1558 #endif
1560 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1561 #ifdef CONFIG_SLIRP
1562 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1563 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1564 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
1565 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n"
1566 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
1567 #ifndef _WIN32
1568 "[,smb=dir[,smbserver=addr]]\n"
1569 #endif
1570 " configure a user mode network backend with ID 'str',\n"
1571 " its DHCP server and optional services\n"
1572 #endif
1573 #ifdef _WIN32
1574 "-netdev tap,id=str,ifname=name\n"
1575 " configure a host TAP network backend with ID 'str'\n"
1576 #else
1577 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
1578 " [,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
1579 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
1580 " configure a host TAP network backend with ID 'str'\n"
1581 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1582 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1583 " to deconfigure it\n"
1584 " use '[down]script=no' to disable script execution\n"
1585 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1586 " configure it\n"
1587 " use 'fd=h' to connect to an already opened TAP interface\n"
1588 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
1589 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1590 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1591 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1592 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1593 " use vhost=on to enable experimental in kernel accelerator\n"
1594 " (only has effect for virtio guests which use MSIX)\n"
1595 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1596 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
1597 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
1598 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
1599 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1600 " configure a host TAP network backend with ID 'str' that is\n"
1601 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1602 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
1603 #endif
1604 #ifdef __linux__
1605 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1606 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1607 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1608 " [,rxcookie=rxcookie][,offset=offset]\n"
1609 " configure a network backend with ID 'str' connected to\n"
1610 " an Ethernet over L2TPv3 pseudowire.\n"
1611 " Linux kernel 3.3+ as well as most routers can talk\n"
1612 " L2TPv3. This transport allows connecting a VM to a VM,\n"
1613 " VM to a router and even VM to Host. It is a nearly-universal\n"
1614 " standard (RFC3391). Note - this implementation uses static\n"
1615 " pre-configured tunnels (same as the Linux kernel).\n"
1616 " use 'src=' to specify source address\n"
1617 " use 'dst=' to specify destination address\n"
1618 " use 'udp=on' to specify udp encapsulation\n"
1619 " use 'srcport=' to specify source udp port\n"
1620 " use 'dstport=' to specify destination udp port\n"
1621 " use 'ipv6=on' to force v6\n"
1622 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1623 " well as a weak security measure\n"
1624 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1625 " use 'txcookie=0x012345678' to specify a txcookie\n"
1626 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1627 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1628 " use 'pincounter=on' to work around broken counter handling in peer\n"
1629 " use 'offset=X' to add an extra offset between header and data\n"
1630 #endif
1631 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1632 " configure a network backend to connect to another network\n"
1633 " using a socket connection\n"
1634 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1635 " configure a network backend to connect to a multicast maddr and port\n"
1636 " use 'localaddr=addr' to specify the host address to send packets from\n"
1637 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1638 " configure a network backend to connect to another network\n"
1639 " using an UDP tunnel\n"
1640 #ifdef CONFIG_VDE
1641 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1642 " configure a network backend to connect to port 'n' of a vde switch\n"
1643 " running on host and listening for incoming connections on 'socketpath'.\n"
1644 " Use group 'groupname' and mode 'octalmode' to change default\n"
1645 " ownership and permissions for communication port.\n"
1646 #endif
1647 #ifdef CONFIG_NETMAP
1648 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
1649 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1650 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1651 " netmap device, defaults to '/dev/netmap')\n"
1652 #endif
1653 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1654 " configure a vhost-user network, backed by a chardev 'dev'\n"
1655 "-netdev hubport,id=str,hubid=n\n"
1656 " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL)
1657 DEF("net", HAS_ARG, QEMU_OPTION_net,
1658 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1659 " old way to create a new NIC and connect it to VLAN 'n'\n"
1660 " (use the '-device devtype,netdev=str' option if possible instead)\n"
1661 "-net dump[,vlan=n][,file=f][,len=n]\n"
1662 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
1663 "-net none use it alone to have zero network devices. If no -net option\n"
1664 " is provided, the default is '-net nic -net user'\n"
1665 "-net ["
1666 #ifdef CONFIG_SLIRP
1667 "user|"
1668 #endif
1669 "tap|"
1670 "bridge|"
1671 #ifdef CONFIG_VDE
1672 "vde|"
1673 #endif
1674 #ifdef CONFIG_NETMAP
1675 "netmap|"
1676 #endif
1677 "socket][,vlan=n][,option][,option][,...]\n"
1678 " old way to initialize a host network interface\n"
1679 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
1680 STEXI
1681 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1682 @findex -net
1683 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1684 = 0 is the default). The NIC is an e1000 by default on the PC
1685 target. Optionally, the MAC address can be changed to @var{mac}, the
1686 device address set to @var{addr} (PCI cards only),
1687 and a @var{name} can be assigned for use in monitor commands.
1688 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1689 that the card should have; this option currently only affects virtio cards; set
1690 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1691 NIC is created. QEMU can emulate several different models of network card.
1692 Valid values for @var{type} are
1693 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1694 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1695 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1696 Not all devices are supported on all targets. Use @code{-net nic,model=help}
1697 for a list of available devices for your target.
1699 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
1700 @findex -netdev
1701 @item -net user[,@var{option}][,@var{option}][,...]
1702 Use the user mode network stack which requires no administrator
1703 privilege to run. Valid options are:
1705 @table @option
1706 @item vlan=@var{n}
1707 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1709 @item id=@var{id}
1710 @itemx name=@var{name}
1711 Assign symbolic name for use in monitor commands.
1713 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
1714 be enabled. If neither is specified both protocols are enabled.
1716 @item net=@var{addr}[/@var{mask}]
1717 Set IP network address the guest will see. Optionally specify the netmask,
1718 either in the form a.b.c.d or as number of valid top-most bits. Default is
1719 10.0.2.0/24.
1721 @item host=@var{addr}
1722 Specify the guest-visible address of the host. Default is the 2nd IP in the
1723 guest network, i.e. x.x.x.2.
1725 @item ipv6-net=@var{addr}[/@var{int}]
1726 Set IPv6 network address the guest will see (default is fec0::/64). The
1727 network prefix is given in the usual hexadecimal IPv6 address
1728 notation. The prefix size is optional, and is given as the number of
1729 valid top-most bits (default is 64).
1731 @item ipv6-host=@var{addr}
1732 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
1733 the guest network, i.e. xxxx::2.
1735 @item restrict=on|off
1736 If this option is enabled, the guest will be isolated, i.e. it will not be
1737 able to contact the host and no guest IP packets will be routed over the host
1738 to the outside. This option does not affect any explicitly set forwarding rules.
1740 @item hostname=@var{name}
1741 Specifies the client hostname reported by the built-in DHCP server.
1743 @item dhcpstart=@var{addr}
1744 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1745 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1747 @item dns=@var{addr}
1748 Specify the guest-visible address of the virtual nameserver. The address must
1749 be different from the host address. Default is the 3rd IP in the guest network,
1750 i.e. x.x.x.3.
1752 @item ipv6-dns=@var{addr}
1753 Specify the guest-visible address of the IPv6 virtual nameserver. The address
1754 must be different from the host address. Default is the 3rd IP in the guest
1755 network, i.e. xxxx::3.
1757 @item dnssearch=@var{domain}
1758 Provides an entry for the domain-search list sent by the built-in
1759 DHCP server. More than one domain suffix can be transmitted by specifying
1760 this option multiple times. If supported, this will cause the guest to
1761 automatically try to append the given domain suffix(es) in case a domain name
1762 can not be resolved.
1764 Example:
1765 @example
1766 qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1767 @end example
1769 @item tftp=@var{dir}
1770 When using the user mode network stack, activate a built-in TFTP
1771 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1772 The TFTP client on the guest must be configured in binary mode (use the command
1773 @code{bin} of the Unix TFTP client).
1775 @item bootfile=@var{file}
1776 When using the user mode network stack, broadcast @var{file} as the BOOTP
1777 filename. In conjunction with @option{tftp}, this can be used to network boot
1778 a guest from a local directory.
1780 Example (using pxelinux):
1781 @example
1782 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1783 @end example
1785 @item smb=@var{dir}[,smbserver=@var{addr}]
1786 When using the user mode network stack, activate a built-in SMB
1787 server so that Windows OSes can access to the host files in @file{@var{dir}}
1788 transparently. The IP address of the SMB server can be set to @var{addr}. By
1789 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1791 In the guest Windows OS, the line:
1792 @example
1793 10.0.2.4 smbserver
1794 @end example
1795 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1796 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1798 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1800 Note that a SAMBA server must be installed on the host OS.
1801 QEMU was tested successfully with smbd versions from Red Hat 9,
1802 Fedora Core 3 and OpenSUSE 11.x.
1804 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1805 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1806 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1807 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1808 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1809 be bound to a specific host interface. If no connection type is set, TCP is
1810 used. This option can be given multiple times.
1812 For example, to redirect host X11 connection from screen 1 to guest
1813 screen 0, use the following:
1815 @example
1816 # on the host
1817 qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1818 # this host xterm should open in the guest X11 server
1819 xterm -display :1
1820 @end example
1822 To redirect telnet connections from host port 5555 to telnet port on
1823 the guest, use the following:
1825 @example
1826 # on the host
1827 qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
1828 telnet localhost 5555
1829 @end example
1831 Then when you use on the host @code{telnet localhost 5555}, you
1832 connect to the guest telnet server.
1834 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1835 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
1836 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1837 to the character device @var{dev} or to a program executed by @var{cmd:command}
1838 which gets spawned for each connection. This option can be given multiple times.
1840 You can either use a chardev directly and have that one used throughout QEMU's
1841 lifetime, like in the following example:
1843 @example
1844 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1845 # the guest accesses it
1846 qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
1847 @end example
1849 Or you can execute a command on every TCP connection established by the guest,
1850 so that QEMU behaves similar to an inetd process for that virtual server:
1852 @example
1853 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1854 # and connect the TCP stream to its stdin/stdout
1855 qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1856 @end example
1858 @end table
1860 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1861 processed and applied to -net user. Mixing them with the new configuration
1862 syntax gives undefined results. Their use for new applications is discouraged
1863 as they will be removed from future versions.
1865 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1866 @itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1867 Connect the host TAP network interface @var{name} to VLAN @var{n}.
1869 Use the network script @var{file} to configure it and the network script
1870 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1871 automatically provides one. The default network configure script is
1872 @file{/etc/qemu-ifup} and the default network deconfigure script is
1873 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1874 to disable script execution.
1876 If running QEMU as an unprivileged user, use the network helper
1877 @var{helper} to configure the TAP interface. The default network
1878 helper executable is @file{/path/to/qemu-bridge-helper}.
1880 @option{fd}=@var{h} can be used to specify the handle of an already
1881 opened host TAP interface.
1883 Examples:
1885 @example
1886 #launch a QEMU instance with the default network script
1887 qemu-system-i386 linux.img -net nic -net tap
1888 @end example
1890 @example
1891 #launch a QEMU instance with two NICs, each one connected
1892 #to a TAP device
1893 qemu-system-i386 linux.img \
1894 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1895 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1896 @end example
1898 @example
1899 #launch a QEMU instance with the default network helper to
1900 #connect a TAP device to bridge br0
1901 qemu-system-i386 linux.img \
1902 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
1903 @end example
1905 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
1906 @itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1907 Connect a host TAP network interface to a host bridge device.
1909 Use the network helper @var{helper} to configure the TAP interface and
1910 attach it to the bridge. The default network helper executable is
1911 @file{/path/to/qemu-bridge-helper} and the default bridge
1912 device is @file{br0}.
1914 Examples:
1916 @example
1917 #launch a QEMU instance with the default network helper to
1918 #connect a TAP device to bridge br0
1919 qemu-system-i386 linux.img -net bridge -net nic,model=virtio
1920 @end example
1922 @example
1923 #launch a QEMU instance with the default network helper to
1924 #connect a TAP device to bridge qemubr0
1925 qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
1926 @end example
1928 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1929 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1931 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1932 machine using a TCP socket connection. If @option{listen} is
1933 specified, QEMU waits for incoming connections on @var{port}
1934 (@var{host} is optional). @option{connect} is used to connect to
1935 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1936 specifies an already opened TCP socket.
1938 Example:
1939 @example
1940 # launch a first QEMU instance
1941 qemu-system-i386 linux.img \
1942 -net nic,macaddr=52:54:00:12:34:56 \
1943 -net socket,listen=:1234
1944 # connect the VLAN 0 of this instance to the VLAN 0
1945 # of the first instance
1946 qemu-system-i386 linux.img \
1947 -net nic,macaddr=52:54:00:12:34:57 \
1948 -net socket,connect=127.0.0.1:1234
1949 @end example
1951 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1952 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1954 Create a VLAN @var{n} shared with another QEMU virtual
1955 machines using a UDP multicast socket, effectively making a bus for
1956 every QEMU with same multicast address @var{maddr} and @var{port}.
1957 NOTES:
1958 @enumerate
1959 @item
1960 Several QEMU can be running on different hosts and share same bus (assuming
1961 correct multicast setup for these hosts).
1962 @item
1963 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1964 @url{http://user-mode-linux.sf.net}.
1965 @item
1966 Use @option{fd=h} to specify an already opened UDP multicast socket.
1967 @end enumerate
1969 Example:
1970 @example
1971 # launch one QEMU instance
1972 qemu-system-i386 linux.img \
1973 -net nic,macaddr=52:54:00:12:34:56 \
1974 -net socket,mcast=230.0.0.1:1234
1975 # launch another QEMU instance on same "bus"
1976 qemu-system-i386 linux.img \
1977 -net nic,macaddr=52:54:00:12:34:57 \
1978 -net socket,mcast=230.0.0.1:1234
1979 # launch yet another QEMU instance on same "bus"
1980 qemu-system-i386 linux.img \
1981 -net nic,macaddr=52:54:00:12:34:58 \
1982 -net socket,mcast=230.0.0.1:1234
1983 @end example
1985 Example (User Mode Linux compat.):
1986 @example
1987 # launch QEMU instance (note mcast address selected
1988 # is UML's default)
1989 qemu-system-i386 linux.img \
1990 -net nic,macaddr=52:54:00:12:34:56 \
1991 -net socket,mcast=239.192.168.1:1102
1992 # launch UML
1993 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1994 @end example
1996 Example (send packets from host's 1.2.3.4):
1997 @example
1998 qemu-system-i386 linux.img \
1999 -net nic,macaddr=52:54:00:12:34:56 \
2000 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2001 @end example
2003 @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}]
2004 @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}]
2005 Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
2006 protocol to transport Ethernet (and other Layer 2) data frames between
2007 two systems. It is present in routers, firewalls and the Linux kernel
2008 (from version 3.3 onwards).
2010 This transport allows a VM to communicate to another VM, router or firewall directly.
2012 @item src=@var{srcaddr}
2013 source address (mandatory)
2014 @item dst=@var{dstaddr}
2015 destination address (mandatory)
2016 @item udp
2017 select udp encapsulation (default is ip).
2018 @item srcport=@var{srcport}
2019 source udp port.
2020 @item dstport=@var{dstport}
2021 destination udp port.
2022 @item ipv6
2023 force v6, otherwise defaults to v4.
2024 @item rxcookie=@var{rxcookie}
2025 @itemx txcookie=@var{txcookie}
2026 Cookies are a weak form of security in the l2tpv3 specification.
2027 Their function is mostly to prevent misconfiguration. By default they are 32
2028 bit.
2029 @item cookie64
2030 Set cookie size to 64 bit instead of the default 32
2031 @item counter=off
2032 Force a 'cut-down' L2TPv3 with no counter as in
2033 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2034 @item pincounter=on
2035 Work around broken counter handling in peer. This may also help on
2036 networks which have packet reorder.
2037 @item offset=@var{offset}
2038 Add an extra offset between header and data
2040 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2041 on the remote Linux host 1.2.3.4:
2042 @example
2043 # Setup tunnel on linux host using raw ip as encapsulation
2044 # on 1.2.3.4
2045 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2046 encap udp udp_sport 16384 udp_dport 16384
2047 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2048 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2049 ifconfig vmtunnel0 mtu 1500
2050 ifconfig vmtunnel0 up
2051 brctl addif br-lan vmtunnel0
2054 # on 4.3.2.1
2055 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2057 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
2060 @end example
2062 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2063 @itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2064 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2065 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2066 and MODE @var{octalmode} to change default ownership and permissions for
2067 communication port. This option is only available if QEMU has been compiled
2068 with vde support enabled.
2070 Example:
2071 @example
2072 # launch vde switch
2073 vde_switch -F -sock /tmp/myswitch
2074 # launch QEMU instance
2075 qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
2076 @end example
2078 @item -netdev hubport,id=@var{id},hubid=@var{hubid}
2080 Create a hub port on QEMU "vlan" @var{hubid}.
2082 The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
2083 netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2084 required hub automatically.
2086 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2088 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2089 be a unix domain socket backed one. The vhost-user uses a specifically defined
2090 protocol to pass vhost ioctl replacement messages to an application on the other
2091 end of the socket. On non-MSIX guests, the feature can be forced with
2092 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2093 be created for multiqueue vhost-user.
2095 Example:
2096 @example
2097 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2098 -numa node,memdev=mem \
2099 -chardev socket,path=/path/to/socket \
2100 -netdev type=vhost-user,id=net0,chardev=chr0 \
2101 -device virtio-net-pci,netdev=net0
2102 @end example
2104 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2105 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2106 At most @var{len} bytes (64k by default) per packet are stored. The file format is
2107 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
2108 Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
2110 @item -net none
2111 Indicate that no network devices should be configured. It is used to
2112 override the default configuration (@option{-net nic -net user}) which
2113 is activated if no @option{-net} options are provided.
2114 ETEXI
2116 STEXI
2117 @end table
2118 ETEXI
2119 DEFHEADING()
2121 DEFHEADING(Character device options:)
2122 STEXI
2124 The general form of a character device option is:
2125 @table @option
2126 ETEXI
2128 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
2129 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2130 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2131 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
2132 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
2133 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2134 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
2135 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
2136 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
2137 " [,logfile=PATH][,logappend=on|off]\n"
2138 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2139 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
2140 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2141 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2142 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2143 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2144 #ifdef _WIN32
2145 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2146 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2147 #else
2148 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2149 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
2150 #endif
2151 #ifdef CONFIG_BRLAPI
2152 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2153 #endif
2154 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2155 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2156 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2157 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2158 #endif
2159 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2160 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2161 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2162 #endif
2163 #if defined(CONFIG_SPICE)
2164 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2165 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2166 #endif
2167 , QEMU_ARCH_ALL
2170 STEXI
2171 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
2172 @findex -chardev
2173 Backend is one of:
2174 @option{null},
2175 @option{socket},
2176 @option{udp},
2177 @option{msmouse},
2178 @option{vc},
2179 @option{ringbuf},
2180 @option{file},
2181 @option{pipe},
2182 @option{console},
2183 @option{serial},
2184 @option{pty},
2185 @option{stdio},
2186 @option{braille},
2187 @option{tty},
2188 @option{parallel},
2189 @option{parport},
2190 @option{spicevmc}.
2191 @option{spiceport}.
2192 The specific backend will determine the applicable options.
2194 All devices must have an id, which can be any string up to 127 characters long.
2195 It is used to uniquely identify this device in other command line directives.
2197 A character device may be used in multiplexing mode by multiple front-ends.
2198 Specify @option{mux=on} to enable this mode.
2199 A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2200 backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2201 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2202 create a multiplexer with your specified ID, and you can then configure multiple
2203 front ends to use that chardev ID for their input/output. Up to four different
2204 front ends can be connected to a single multiplexed chardev. (Without
2205 multiplexing enabled, a chardev can only be used by a single front end.)
2206 For instance you could use this to allow a single stdio chardev to be used by
2207 two serial ports and the QEMU monitor:
2209 @example
2210 -chardev stdio,mux=on,id=char0 \
2211 -mon chardev=char0,mode=readline,default \
2212 -serial chardev:char0 \
2213 -serial chardev:char0
2214 @end example
2216 You can have more than one multiplexer in a system configuration; for instance
2217 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2218 multiplexed between the QEMU monitor and a parallel port:
2220 @example
2221 -chardev stdio,mux=on,id=char0 \
2222 -mon chardev=char0,mode=readline,default \
2223 -parallel chardev:char0 \
2224 -chardev tcp,...,mux=on,id=char1 \
2225 -serial chardev:char1 \
2226 -serial chardev:char1
2227 @end example
2229 When you're using a multiplexed character device, some escape sequences are
2230 interpreted in the input. @xref{mux_keys, Keys in the character backend
2231 multiplexer}.
2233 Note that some other command line options may implicitly create multiplexed
2234 character backends; for instance @option{-serial mon:stdio} creates a
2235 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2236 and @option{-nographic} also multiplexes the console and the monitor to
2237 stdio.
2239 There is currently no support for multiplexing in the other direction
2240 (where a single QEMU front end takes input and output from multiple chardevs).
2242 Every backend supports the @option{logfile} option, which supplies the path
2243 to a file to record all data transmitted via the backend. The @option{logappend}
2244 option controls whether the log file will be truncated or appended to when
2245 opened.
2247 Further options to each backend are described below.
2249 @item -chardev null ,id=@var{id}
2250 A void device. This device will not emit any data, and will drop any data it
2251 receives. The null backend does not take any options.
2253 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
2255 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2256 unix socket will be created if @option{path} is specified. Behaviour is
2257 undefined if TCP options are specified for a unix socket.
2259 @option{server} specifies that the socket shall be a listening socket.
2261 @option{nowait} specifies that QEMU should not block waiting for a client to
2262 connect to a listening socket.
2264 @option{telnet} specifies that traffic on the socket should interpret telnet
2265 escape sequences.
2267 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2268 the remote end goes away. qemu will delay this many seconds and then attempt
2269 to reconnect. Zero disables reconnecting, and is the default.
2271 @option{tls-creds} requests enablement of the TLS protocol for encryption,
2272 and specifies the id of the TLS credentials to use for the handshake. The
2273 credentials must be previously created with the @option{-object tls-creds}
2274 argument.
2276 TCP and unix socket options are given below:
2278 @table @option
2280 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
2282 @option{host} for a listening socket specifies the local address to be bound.
2283 For a connecting socket species the remote host to connect to. @option{host} is
2284 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2286 @option{port} for a listening socket specifies the local port to be bound. For a
2287 connecting socket specifies the port on the remote host to connect to.
2288 @option{port} can be given as either a port number or a service name.
2289 @option{port} is required.
2291 @option{to} is only relevant to listening sockets. If it is specified, and
2292 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2293 to and including @option{to} until it succeeds. @option{to} must be specified
2294 as a port number.
2296 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2297 If neither is specified the socket may use either protocol.
2299 @option{nodelay} disables the Nagle algorithm.
2301 @item unix options: path=@var{path}
2303 @option{path} specifies the local path of the unix socket. @option{path} is
2304 required.
2306 @end table
2308 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2310 Sends all traffic from the guest to a remote host over UDP.
2312 @option{host} specifies the remote host to connect to. If not specified it
2313 defaults to @code{localhost}.
2315 @option{port} specifies the port on the remote host to connect to. @option{port}
2316 is required.
2318 @option{localaddr} specifies the local address to bind to. If not specified it
2319 defaults to @code{0.0.0.0}.
2321 @option{localport} specifies the local port to bind to. If not specified any
2322 available local port will be used.
2324 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2325 If neither is specified the device may use either protocol.
2327 @item -chardev msmouse ,id=@var{id}
2329 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2330 take any options.
2332 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2334 Connect to a QEMU text console. @option{vc} may optionally be given a specific
2335 size.
2337 @option{width} and @option{height} specify the width and height respectively of
2338 the console, in pixels.
2340 @option{cols} and @option{rows} specify that the console be sized to fit a text
2341 console with the given dimensions.
2343 @item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
2345 Create a ring buffer with fixed size @option{size}.
2346 @var{size} must be a power of two, and defaults to @code{64K}).
2348 @item -chardev file ,id=@var{id} ,path=@var{path}
2350 Log all traffic received from the guest to a file.
2352 @option{path} specifies the path of the file to be opened. This file will be
2353 created if it does not already exist, and overwritten if it does. @option{path}
2354 is required.
2356 @item -chardev pipe ,id=@var{id} ,path=@var{path}
2358 Create a two-way connection to the guest. The behaviour differs slightly between
2359 Windows hosts and other hosts:
2361 On Windows, a single duplex pipe will be created at
2362 @file{\\.pipe\@option{path}}.
2364 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2365 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2366 received by the guest. Data written by the guest can be read from
2367 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2368 be present.
2370 @option{path} forms part of the pipe path as described above. @option{path} is
2371 required.
2373 @item -chardev console ,id=@var{id}
2375 Send traffic from the guest to QEMU's standard output. @option{console} does not
2376 take any options.
2378 @option{console} is only available on Windows hosts.
2380 @item -chardev serial ,id=@var{id} ,path=@option{path}
2382 Send traffic from the guest to a serial device on the host.
2384 On Unix hosts serial will actually accept any tty device,
2385 not only serial lines.
2387 @option{path} specifies the name of the serial device to open.
2389 @item -chardev pty ,id=@var{id}
2391 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2392 not take any options.
2394 @option{pty} is not available on Windows hosts.
2396 @item -chardev stdio ,id=@var{id} [,signal=on|off]
2397 Connect to standard input and standard output of the QEMU process.
2399 @option{signal} controls if signals are enabled on the terminal, that includes
2400 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2401 default, use @option{signal=off} to disable it.
2403 @option{stdio} is not available on Windows hosts.
2405 @item -chardev braille ,id=@var{id}
2407 Connect to a local BrlAPI server. @option{braille} does not take any options.
2409 @item -chardev tty ,id=@var{id} ,path=@var{path}
2411 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2412 DragonFlyBSD hosts. It is an alias for @option{serial}.
2414 @option{path} specifies the path to the tty. @option{path} is required.
2416 @item -chardev parallel ,id=@var{id} ,path=@var{path}
2417 @itemx -chardev parport ,id=@var{id} ,path=@var{path}
2419 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2421 Connect to a local parallel port.
2423 @option{path} specifies the path to the parallel port device. @option{path} is
2424 required.
2426 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2428 @option{spicevmc} is only available when spice support is built in.
2430 @option{debug} debug level for spicevmc
2432 @option{name} name of spice channel to connect to
2434 Connect to a spice virtual machine channel, such as vdiport.
2436 @item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2438 @option{spiceport} is only available when spice support is built in.
2440 @option{debug} debug level for spicevmc
2442 @option{name} name of spice port to connect to
2444 Connect to a spice port, allowing a Spice client to handle the traffic
2445 identified by a name (preferably a fqdn).
2446 ETEXI
2448 STEXI
2449 @end table
2450 ETEXI
2451 DEFHEADING()
2453 DEFHEADING(Device URL Syntax:)
2454 STEXI
2456 In addition to using normal file images for the emulated storage devices,
2457 QEMU can also use networked resources such as iSCSI devices. These are
2458 specified using a special URL syntax.
2460 @table @option
2461 @item iSCSI
2462 iSCSI support allows QEMU to access iSCSI resources directly and use as
2463 images for the guest storage. Both disk and cdrom images are supported.
2465 Syntax for specifying iSCSI LUNs is
2466 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2468 By default qemu will use the iSCSI initiator-name
2469 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2470 line or a configuration file.
2472 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2473 stalled requests and force a reestablishment of the session. The timeout
2474 is specified in seconds. The default is 0 which means no timeout. Libiscsi
2475 1.15.0 or greater is required for this feature.
2477 Example (without authentication):
2478 @example
2479 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2480 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2481 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2482 @end example
2484 Example (CHAP username/password via URL):
2485 @example
2486 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
2487 @end example
2489 Example (CHAP username/password via environment variables):
2490 @example
2491 LIBISCSI_CHAP_USERNAME="user" \
2492 LIBISCSI_CHAP_PASSWORD="password" \
2493 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2494 @end example
2496 iSCSI support is an optional feature of QEMU and only available when
2497 compiled and linked against libiscsi.
2498 ETEXI
2499 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2500 "-iscsi [user=user][,password=password]\n"
2501 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
2502 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
2503 " [,timeout=timeout]\n"
2504 " iSCSI session parameters\n", QEMU_ARCH_ALL)
2505 STEXI
2507 iSCSI parameters such as username and password can also be specified via
2508 a configuration file. See qemu-doc for more information and examples.
2510 @item NBD
2511 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2512 as Unix Domain Sockets.
2514 Syntax for specifying a NBD device using TCP
2515 ``nbd:<server-ip>:<port>[:exportname=<export>]''
2517 Syntax for specifying a NBD device using Unix Domain Sockets
2518 ``nbd:unix:<domain-socket>[:exportname=<export>]''
2521 Example for TCP
2522 @example
2523 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
2524 @end example
2526 Example for Unix Domain Sockets
2527 @example
2528 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
2529 @end example
2531 @item SSH
2532 QEMU supports SSH (Secure Shell) access to remote disks.
2534 Examples:
2535 @example
2536 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2537 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2538 @end example
2540 Currently authentication must be done using ssh-agent. Other
2541 authentication methods may be supported in future.
2543 @item Sheepdog
2544 Sheepdog is a distributed storage system for QEMU.
2545 QEMU supports using either local sheepdog devices or remote networked
2546 devices.
2548 Syntax for specifying a sheepdog device
2549 @example
2550 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
2551 @end example
2553 Example
2554 @example
2555 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
2556 @end example
2558 See also @url{http://http://www.osrg.net/sheepdog/}.
2560 @item GlusterFS
2561 GlusterFS is an user space distributed file system.
2562 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2563 TCP, Unix Domain Sockets and RDMA transport protocols.
2565 Syntax for specifying a VM disk image on GlusterFS volume is
2566 @example
2567 gluster[+transport]://[server[:port]]/volname/image[?socket=...]
2568 @end example
2571 Example
2572 @example
2573 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
2574 @end example
2576 See also @url{http://www.gluster.org}.
2578 @item HTTP/HTTPS/FTP/FTPS/TFTP
2579 QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp.
2581 Syntax using a single filename:
2582 @example
2583 <protocol>://[<username>[:<password>]@@]<host>/<path>
2584 @end example
2586 where:
2587 @table @option
2588 @item protocol
2589 'http', 'https', 'ftp', 'ftps', or 'tftp'.
2591 @item username
2592 Optional username for authentication to the remote server.
2594 @item password
2595 Optional password for authentication to the remote server.
2597 @item host
2598 Address of the remote server.
2600 @item path
2601 Path on the remote server, including any query string.
2602 @end table
2604 The following options are also supported:
2605 @table @option
2606 @item url
2607 The full URL when passing options to the driver explicitly.
2609 @item readahead
2610 The amount of data to read ahead with each range request to the remote server.
2611 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2612 does not have a suffix, it will be assumed to be in bytes. The value must be a
2613 multiple of 512 bytes. It defaults to 256k.
2615 @item sslverify
2616 Whether to verify the remote server's certificate when connecting over SSL. It
2617 can have the value 'on' or 'off'. It defaults to 'on'.
2619 @item cookie
2620 Send this cookie (it can also be a list of cookies separated by ';') with
2621 each outgoing request. Only supported when using protocols such as HTTP
2622 which support cookies, otherwise ignored.
2624 @item timeout
2625 Set the timeout in seconds of the CURL connection. This timeout is the time
2626 that CURL waits for a response from the remote server to get the size of the
2627 image to be downloaded. If not set, the default timeout of 5 seconds is used.
2628 @end table
2630 Note that when passing options to qemu explicitly, @option{driver} is the value
2631 of <protocol>.
2633 Example: boot from a remote Fedora 20 live ISO image
2634 @example
2635 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
2637 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
2638 @end example
2640 Example: boot from a remote Fedora 20 cloud image using a local overlay for
2641 writes, copy-on-read, and a readahead of 64k
2642 @example
2643 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
2645 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
2646 @end example
2648 Example: boot from an image stored on a VMware vSphere server with a self-signed
2649 certificate using a local overlay for writes, a readahead of 64k and a timeout
2650 of 10 seconds.
2651 @example
2652 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
2654 qemu-system-x86_64 -drive file=/tmp/test.qcow2
2655 @end example
2656 ETEXI
2658 STEXI
2659 @end table
2660 ETEXI
2662 DEFHEADING(Bluetooth(R) options:)
2663 STEXI
2664 @table @option
2665 ETEXI
2667 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
2668 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2669 "-bt hci,host[:id]\n" \
2670 " use host's HCI with the given name\n" \
2671 "-bt hci[,vlan=n]\n" \
2672 " emulate a standard HCI in virtual scatternet 'n'\n" \
2673 "-bt vhci[,vlan=n]\n" \
2674 " add host computer to virtual scatternet 'n' using VHCI\n" \
2675 "-bt device:dev[,vlan=n]\n" \
2676 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2677 QEMU_ARCH_ALL)
2678 STEXI
2679 @item -bt hci[...]
2680 @findex -bt
2681 Defines the function of the corresponding Bluetooth HCI. -bt options
2682 are matched with the HCIs present in the chosen machine type. For
2683 example when emulating a machine with only one HCI built into it, only
2684 the first @code{-bt hci[...]} option is valid and defines the HCI's
2685 logic. The Transport Layer is decided by the machine type. Currently
2686 the machines @code{n800} and @code{n810} have one HCI and all other
2687 machines have none.
2689 @anchor{bt-hcis}
2690 The following three types are recognized:
2692 @table @option
2693 @item -bt hci,null
2694 (default) The corresponding Bluetooth HCI assumes no internal logic
2695 and will not respond to any HCI commands or emit events.
2697 @item -bt hci,host[:@var{id}]
2698 (@code{bluez} only) The corresponding HCI passes commands / events
2699 to / from the physical HCI identified by the name @var{id} (default:
2700 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2701 capable systems like Linux.
2703 @item -bt hci[,vlan=@var{n}]
2704 Add a virtual, standard HCI that will participate in the Bluetooth
2705 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2706 VLANs, devices inside a bluetooth network @var{n} can only communicate
2707 with other devices in the same network (scatternet).
2708 @end table
2710 @item -bt vhci[,vlan=@var{n}]
2711 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2712 to the host bluetooth stack instead of to the emulated target. This
2713 allows the host and target machines to participate in a common scatternet
2714 and communicate. Requires the Linux @code{vhci} driver installed. Can
2715 be used as following:
2717 @example
2718 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2719 @end example
2721 @item -bt device:@var{dev}[,vlan=@var{n}]
2722 Emulate a bluetooth device @var{dev} and place it in network @var{n}
2723 (default @code{0}). QEMU can only emulate one type of bluetooth devices
2724 currently:
2726 @table @option
2727 @item keyboard
2728 Virtual wireless keyboard implementing the HIDP bluetooth profile.
2729 @end table
2730 ETEXI
2732 STEXI
2733 @end table
2734 ETEXI
2735 DEFHEADING()
2737 #ifdef CONFIG_TPM
2738 DEFHEADING(TPM device options:)
2740 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
2741 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2742 " use path to provide path to a character device; default is /dev/tpm0\n"
2743 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
2744 " not provided it will be searched for in /sys/class/misc/tpm?/device\n",
2745 QEMU_ARCH_ALL)
2746 STEXI
2748 The general form of a TPM device option is:
2749 @table @option
2751 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2752 @findex -tpmdev
2753 Backend type must be:
2754 @option{passthrough}.
2756 The specific backend type will determine the applicable options.
2757 The @code{-tpmdev} option creates the TPM backend and requires a
2758 @code{-device} option that specifies the TPM frontend interface model.
2760 Options to each backend are described below.
2762 Use 'help' to print all available TPM backend types.
2763 @example
2764 qemu -tpmdev help
2765 @end example
2767 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
2769 (Linux-host only) Enable access to the host's TPM using the passthrough
2770 driver.
2772 @option{path} specifies the path to the host's TPM device, i.e., on
2773 a Linux host this would be @code{/dev/tpm0}.
2774 @option{path} is optional and by default @code{/dev/tpm0} is used.
2776 @option{cancel-path} specifies the path to the host TPM device's sysfs
2777 entry allowing for cancellation of an ongoing TPM command.
2778 @option{cancel-path} is optional and by default QEMU will search for the
2779 sysfs entry to use.
2781 Some notes about using the host's TPM with the passthrough driver:
2783 The TPM device accessed by the passthrough driver must not be
2784 used by any other application on the host.
2786 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2787 the VM's firmware (BIOS/UEFI) will not be able to initialize the
2788 TPM again and may therefore not show a TPM-specific menu that would
2789 otherwise allow the user to configure the TPM, e.g., allow the user to
2790 enable/disable or activate/deactivate the TPM.
2791 Further, if TPM ownership is released from within a VM then the host's TPM
2792 will get disabled and deactivated. To enable and activate the
2793 TPM again afterwards, the host has to be rebooted and the user is
2794 required to enter the firmware's menu to enable and activate the TPM.
2795 If the TPM is left disabled and/or deactivated most TPM commands will fail.
2797 To create a passthrough TPM use the following two options:
2798 @example
2799 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2800 @end example
2801 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2802 @code{tpmdev=tpm0} in the device option.
2804 @end table
2806 ETEXI
2808 DEFHEADING()
2810 #endif
2812 DEFHEADING(Linux/Multiboot boot specific:)
2813 STEXI
2815 When using these options, you can use a given Linux or Multiboot
2816 kernel without installing it in the disk image. It can be useful
2817 for easier testing of various kernels.
2819 @table @option
2820 ETEXI
2822 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
2823 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
2824 STEXI
2825 @item -kernel @var{bzImage}
2826 @findex -kernel
2827 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2828 or in multiboot format.
2829 ETEXI
2831 DEF("append", HAS_ARG, QEMU_OPTION_append, \
2832 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
2833 STEXI
2834 @item -append @var{cmdline}
2835 @findex -append
2836 Use @var{cmdline} as kernel command line
2837 ETEXI
2839 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
2840 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
2841 STEXI
2842 @item -initrd @var{file}
2843 @findex -initrd
2844 Use @var{file} as initial ram disk.
2846 @item -initrd "@var{file1} arg=foo,@var{file2}"
2848 This syntax is only available with multiboot.
2850 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2851 first module.
2852 ETEXI
2854 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
2855 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
2856 STEXI
2857 @item -dtb @var{file}
2858 @findex -dtb
2859 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2860 on boot.
2861 ETEXI
2863 STEXI
2864 @end table
2865 ETEXI
2866 DEFHEADING()
2868 DEFHEADING(Debug/Expert options:)
2869 STEXI
2870 @table @option
2871 ETEXI
2873 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
2874 "-fw_cfg [name=]<name>,file=<file>\n"
2875 " add named fw_cfg entry with contents from file\n"
2876 "-fw_cfg [name=]<name>,string=<str>\n"
2877 " add named fw_cfg entry with contents from string\n",
2878 QEMU_ARCH_ALL)
2879 STEXI
2881 @item -fw_cfg [name=]@var{name},file=@var{file}
2882 @findex -fw_cfg
2883 Add named fw_cfg entry with contents from file @var{file}.
2885 @item -fw_cfg [name=]@var{name},string=@var{str}
2886 Add named fw_cfg entry with contents from string @var{str}.
2888 The terminating NUL character of the contents of @var{str} will not be
2889 included as part of the fw_cfg item data. To insert contents with
2890 embedded NUL characters, you have to use the @var{file} parameter.
2892 The fw_cfg entries are passed by QEMU through to the guest.
2894 Example:
2895 @example
2896 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2897 @end example
2898 creates an fw_cfg entry named opt/com.mycompany/blob with contents
2899 from ./my_blob.bin.
2901 ETEXI
2903 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
2904 "-serial dev redirect the serial port to char device 'dev'\n",
2905 QEMU_ARCH_ALL)
2906 STEXI
2907 @item -serial @var{dev}
2908 @findex -serial
2909 Redirect the virtual serial port to host character device
2910 @var{dev}. The default device is @code{vc} in graphical mode and
2911 @code{stdio} in non graphical mode.
2913 This option can be used several times to simulate up to 4 serial
2914 ports.
2916 Use @code{-serial none} to disable all serial ports.
2918 Available character devices are:
2919 @table @option
2920 @item vc[:@var{W}x@var{H}]
2921 Virtual console. Optionally, a width and height can be given in pixel with
2922 @example
2923 vc:800x600
2924 @end example
2925 It is also possible to specify width or height in characters:
2926 @example
2927 vc:80Cx24C
2928 @end example
2929 @item pty
2930 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2931 @item none
2932 No device is allocated.
2933 @item null
2934 void device
2935 @item chardev:@var{id}
2936 Use a named character device defined with the @code{-chardev} option.
2937 @item /dev/XXX
2938 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2939 parameters are set according to the emulated ones.
2940 @item /dev/parport@var{N}
2941 [Linux only, parallel port only] Use host parallel port
2942 @var{N}. Currently SPP and EPP parallel port features can be used.
2943 @item file:@var{filename}
2944 Write output to @var{filename}. No character can be read.
2945 @item stdio
2946 [Unix only] standard input/output
2947 @item pipe:@var{filename}
2948 name pipe @var{filename}
2949 @item COM@var{n}
2950 [Windows only] Use host serial port @var{n}
2951 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2952 This implements UDP Net Console.
2953 When @var{remote_host} or @var{src_ip} are not specified
2954 they default to @code{0.0.0.0}.
2955 When not using a specified @var{src_port} a random port is automatically chosen.
2957 If you just want a simple readonly console you can use @code{netcat} or
2958 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
2959 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
2960 will appear in the netconsole session.
2962 If you plan to send characters back via netconsole or you want to stop
2963 and start QEMU a lot of times, you should have QEMU use the same
2964 source port each time by using something like @code{-serial
2965 udp::4555@@:4556} to QEMU. Another approach is to use a patched
2966 version of netcat which can listen to a TCP port and send and receive
2967 characters via udp. If you have a patched version of netcat which
2968 activates telnet remote echo and single char transfer, then you can
2969 use the following options to step up a netcat redirector to allow
2970 telnet on port 5555 to access the QEMU port.
2971 @table @code
2972 @item QEMU Options:
2973 -serial udp::4555@@:4556
2974 @item netcat options:
2975 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2976 @item telnet options:
2977 localhost 5555
2978 @end table
2980 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
2981 The TCP Net Console has two modes of operation. It can send the serial
2982 I/O to a location or wait for a connection from a location. By default
2983 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
2984 the @var{server} option QEMU will wait for a client socket application
2985 to connect to the port before continuing, unless the @code{nowait}
2986 option was specified. The @code{nodelay} option disables the Nagle buffering
2987 algorithm. The @code{reconnect} option only applies if @var{noserver} is
2988 set, if the connection goes down it will attempt to reconnect at the
2989 given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
2990 one TCP connection at a time is accepted. You can use @code{telnet} to
2991 connect to the corresponding character device.
2992 @table @code
2993 @item Example to send tcp console to 192.168.0.2 port 4444
2994 -serial tcp:192.168.0.2:4444
2995 @item Example to listen and wait on port 4444 for connection
2996 -serial tcp::4444,server
2997 @item Example to not wait and listen on ip 192.168.0.100 port 4444
2998 -serial tcp:192.168.0.100:4444,server,nowait
2999 @end table
3001 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3002 The telnet protocol is used instead of raw tcp sockets. The options
3003 work the same as if you had specified @code{-serial tcp}. The
3004 difference is that the port acts like a telnet server or client using
3005 telnet option negotiation. This will also allow you to send the
3006 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3007 sequence. Typically in unix telnet you do it with Control-] and then
3008 type "send break" followed by pressing the enter key.
3010 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3011 A unix domain socket is used instead of a tcp socket. The option works the
3012 same as if you had specified @code{-serial tcp} except the unix domain socket
3013 @var{path} is used for connections.
3015 @item mon:@var{dev_string}
3016 This is a special option to allow the monitor to be multiplexed onto
3017 another serial port. The monitor is accessed with key sequence of
3018 @key{Control-a} and then pressing @key{c}.
3019 @var{dev_string} should be any one of the serial devices specified
3020 above. An example to multiplex the monitor onto a telnet server
3021 listening on port 4444 would be:
3022 @table @code
3023 @item -serial mon:telnet::4444,server,nowait
3024 @end table
3025 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3026 QEMU any more but will be passed to the guest instead.
3028 @item braille
3029 Braille device. This will use BrlAPI to display the braille output on a real
3030 or fake device.
3032 @item msmouse
3033 Three button serial mouse. Configure the guest to use Microsoft protocol.
3034 @end table
3035 ETEXI
3037 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3038 "-parallel dev redirect the parallel port to char device 'dev'\n",
3039 QEMU_ARCH_ALL)
3040 STEXI
3041 @item -parallel @var{dev}
3042 @findex -parallel
3043 Redirect the virtual parallel port to host device @var{dev} (same
3044 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3045 be used to use hardware devices connected on the corresponding host
3046 parallel port.
3048 This option can be used several times to simulate up to 3 parallel
3049 ports.
3051 Use @code{-parallel none} to disable all parallel ports.
3052 ETEXI
3054 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3055 "-monitor dev redirect the monitor to char device 'dev'\n",
3056 QEMU_ARCH_ALL)
3057 STEXI
3058 @item -monitor @var{dev}
3059 @findex -monitor
3060 Redirect the monitor to host device @var{dev} (same devices as the
3061 serial port).
3062 The default device is @code{vc} in graphical mode and @code{stdio} in
3063 non graphical mode.
3064 Use @code{-monitor none} to disable the default monitor.
3065 ETEXI
3066 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3067 "-qmp dev like -monitor but opens in 'control' mode\n",
3068 QEMU_ARCH_ALL)
3069 STEXI
3070 @item -qmp @var{dev}
3071 @findex -qmp
3072 Like -monitor but opens in 'control' mode.
3073 ETEXI
3074 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3075 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3076 QEMU_ARCH_ALL)
3077 STEXI
3078 @item -qmp-pretty @var{dev}
3079 @findex -qmp-pretty
3080 Like -qmp but uses pretty JSON formatting.
3081 ETEXI
3083 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3084 "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
3085 STEXI
3086 @item -mon [chardev=]name[,mode=readline|control][,default]
3087 @findex -mon
3088 Setup monitor on chardev @var{name}.
3089 ETEXI
3091 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3092 "-debugcon dev redirect the debug console to char device 'dev'\n",
3093 QEMU_ARCH_ALL)
3094 STEXI
3095 @item -debugcon @var{dev}
3096 @findex -debugcon
3097 Redirect the debug console to host device @var{dev} (same devices as the
3098 serial port). The debug console is an I/O port which is typically port
3099 0xe9; writing to that I/O port sends output to this device.
3100 The default device is @code{vc} in graphical mode and @code{stdio} in
3101 non graphical mode.
3102 ETEXI
3104 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3105 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
3106 STEXI
3107 @item -pidfile @var{file}
3108 @findex -pidfile
3109 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3110 from a script.
3111 ETEXI
3113 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3114 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
3115 STEXI
3116 @item -singlestep
3117 @findex -singlestep
3118 Run the emulation in single step mode.
3119 ETEXI
3121 DEF("S", 0, QEMU_OPTION_S, \
3122 "-S freeze CPU at startup (use 'c' to start execution)\n",
3123 QEMU_ARCH_ALL)
3124 STEXI
3125 @item -S
3126 @findex -S
3127 Do not start CPU at startup (you must type 'c' in the monitor).
3128 ETEXI
3130 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3131 "-realtime [mlock=on|off]\n"
3132 " run qemu with realtime features\n"
3133 " mlock=on|off controls mlock support (default: on)\n",
3134 QEMU_ARCH_ALL)
3135 STEXI
3136 @item -realtime mlock=on|off
3137 @findex -realtime
3138 Run qemu with realtime features.
3139 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3140 (enabled by default).
3141 ETEXI
3143 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3144 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
3145 STEXI
3146 @item -gdb @var{dev}
3147 @findex -gdb
3148 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3149 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3150 stdio are reasonable use case. The latter is allowing to start QEMU from
3151 within gdb and establish the connection via a pipe:
3152 @example
3153 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3154 @end example
3155 ETEXI
3157 DEF("s", 0, QEMU_OPTION_s, \
3158 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3159 QEMU_ARCH_ALL)
3160 STEXI
3161 @item -s
3162 @findex -s
3163 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3164 (@pxref{gdb_usage}).
3165 ETEXI
3167 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3168 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
3169 QEMU_ARCH_ALL)
3170 STEXI
3171 @item -d @var{item1}[,...]
3172 @findex -d
3173 Enable logging of specified items. Use '-d help' for a list of log items.
3174 ETEXI
3176 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3177 "-D logfile output log to logfile (default stderr)\n",
3178 QEMU_ARCH_ALL)
3179 STEXI
3180 @item -D @var{logfile}
3181 @findex -D
3182 Output log in @var{logfile} instead of to stderr
3183 ETEXI
3185 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3186 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3187 QEMU_ARCH_ALL)
3188 STEXI
3189 @item -dfilter @var{range1}[,...]
3190 @findex -dfilter
3191 Filter debug output to that relevant to a range of target addresses. The filter
3192 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3193 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3194 addresses and sizes required. For example:
3195 @example
3196 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3197 @end example
3198 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3199 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3200 block starting at 0xffffffc00005f000.
3201 ETEXI
3203 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3204 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3205 QEMU_ARCH_ALL)
3206 STEXI
3207 @item -L @var{path}
3208 @findex -L
3209 Set the directory for the BIOS, VGA BIOS and keymaps.
3210 ETEXI
3212 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3213 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
3214 STEXI
3215 @item -bios @var{file}
3216 @findex -bios
3217 Set the filename for the BIOS.
3218 ETEXI
3220 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3221 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3222 STEXI
3223 @item -enable-kvm
3224 @findex -enable-kvm
3225 Enable KVM full virtualization support. This option is only available
3226 if KVM support is enabled when compiling.
3227 ETEXI
3229 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3230 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
3231 DEF("xen-create", 0, QEMU_OPTION_xen_create,
3232 "-xen-create create domain using xen hypercalls, bypassing xend\n"
3233 " warning: should not be used when xend is in use\n",
3234 QEMU_ARCH_ALL)
3235 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3236 "-xen-attach attach to existing xen domain\n"
3237 " xend will use this when starting QEMU\n",
3238 QEMU_ARCH_ALL)
3239 STEXI
3240 @item -xen-domid @var{id}
3241 @findex -xen-domid
3242 Specify xen guest domain @var{id} (XEN only).
3243 @item -xen-create
3244 @findex -xen-create
3245 Create domain using xen hypercalls, bypassing xend.
3246 Warning: should not be used when xend is in use (XEN only).
3247 @item -xen-attach
3248 @findex -xen-attach
3249 Attach to existing xen domain.
3250 xend will use this when starting QEMU (XEN only).
3251 ETEXI
3253 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3254 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
3255 STEXI
3256 @item -no-reboot
3257 @findex -no-reboot
3258 Exit instead of rebooting.
3259 ETEXI
3261 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3262 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
3263 STEXI
3264 @item -no-shutdown
3265 @findex -no-shutdown
3266 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3267 This allows for instance switching to monitor to commit changes to the
3268 disk image.
3269 ETEXI
3271 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3272 "-loadvm [tag|id]\n" \
3273 " start right away with a saved state (loadvm in monitor)\n",
3274 QEMU_ARCH_ALL)
3275 STEXI
3276 @item -loadvm @var{file}
3277 @findex -loadvm
3278 Start right away with a saved state (@code{loadvm} in monitor)
3279 ETEXI
3281 #ifndef _WIN32
3282 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3283 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3284 #endif
3285 STEXI
3286 @item -daemonize
3287 @findex -daemonize
3288 Daemonize the QEMU process after initialization. QEMU will not detach from
3289 standard IO until it is ready to receive connections on any of its devices.
3290 This option is a useful way for external programs to launch QEMU without having
3291 to cope with initialization race conditions.
3292 ETEXI
3294 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3295 "-option-rom rom load a file, rom, into the option ROM space\n",
3296 QEMU_ARCH_ALL)
3297 STEXI
3298 @item -option-rom @var{file}
3299 @findex -option-rom
3300 Load the contents of @var{file} as an option ROM.
3301 This option is useful to load things like EtherBoot.
3302 ETEXI
3304 HXCOMM Silently ignored for compatibility
3305 DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
3307 HXCOMM Options deprecated by -rtc
3308 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3309 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
3311 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3312 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3313 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3314 QEMU_ARCH_ALL)
3316 STEXI
3318 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3319 @findex -rtc
3320 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3321 UTC or local time, respectively. @code{localtime} is required for correct date in
3322 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3323 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3325 By default the RTC is driven by the host system time. This allows using of the
3326 RTC as accurate reference clock inside the guest, specifically if the host
3327 time is smoothly following an accurate external reference clock, e.g. via NTP.
3328 If you want to isolate the guest time from the host, you can set @option{clock}
3329 to @code{rt} instead. To even prevent it from progressing during suspension,
3330 you can set it to @code{vm}.
3332 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3333 specifically with Windows' ACPI HAL. This option will try to figure out how
3334 many timer interrupts were not processed by the Windows guest and will
3335 re-inject them.
3336 ETEXI
3338 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
3339 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>]\n" \
3340 " enable virtual instruction counter with 2^N clock ticks per\n" \
3341 " instruction, enable aligning the host and virtual clocks\n" \
3342 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
3343 STEXI
3344 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename}]
3345 @findex -icount
3346 Enable virtual instruction counter. The virtual cpu will execute one
3347 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
3348 then the virtual cpu speed will be automatically adjusted to keep virtual
3349 time within a few seconds of real time.
3351 When the virtual cpu is sleeping, the virtual time will advance at default
3352 speed unless @option{sleep=on|off} is specified.
3353 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3354 instantly whenever the virtual cpu goes to sleep mode and will not advance
3355 if no timer is enabled. This behavior give deterministic execution times from
3356 the guest point of view.
3358 Note that while this option can give deterministic behavior, it does not
3359 provide cycle accurate emulation. Modern CPUs contain superscalar out of
3360 order cores with complex cache hierarchies. The number of instructions
3361 executed often has little or no correlation with actual performance.
3363 @option{align=on} will activate the delay algorithm which will try
3364 to synchronise the host clock and the virtual clock. The goal is to
3365 have a guest running at the real frequency imposed by the shift option.
3366 Whenever the guest clock is behind the host clock and if
3367 @option{align=on} is specified then we print a message to the user
3368 to inform about the delay.
3369 Currently this option does not work when @option{shift} is @code{auto}.
3370 Note: The sync algorithm will work for those shift values for which
3371 the guest clock runs ahead of the host clock. Typically this happens
3372 when the shift value is high (how high depends on the host machine).
3374 When @option{rr} option is specified deterministic record/replay is enabled.
3375 Replay log is written into @var{filename} file in record mode and
3376 read from this file in replay mode.
3377 ETEXI
3379 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3380 "-watchdog model\n" \
3381 " enable virtual hardware watchdog [default=none]\n",
3382 QEMU_ARCH_ALL)
3383 STEXI
3384 @item -watchdog @var{model}
3385 @findex -watchdog
3386 Create a virtual hardware watchdog device. Once enabled (by a guest
3387 action), the watchdog must be periodically polled by an agent inside
3388 the guest or else the guest will be restarted. Choose a model for
3389 which your guest has drivers.
3391 The @var{model} is the model of hardware watchdog to emulate. Use
3392 @code{-watchdog help} to list available hardware models. Only one
3393 watchdog can be enabled for a guest.
3395 The following models may be available:
3396 @table @option
3397 @item ib700
3398 iBASE 700 is a very simple ISA watchdog with a single timer.
3399 @item i6300esb
3400 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3401 dual-timer watchdog.
3402 @item diag288
3403 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3404 (currently KVM only).
3405 @end table
3406 ETEXI
3408 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3409 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
3410 " action when watchdog fires [default=reset]\n",
3411 QEMU_ARCH_ALL)
3412 STEXI
3413 @item -watchdog-action @var{action}
3414 @findex -watchdog-action
3416 The @var{action} controls what QEMU will do when the watchdog timer
3417 expires.
3418 The default is
3419 @code{reset} (forcefully reset the guest).
3420 Other possible actions are:
3421 @code{shutdown} (attempt to gracefully shutdown the guest),
3422 @code{poweroff} (forcefully poweroff the guest),
3423 @code{pause} (pause the guest),
3424 @code{debug} (print a debug message and continue), or
3425 @code{none} (do nothing).
3427 Note that the @code{shutdown} action requires that the guest responds
3428 to ACPI signals, which it may not be able to do in the sort of
3429 situations where the watchdog would have expired, and thus
3430 @code{-watchdog-action shutdown} is not recommended for production use.
3432 Examples:
3434 @table @code
3435 @item -watchdog i6300esb -watchdog-action pause
3436 @itemx -watchdog ib700
3437 @end table
3438 ETEXI
3440 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
3441 "-echr chr set terminal escape character instead of ctrl-a\n",
3442 QEMU_ARCH_ALL)
3443 STEXI
3445 @item -echr @var{numeric_ascii_value}
3446 @findex -echr
3447 Change the escape character used for switching to the monitor when using
3448 monitor and serial sharing. The default is @code{0x01} when using the
3449 @code{-nographic} option. @code{0x01} is equal to pressing
3450 @code{Control-a}. You can select a different character from the ascii
3451 control keys where 1 through 26 map to Control-a through Control-z. For
3452 instance you could use the either of the following to change the escape
3453 character to Control-t.
3454 @table @code
3455 @item -echr 0x14
3456 @itemx -echr 20
3457 @end table
3458 ETEXI
3460 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3461 "-virtioconsole c\n" \
3462 " set virtio console\n", QEMU_ARCH_ALL)
3463 STEXI
3464 @item -virtioconsole @var{c}
3465 @findex -virtioconsole
3466 Set virtio console.
3468 This option is maintained for backward compatibility.
3470 Please use @code{-device virtconsole} for the new way of invocation.
3471 ETEXI
3473 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
3474 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
3475 STEXI
3476 @item -show-cursor
3477 @findex -show-cursor
3478 Show cursor.
3479 ETEXI
3481 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
3482 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
3483 STEXI
3484 @item -tb-size @var{n}
3485 @findex -tb-size
3486 Set TB size.
3487 ETEXI
3489 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
3490 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3491 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3492 "-incoming unix:socketpath\n" \
3493 " prepare for incoming migration, listen on\n" \
3494 " specified protocol and socket address\n" \
3495 "-incoming fd:fd\n" \
3496 "-incoming exec:cmdline\n" \
3497 " accept incoming migration on given file descriptor\n" \
3498 " or from given external command\n" \
3499 "-incoming defer\n" \
3500 " wait for the URI to be specified via migrate_incoming\n",
3501 QEMU_ARCH_ALL)
3502 STEXI
3503 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3504 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3505 @findex -incoming
3506 Prepare for incoming migration, listen on a given tcp port.
3508 @item -incoming unix:@var{socketpath}
3509 Prepare for incoming migration, listen on a given unix socket.
3511 @item -incoming fd:@var{fd}
3512 Accept incoming migration from a given filedescriptor.
3514 @item -incoming exec:@var{cmdline}
3515 Accept incoming migration as an output from specified external command.
3517 @item -incoming defer
3518 Wait for the URI to be specified via migrate_incoming. The monitor can
3519 be used to change settings (such as migration parameters) prior to issuing
3520 the migrate_incoming to allow the migration to begin.
3521 ETEXI
3523 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
3524 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
3525 STEXI
3526 @item -nodefaults
3527 @findex -nodefaults
3528 Don't create default devices. Normally, QEMU sets the default devices like serial
3529 port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3530 CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3531 default devices.
3532 ETEXI
3534 #ifndef _WIN32
3535 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
3536 "-chroot dir chroot to dir just before starting the VM\n",
3537 QEMU_ARCH_ALL)
3538 #endif
3539 STEXI
3540 @item -chroot @var{dir}
3541 @findex -chroot
3542 Immediately before starting guest execution, chroot to the specified
3543 directory. Especially useful in combination with -runas.
3544 ETEXI
3546 #ifndef _WIN32
3547 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
3548 "-runas user change to user id user just before starting the VM\n",
3549 QEMU_ARCH_ALL)
3550 #endif
3551 STEXI
3552 @item -runas @var{user}
3553 @findex -runas
3554 Immediately before starting guest execution, drop root privileges, switching
3555 to the specified user.
3556 ETEXI
3558 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3559 "-prom-env variable=value\n"
3560 " set OpenBIOS nvram variables\n",
3561 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
3562 STEXI
3563 @item -prom-env @var{variable}=@var{value}
3564 @findex -prom-env
3565 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3566 ETEXI
3567 DEF("semihosting", 0, QEMU_OPTION_semihosting,
3568 "-semihosting semihosting mode\n",
3569 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3570 QEMU_ARCH_MIPS)
3571 STEXI
3572 @item -semihosting
3573 @findex -semihosting
3574 Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
3575 ETEXI
3576 DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
3577 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3578 " semihosting configuration\n",
3579 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3580 QEMU_ARCH_MIPS)
3581 STEXI
3582 @item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
3583 @findex -semihosting-config
3584 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
3585 @table @option
3586 @item target=@code{native|gdb|auto}
3587 Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3588 or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3589 during debug sessions and @code{native} otherwise.
3590 @item arg=@var{str1},arg=@var{str2},...
3591 Allows the user to pass input arguments, and can be used multiple times to build
3592 up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3593 command line is still supported for backward compatibility. If both the
3594 @code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3595 specified, the former is passed to semihosting as it always takes precedence.
3596 @end table
3597 ETEXI
3598 DEF("old-param", 0, QEMU_OPTION_old_param,
3599 "-old-param old param mode\n", QEMU_ARCH_ARM)
3600 STEXI
3601 @item -old-param
3602 @findex -old-param (ARM)
3603 Old param mode (ARM only).
3604 ETEXI
3606 DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
3607 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
3608 QEMU_ARCH_ALL)
3609 STEXI
3610 @item -sandbox @var{arg}
3611 @findex -sandbox
3612 Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3613 disable it. The default is 'off'.
3614 ETEXI
3616 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
3617 "-readconfig <file>\n", QEMU_ARCH_ALL)
3618 STEXI
3619 @item -readconfig @var{file}
3620 @findex -readconfig
3621 Read device configuration from @var{file}. This approach is useful when you want to spawn
3622 QEMU process with many command line options but you don't want to exceed the command line
3623 character limit.
3624 ETEXI
3625 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3626 "-writeconfig <file>\n"
3627 " read/write config file\n", QEMU_ARCH_ALL)
3628 STEXI
3629 @item -writeconfig @var{file}
3630 @findex -writeconfig
3631 Write device configuration to @var{file}. The @var{file} can be either filename to save
3632 command line and device configuration into file or dash @code{-}) character to print the
3633 output to stdout. This can be later used as input file for @code{-readconfig} option.
3634 ETEXI
3635 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3636 "-nodefconfig\n"
3637 " do not load default config files at startup\n",
3638 QEMU_ARCH_ALL)
3639 STEXI
3640 @item -nodefconfig
3641 @findex -nodefconfig
3642 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3643 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3644 ETEXI
3645 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3646 "-no-user-config\n"
3647 " do not load user-provided config files at startup\n",
3648 QEMU_ARCH_ALL)
3649 STEXI
3650 @item -no-user-config
3651 @findex -no-user-config
3652 The @code{-no-user-config} option makes QEMU not load any of the user-provided
3653 config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
3654 files from @var{datadir}.
3655 ETEXI
3656 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
3657 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
3658 " specify tracing options\n",
3659 QEMU_ARCH_ALL)
3660 STEXI
3661 HXCOMM This line is not accurate, as some sub-options are backend-specific but
3662 HXCOMM HX does not support conditional compilation of text.
3663 @item -trace [events=@var{file}][,file=@var{file}]
3664 @findex -trace
3666 Specify tracing options.
3668 @table @option
3669 @item [enable=]@var{pattern}
3670 Immediately enable events matching @var{pattern}.
3671 The file must contain one event name (as listed in the @file{trace-events} file)
3672 per line; globbing patterns are accepted too. This option is only
3673 available if QEMU has been compiled with the @var{simple}, @var{stderr}
3674 or @var{ftrace} tracing backend. To specify multiple events or patterns,
3675 specify the @option{-trace} option multiple times.
3677 Use @code{-trace help} to print a list of names of trace points.
3679 @item events=@var{file}
3680 Immediately enable events listed in @var{file}.
3681 The file must contain one event name (as listed in the @file{trace-events} file)
3682 per line; globbing patterns are accepted too. This option is only
3683 available if QEMU has been compiled with the @var{simple}, @var{stderr} or
3684 @var{ftrace} tracing backend.
3686 @item file=@var{file}
3687 Log output traces to @var{file}.
3688 This option is only available if QEMU has been compiled with
3689 the @var{simple} tracing backend.
3690 @end table
3691 ETEXI
3693 HXCOMM Internal use
3694 DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3695 DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
3697 #ifdef __linux__
3698 DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3699 "-enable-fips enable FIPS 140-2 compliance\n",
3700 QEMU_ARCH_ALL)
3701 #endif
3702 STEXI
3703 @item -enable-fips
3704 @findex -enable-fips
3705 Enable FIPS 140-2 compliance mode.
3706 ETEXI
3708 HXCOMM Deprecated by -machine accel=tcg property
3709 DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
3711 HXCOMM Deprecated by kvm-pit driver properties
3712 DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
3713 "", QEMU_ARCH_I386)
3715 HXCOMM Deprecated (ignored)
3716 DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
3718 HXCOMM Deprecated by -machine kernel_irqchip=on|off property
3719 DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
3721 HXCOMM Deprecated (ignored)
3722 DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
3724 DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3725 "-msg timestamp[=on|off]\n"
3726 " change the format of messages\n"
3727 " on|off controls leading timestamps (default:on)\n",
3728 QEMU_ARCH_ALL)
3729 STEXI
3730 @item -msg timestamp[=on|off]
3731 @findex -msg
3732 prepend a timestamp to each log message.(default:on)
3733 ETEXI
3735 DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3736 "-dump-vmstate <file>\n"
3737 " Output vmstate information in JSON format to file.\n"
3738 " Use the scripts/vmstate-static-checker.py file to\n"
3739 " check for possible regressions in migration code\n"
3740 " by comparing two such vmstate dumps.\n",
3741 QEMU_ARCH_ALL)
3742 STEXI
3743 @item -dump-vmstate @var{file}
3744 @findex -dump-vmstate
3745 Dump json-encoded vmstate information for current machine type to file
3746 in @var{file}
3747 ETEXI
3749 DEFHEADING(Generic object creation)
3751 DEF("object", HAS_ARG, QEMU_OPTION_object,
3752 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3753 " create a new object of type TYPENAME setting properties\n"
3754 " in the order they are specified. Note that the 'id'\n"
3755 " property must be set. These objects are placed in the\n"
3756 " '/objects' path.\n",
3757 QEMU_ARCH_ALL)
3758 STEXI
3759 @item -object @var{typename}[,@var{prop1}=@var{value1},...]
3760 @findex -object
3761 Create a new object of type @var{typename} setting properties
3762 in the order they are specified. Note that the 'id'
3763 property must be set. These objects are placed in the
3764 '/objects' path.
3766 @table @option
3768 @item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off}
3770 Creates a memory file backend object, which can be used to back
3771 the guest RAM with huge pages. The @option{id} parameter is a
3772 unique ID that will be used to reference this memory region
3773 when configuring the @option{-numa} argument. The @option{size}
3774 option provides the size of the memory region, and accepts
3775 common suffixes, eg @option{500M}. The @option{mem-path} provides
3776 the path to either a shared memory or huge page filesystem mount.
3777 The @option{share} boolean option determines whether the memory
3778 region is marked as private to QEMU, or shared. The latter allows
3779 a co-operating external process to access the QEMU memory region.
3781 @item -object rng-random,id=@var{id},filename=@var{/dev/random}
3783 Creates a random number generator backend which obtains entropy from
3784 a device on the host. The @option{id} parameter is a unique ID that
3785 will be used to reference this entropy backend from the @option{virtio-rng}
3786 device. The @option{filename} parameter specifies which file to obtain
3787 entropy from and if omitted defaults to @option{/dev/random}.
3789 @item -object rng-egd,id=@var{id},chardev=@var{chardevid}
3791 Creates a random number generator backend which obtains entropy from
3792 an external daemon running on the host. The @option{id} parameter is
3793 a unique ID that will be used to reference this entropy backend from
3794 the @option{virtio-rng} device. The @option{chardev} parameter is
3795 the unique ID of a character device backend that provides the connection
3796 to the RNG daemon.
3798 @item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
3800 Creates a TLS anonymous credentials object, which can be used to provide
3801 TLS support on network backends. The @option{id} parameter is a unique
3802 ID which network backends will use to access the credentials. The
3803 @option{endpoint} is either @option{server} or @option{client} depending
3804 on whether the QEMU network backend that uses the credentials will be
3805 acting as a client or as a server. If @option{verify-peer} is enabled
3806 (the default) then once the handshake is completed, the peer credentials
3807 will be verified, though this is a no-op for anonymous credentials.
3809 The @var{dir} parameter tells QEMU where to find the credential
3810 files. For server endpoints, this directory may contain a file
3811 @var{dh-params.pem} providing diffie-hellman parameters to use
3812 for the TLS server. If the file is missing, QEMU will generate
3813 a set of DH parameters at startup. This is a computationally
3814 expensive operation that consumes random pool entropy, so it is
3815 recommended that a persistent set of parameters be generated
3816 upfront and saved.
3818 @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}
3820 Creates a TLS anonymous credentials object, which can be used to provide
3821 TLS support on network backends. The @option{id} parameter is a unique
3822 ID which network backends will use to access the credentials. The
3823 @option{endpoint} is either @option{server} or @option{client} depending
3824 on whether the QEMU network backend that uses the credentials will be
3825 acting as a client or as a server. If @option{verify-peer} is enabled
3826 (the default) then once the handshake is completed, the peer credentials
3827 will be verified. With x509 certificates, this implies that the clients
3828 must be provided with valid client certificates too.
3830 The @var{dir} parameter tells QEMU where to find the credential
3831 files. For server endpoints, this directory may contain a file
3832 @var{dh-params.pem} providing diffie-hellman parameters to use
3833 for the TLS server. If the file is missing, QEMU will generate
3834 a set of DH parameters at startup. This is a computationally
3835 expensive operation that consumes random pool entropy, so it is
3836 recommended that a persistent set of parameters be generated
3837 upfront and saved.
3839 For x509 certificate credentials the directory will contain further files
3840 providing the x509 certificates. The certificates must be stored
3841 in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
3842 @var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
3843 @var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
3845 For the @var{server-key.pem} and @var{client-key.pem} files which
3846 contain sensitive private keys, it is possible to use an encrypted
3847 version by providing the @var{passwordid} parameter. This provides
3848 the ID of a previously created @code{secret} object containing the
3849 password for decryption.
3851 @item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
3853 Interval @var{t} can't be 0, this filter batches the packet delivery: all
3854 packets arriving in a given interval on netdev @var{netdevid} are delayed
3855 until the end of the interval. Interval is in microseconds.
3856 @option{status} is optional that indicate whether the netfilter is
3857 on (enabled) or off (disabled), the default status for netfilter will be 'on'.
3859 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
3861 @option{all}: the filter is attached both to the receive and the transmit
3862 queue of the netdev (default).
3864 @option{rx}: the filter is attached to the receive queue of the netdev,
3865 where it will receive packets sent to the netdev.
3867 @option{tx}: the filter is attached to the transmit queue of the netdev,
3868 where it will receive packets sent by the netdev.
3870 @item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
3872 filter-mirror on netdev @var{netdevid},mirror net packet to chardev
3873 @var{chardevid}
3875 @item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},
3876 outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
3878 filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
3879 @var{chardevid},and redirect indev's packet to filter.
3880 Create a filter-redirector we need to differ outdev id from indev id, id can not
3881 be the same. we can just use indev or outdev, but at least one of indev or outdev
3882 need to be specified.
3884 @item -object filter-dump,id=@var{id},netdev=@var{dev},file=@var{filename}][,maxlen=@var{len}]
3886 Dump the network traffic on netdev @var{dev} to the file specified by
3887 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
3888 The file format is libpcap, so it can be analyzed with tools such as tcpdump
3889 or Wireshark.
3891 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
3892 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
3894 Defines a secret to store a password, encryption key, or some other sensitive
3895 data. The sensitive data can either be passed directly via the @var{data}
3896 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
3897 parameter is insecure unless the sensitive data is encrypted.
3899 The sensitive data can be provided in raw format (the default), or base64.
3900 When encoded as JSON, the raw format only supports valid UTF-8 characters,
3901 so base64 is recommended for sending binary data. QEMU will convert from
3902 which ever format is provided to the format it needs internally. eg, an
3903 RBD password can be provided in raw format, even though it will be base64
3904 encoded when passed onto the RBD sever.
3906 For added protection, it is possible to encrypt the data associated with
3907 a secret using the AES-256-CBC cipher. Use of encryption is indicated
3908 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
3909 parameter provides the ID of a previously defined secret that contains
3910 the AES-256 decryption key. This key should be 32-bytes long and be
3911 base64 encoded. The @var{iv} parameter provides the random initialization
3912 vector used for encryption of this particular secret and should be a
3913 base64 encrypted string of the 16-byte IV.
3915 The simplest (insecure) usage is to provide the secret inline
3917 @example
3919 # $QEMU -object secret,id=sec0,data=letmein,format=raw
3921 @end example
3923 The simplest secure usage is to provide the secret via a file
3925 # echo -n "letmein" > mypasswd.txt
3926 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
3928 For greater security, AES-256-CBC should be used. To illustrate usage,
3929 consider the openssl command line tool which can encrypt the data. Note
3930 that when encrypting, the plaintext must be padded to the cipher block
3931 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
3933 First a master key needs to be created in base64 encoding:
3935 @example
3936 # openssl rand -base64 32 > key.b64
3937 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
3938 @end example
3940 Each secret to be encrypted needs to have a random initialization vector
3941 generated. These do not need to be kept secret
3943 @example
3944 # openssl rand -base64 16 > iv.b64
3945 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
3946 @end example
3948 The secret to be defined can now be encrypted, in this case we're
3949 telling openssl to base64 encode the result, but it could be left
3950 as raw bytes if desired.
3952 @example
3953 # SECRET=$(echo -n "letmein" |
3954 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
3955 @end example
3957 When launching QEMU, create a master secret pointing to @code{key.b64}
3958 and specify that to be used to decrypt the user password. Pass the
3959 contents of @code{iv.b64} to the second secret
3961 @example
3962 # $QEMU \
3963 -object secret,id=secmaster0,format=base64,file=key.b64 \
3964 -object secret,id=sec0,keyid=secmaster0,format=base64,\
3965 data=$SECRET,iv=$(<iv.b64)
3966 @end example
3968 @end table
3970 ETEXI
3973 HXCOMM This is the last statement. Insert new options before this line!
3974 STEXI
3975 @end table
3976 ETEXI