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