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