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