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