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