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