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