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