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