Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20150401' 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)
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("net", HAS_ARG, QEMU_OPTION_net,
1453     "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1454     "                create a new Network Interface Card and connect it to VLAN 'n'\n"
1455 #ifdef CONFIG_SLIRP
1456     "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
1457     "         [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n"
1458     "         [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
1459 #ifndef _WIN32
1460                                              "[,smb=dir[,smbserver=addr]]\n"
1461 #endif
1462     "                connect the user mode network stack to VLAN 'n', configure its\n"
1463     "                DHCP server and enabled optional services\n"
1464 #endif
1465 #ifdef _WIN32
1466     "-net tap[,vlan=n][,name=str],ifname=name\n"
1467     "                connect the host TAP network interface to VLAN 'n'\n"
1468 #else
1469     "-net tap[,vlan=n][,name=str][,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
1470     "                connect the host TAP network interface to VLAN 'n'\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     "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
1490     "                connects a host TAP network interface to a host bridge device 'br'\n"
1491     "                (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
1492     "                (default=" DEFAULT_BRIDGE_HELPER ")\n"
1493 #endif
1494 #ifdef __linux__
1495     "-net l2tpv3[,vlan=n][,name=str],src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on/off][,udp=on/off][,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]\n"
1496     "                connect the VLAN to an Ethernet over L2TPv3 pseudowire\n"
1497     "                Linux kernel 3.3+ as well as most routers can talk\n"
1498     "                L2TPv3. This transport allows connecting a VM to a VM,\n"
1499     "                VM to a router and even VM to Host. It is a nearly-universal\n"
1500     "                standard (RFC3391). Note - this implementation uses static\n"
1501     "                pre-configured tunnels (same as the Linux kernel).\n"
1502     "                use 'src=' to specify source address\n"
1503     "                use 'dst=' to specify destination address\n"
1504     "                use 'udp=on' to specify udp encapsulation\n"
1505     "                use 'srcport=' to specify source udp port\n"
1506     "                use 'dstport=' to specify destination udp port\n"
1507     "                use 'ipv6=on' to force v6\n"
1508     "                L2TPv3 uses cookies to prevent misconfiguration as\n"
1509     "                well as a weak security measure\n"
1510     "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
1511     "                use 'txcookie=0x012345678' to specify a txcookie\n"
1512     "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1513     "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1514     "                use 'pincounter=on' to work around broken counter handling in peer\n"
1515     "                use 'offset=X' to add an extra offset between header and data\n"
1516 #endif
1517     "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
1518     "                connect the vlan 'n' to another VLAN using a socket connection\n"
1519     "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1520     "                connect the vlan 'n' to multicast maddr and port\n"
1521     "                use 'localaddr=addr' to specify the host address to send packets from\n"
1522     "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
1523     "                connect the vlan 'n' to another VLAN using an UDP tunnel\n"
1524 #ifdef CONFIG_VDE
1525     "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1526     "                connect the vlan 'n' to port 'n' of a vde switch running\n"
1527     "                on host and listening for incoming connections on 'socketpath'.\n"
1528     "                Use group 'groupname' and mode 'octalmode' to change default\n"
1529     "                ownership and permissions for communication port.\n"
1530 #endif
1531 #ifdef CONFIG_NETMAP
1532     "-net netmap,ifname=name[,devname=nmname]\n"
1533     "                attach to the existing netmap-enabled network interface 'name', or to a\n"
1534     "                VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1535     "                netmap device, defaults to '/dev/netmap')\n"
1536 #endif
1537     "-net dump[,vlan=n][,file=f][,len=n]\n"
1538     "                dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
1539     "-net none       use it alone to have zero network devices. If no -net option\n"
1540     "                is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL)
1541 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1542     "-netdev ["
1543 #ifdef CONFIG_SLIRP
1544     "user|"
1545 #endif
1546     "tap|"
1547     "bridge|"
1548 #ifdef CONFIG_VDE
1549     "vde|"
1550 #endif
1551 #ifdef CONFIG_NETMAP
1552     "netmap|"
1553 #endif
1554     "vhost-user|"
1555     "socket|"
1556     "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
1557 STEXI
1558 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1559 @findex -net
1560 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1561 = 0 is the default). The NIC is an e1000 by default on the PC
1562 target. Optionally, the MAC address can be changed to @var{mac}, the
1563 device address set to @var{addr} (PCI cards only),
1564 and a @var{name} can be assigned for use in monitor commands.
1565 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1566 that the card should have; this option currently only affects virtio cards; set
1567 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1568 NIC is created.  QEMU can emulate several different models of network card.
1569 Valid values for @var{type} are
1570 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1571 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1572 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1573 Not all devices are supported on all targets.  Use @code{-net nic,model=help}
1574 for a list of available devices for your target.
1575
1576 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
1577 @findex -netdev
1578 @item -net user[,@var{option}][,@var{option}][,...]
1579 Use the user mode network stack which requires no administrator
1580 privilege to run. Valid options are:
1581
1582 @table @option
1583 @item vlan=@var{n}
1584 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1585
1586 @item id=@var{id}
1587 @item name=@var{name}
1588 Assign symbolic name for use in monitor commands.
1589
1590 @item net=@var{addr}[/@var{mask}]
1591 Set IP network address the guest will see. Optionally specify the netmask,
1592 either in the form a.b.c.d or as number of valid top-most bits. Default is
1593 10.0.2.0/24.
1594
1595 @item host=@var{addr}
1596 Specify the guest-visible address of the host. Default is the 2nd IP in the
1597 guest network, i.e. x.x.x.2.
1598
1599 @item restrict=on|off
1600 If this option is enabled, the guest will be isolated, i.e. it will not be
1601 able to contact the host and no guest IP packets will be routed over the host
1602 to the outside. This option does not affect any explicitly set forwarding rules.
1603
1604 @item hostname=@var{name}
1605 Specifies the client hostname reported by the built-in DHCP server.
1606
1607 @item dhcpstart=@var{addr}
1608 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1609 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1610
1611 @item dns=@var{addr}
1612 Specify the guest-visible address of the virtual nameserver. The address must
1613 be different from the host address. Default is the 3rd IP in the guest network,
1614 i.e. x.x.x.3.
1615
1616 @item dnssearch=@var{domain}
1617 Provides an entry for the domain-search list sent by the built-in
1618 DHCP server. More than one domain suffix can be transmitted by specifying
1619 this option multiple times. If supported, this will cause the guest to
1620 automatically try to append the given domain suffix(es) in case a domain name
1621 can not be resolved.
1622
1623 Example:
1624 @example
1625 qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1626 @end example
1627
1628 @item tftp=@var{dir}
1629 When using the user mode network stack, activate a built-in TFTP
1630 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1631 The TFTP client on the guest must be configured in binary mode (use the command
1632 @code{bin} of the Unix TFTP client).
1633
1634 @item bootfile=@var{file}
1635 When using the user mode network stack, broadcast @var{file} as the BOOTP
1636 filename. In conjunction with @option{tftp}, this can be used to network boot
1637 a guest from a local directory.
1638
1639 Example (using pxelinux):
1640 @example
1641 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1642 @end example
1643
1644 @item smb=@var{dir}[,smbserver=@var{addr}]
1645 When using the user mode network stack, activate a built-in SMB
1646 server so that Windows OSes can access to the host files in @file{@var{dir}}
1647 transparently. The IP address of the SMB server can be set to @var{addr}. By
1648 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1649
1650 In the guest Windows OS, the line:
1651 @example
1652 10.0.2.4 smbserver
1653 @end example
1654 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1655 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1656
1657 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1658
1659 Note that a SAMBA server must be installed on the host OS.
1660 QEMU was tested successfully with smbd versions from Red Hat 9,
1661 Fedora Core 3 and OpenSUSE 11.x.
1662
1663 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1664 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1665 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1666 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1667 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1668 be bound to a specific host interface. If no connection type is set, TCP is
1669 used. This option can be given multiple times.
1670
1671 For example, to redirect host X11 connection from screen 1 to guest
1672 screen 0, use the following:
1673
1674 @example
1675 # on the host
1676 qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1677 # this host xterm should open in the guest X11 server
1678 xterm -display :1
1679 @end example
1680
1681 To redirect telnet connections from host port 5555 to telnet port on
1682 the guest, use the following:
1683
1684 @example
1685 # on the host
1686 qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
1687 telnet localhost 5555
1688 @end example
1689
1690 Then when you use on the host @code{telnet localhost 5555}, you
1691 connect to the guest telnet server.
1692
1693 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1694 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
1695 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1696 to the character device @var{dev} or to a program executed by @var{cmd:command}
1697 which gets spawned for each connection. This option can be given multiple times.
1698
1699 You can either use a chardev directly and have that one used throughout QEMU's
1700 lifetime, like in the following example:
1701
1702 @example
1703 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1704 # the guest accesses it
1705 qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
1706 @end example
1707
1708 Or you can execute a command on every TCP connection established by the guest,
1709 so that QEMU behaves similar to an inetd process for that virtual server:
1710
1711 @example
1712 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1713 # and connect the TCP stream to its stdin/stdout
1714 qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1715 @end example
1716
1717 @end table
1718
1719 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1720 processed and applied to -net user. Mixing them with the new configuration
1721 syntax gives undefined results. Their use for new applications is discouraged
1722 as they will be removed from future versions.
1723
1724 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1725 @item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1726 Connect the host TAP network interface @var{name} to VLAN @var{n}.
1727
1728 Use the network script @var{file} to configure it and the network script
1729 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1730 automatically provides one. The default network configure script is
1731 @file{/etc/qemu-ifup} and the default network deconfigure script is
1732 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1733 to disable script execution.
1734
1735 If running QEMU as an unprivileged user, use the network helper
1736 @var{helper} to configure the TAP interface. The default network
1737 helper executable is @file{/path/to/qemu-bridge-helper}.
1738
1739 @option{fd}=@var{h} can be used to specify the handle of an already
1740 opened host TAP interface.
1741
1742 Examples:
1743
1744 @example
1745 #launch a QEMU instance with the default network script
1746 qemu-system-i386 linux.img -net nic -net tap
1747 @end example
1748
1749 @example
1750 #launch a QEMU instance with two NICs, each one connected
1751 #to a TAP device
1752 qemu-system-i386 linux.img \
1753                  -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1754                  -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1755 @end example
1756
1757 @example
1758 #launch a QEMU instance with the default network helper to
1759 #connect a TAP device to bridge br0
1760 qemu-system-i386 linux.img \
1761                  -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
1762 @end example
1763
1764 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
1765 @item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1766 Connect a host TAP network interface to a host bridge device.
1767
1768 Use the network helper @var{helper} to configure the TAP interface and
1769 attach it to the bridge. The default network helper executable is
1770 @file{/path/to/qemu-bridge-helper} and the default bridge
1771 device is @file{br0}.
1772
1773 Examples:
1774
1775 @example
1776 #launch a QEMU instance with the default network helper to
1777 #connect a TAP device to bridge br0
1778 qemu-system-i386 linux.img -net bridge -net nic,model=virtio
1779 @end example
1780
1781 @example
1782 #launch a QEMU instance with the default network helper to
1783 #connect a TAP device to bridge qemubr0
1784 qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
1785 @end example
1786
1787 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1788 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1789
1790 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1791 machine using a TCP socket connection. If @option{listen} is
1792 specified, QEMU waits for incoming connections on @var{port}
1793 (@var{host} is optional). @option{connect} is used to connect to
1794 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1795 specifies an already opened TCP socket.
1796
1797 Example:
1798 @example
1799 # launch a first QEMU instance
1800 qemu-system-i386 linux.img \
1801                  -net nic,macaddr=52:54:00:12:34:56 \
1802                  -net socket,listen=:1234
1803 # connect the VLAN 0 of this instance to the VLAN 0
1804 # of the first instance
1805 qemu-system-i386 linux.img \
1806                  -net nic,macaddr=52:54:00:12:34:57 \
1807                  -net socket,connect=127.0.0.1:1234
1808 @end example
1809
1810 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1811 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1812
1813 Create a VLAN @var{n} shared with another QEMU virtual
1814 machines using a UDP multicast socket, effectively making a bus for
1815 every QEMU with same multicast address @var{maddr} and @var{port}.
1816 NOTES:
1817 @enumerate
1818 @item
1819 Several QEMU can be running on different hosts and share same bus (assuming
1820 correct multicast setup for these hosts).
1821 @item
1822 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1823 @url{http://user-mode-linux.sf.net}.
1824 @item
1825 Use @option{fd=h} to specify an already opened UDP multicast socket.
1826 @end enumerate
1827
1828 Example:
1829 @example
1830 # launch one QEMU instance
1831 qemu-system-i386 linux.img \
1832                  -net nic,macaddr=52:54:00:12:34:56 \
1833                  -net socket,mcast=230.0.0.1:1234
1834 # launch another QEMU instance on same "bus"
1835 qemu-system-i386 linux.img \
1836                  -net nic,macaddr=52:54:00:12:34:57 \
1837                  -net socket,mcast=230.0.0.1:1234
1838 # launch yet another QEMU instance on same "bus"
1839 qemu-system-i386 linux.img \
1840                  -net nic,macaddr=52:54:00:12:34:58 \
1841                  -net socket,mcast=230.0.0.1:1234
1842 @end example
1843
1844 Example (User Mode Linux compat.):
1845 @example
1846 # launch QEMU instance (note mcast address selected
1847 # is UML's default)
1848 qemu-system-i386 linux.img \
1849                  -net nic,macaddr=52:54:00:12:34:56 \
1850                  -net socket,mcast=239.192.168.1:1102
1851 # launch UML
1852 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1853 @end example
1854
1855 Example (send packets from host's 1.2.3.4):
1856 @example
1857 qemu-system-i386 linux.img \
1858                  -net nic,macaddr=52:54:00:12:34:56 \
1859                  -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1860 @end example
1861
1862 @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}]
1863 @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}]
1864 Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
1865 protocol to transport Ethernet (and other Layer 2) data frames between
1866 two systems. It is present in routers, firewalls and the Linux kernel
1867 (from version 3.3 onwards).
1868
1869 This transport allows a VM to communicate to another VM, router or firewall directly.
1870
1871 @item src=@var{srcaddr}
1872     source address (mandatory)
1873 @item dst=@var{dstaddr}
1874     destination address (mandatory)
1875 @item udp
1876     select udp encapsulation (default is ip).
1877 @item srcport=@var{srcport}
1878     source udp port.
1879 @item dstport=@var{dstport}
1880     destination udp port.
1881 @item ipv6
1882     force v6, otherwise defaults to v4.
1883 @item rxcookie=@var{rxcookie}
1884 @item txcookie=@var{txcookie}
1885     Cookies are a weak form of security in the l2tpv3 specification.
1886 Their function is mostly to prevent misconfiguration. By default they are 32
1887 bit.
1888 @item cookie64
1889     Set cookie size to 64 bit instead of the default 32
1890 @item counter=off
1891     Force a 'cut-down' L2TPv3 with no counter as in
1892 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
1893 @item pincounter=on
1894     Work around broken counter handling in peer. This may also help on
1895 networks which have packet reorder.
1896 @item offset=@var{offset}
1897     Add an extra offset between header and data
1898
1899 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
1900 on the remote Linux host 1.2.3.4:
1901 @example
1902 # Setup tunnel on linux host using raw ip as encapsulation
1903 # on 1.2.3.4
1904 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
1905     encap udp udp_sport 16384 udp_dport 16384
1906 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
1907     0xFFFFFFFF peer_session_id 0xFFFFFFFF
1908 ifconfig vmtunnel0 mtu 1500
1909 ifconfig vmtunnel0 up
1910 brctl addif br-lan vmtunnel0
1911
1912
1913 # on 4.3.2.1
1914 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
1915
1916 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
1917
1918
1919 @end example
1920
1921 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1922 @item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1923 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1924 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1925 and MODE @var{octalmode} to change default ownership and permissions for
1926 communication port. This option is only available if QEMU has been compiled
1927 with vde support enabled.
1928
1929 Example:
1930 @example
1931 # launch vde switch
1932 vde_switch -F -sock /tmp/myswitch
1933 # launch QEMU instance
1934 qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
1935 @end example
1936
1937 @item -netdev hubport,id=@var{id},hubid=@var{hubid}
1938
1939 Create a hub port on QEMU "vlan" @var{hubid}.
1940
1941 The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
1942 netdev.  @code{-net} and @code{-device} with parameter @option{vlan} create the
1943 required hub automatically.
1944
1945 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off]
1946
1947 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
1948 be a unix domain socket backed one. The vhost-user uses a specifically defined
1949 protocol to pass vhost ioctl replacement messages to an application on the other
1950 end of the socket. On non-MSIX guests, the feature can be forced with
1951 @var{vhostforce}.
1952
1953 Example:
1954 @example
1955 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
1956      -numa node,memdev=mem \
1957      -chardev socket,path=/path/to/socket \
1958      -netdev type=vhost-user,id=net0,chardev=chr0 \
1959      -device virtio-net-pci,netdev=net0
1960 @end example
1961
1962 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1963 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1964 At most @var{len} bytes (64k by default) per packet are stored. The file format is
1965 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1966
1967 @item -net none
1968 Indicate that no network devices should be configured. It is used to
1969 override the default configuration (@option{-net nic -net user}) which
1970 is activated if no @option{-net} options are provided.
1971 ETEXI
1972
1973 STEXI
1974 @end table
1975 ETEXI
1976 DEFHEADING()
1977
1978 DEFHEADING(Character device options:)
1979 STEXI
1980
1981 The general form of a character device option is:
1982 @table @option
1983 ETEXI
1984
1985 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1986     "-chardev null,id=id[,mux=on|off]\n"
1987     "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
1988     "         [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off] (tcp)\n"
1989     "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off] (unix)\n"
1990     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1991     "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1992     "-chardev msmouse,id=id[,mux=on|off]\n"
1993     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1994     "         [,mux=on|off]\n"
1995     "-chardev ringbuf,id=id[,size=size]\n"
1996     "-chardev file,id=id,path=path[,mux=on|off]\n"
1997     "-chardev pipe,id=id,path=path[,mux=on|off]\n"
1998 #ifdef _WIN32
1999     "-chardev console,id=id[,mux=on|off]\n"
2000     "-chardev serial,id=id,path=path[,mux=on|off]\n"
2001 #else
2002     "-chardev pty,id=id[,mux=on|off]\n"
2003     "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
2004 #endif
2005 #ifdef CONFIG_BRLAPI
2006     "-chardev braille,id=id[,mux=on|off]\n"
2007 #endif
2008 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2009         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2010     "-chardev serial,id=id,path=path[,mux=on|off]\n"
2011     "-chardev tty,id=id,path=path[,mux=on|off]\n"
2012 #endif
2013 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2014     "-chardev parallel,id=id,path=path[,mux=on|off]\n"
2015     "-chardev parport,id=id,path=path[,mux=on|off]\n"
2016 #endif
2017 #if defined(CONFIG_SPICE)
2018     "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
2019     "-chardev spiceport,id=id,name=name[,debug=debug]\n"
2020 #endif
2021     , QEMU_ARCH_ALL
2022 )
2023
2024 STEXI
2025 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
2026 @findex -chardev
2027 Backend is one of:
2028 @option{null},
2029 @option{socket},
2030 @option{udp},
2031 @option{msmouse},
2032 @option{vc},
2033 @option{ringbuf},
2034 @option{file},
2035 @option{pipe},
2036 @option{console},
2037 @option{serial},
2038 @option{pty},
2039 @option{stdio},
2040 @option{braille},
2041 @option{tty},
2042 @option{parallel},
2043 @option{parport},
2044 @option{spicevmc}.
2045 @option{spiceport}.
2046 The specific backend will determine the applicable options.
2047
2048 All devices must have an id, which can be any string up to 127 characters long.
2049 It is used to uniquely identify this device in other command line directives.
2050
2051 A character device may be used in multiplexing mode by multiple front-ends.
2052 The key sequence of @key{Control-a} and @key{c} will rotate the input focus
2053 between attached front-ends. Specify @option{mux=on} to enable this mode.
2054
2055 Options to each backend are described below.
2056
2057 @item -chardev null ,id=@var{id}
2058 A void device. This device will not emit any data, and will drop any data it
2059 receives. The null backend does not take any options.
2060
2061 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}]
2062
2063 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2064 unix socket will be created if @option{path} is specified. Behaviour is
2065 undefined if TCP options are specified for a unix socket.
2066
2067 @option{server} specifies that the socket shall be a listening socket.
2068
2069 @option{nowait} specifies that QEMU should not block waiting for a client to
2070 connect to a listening socket.
2071
2072 @option{telnet} specifies that traffic on the socket should interpret telnet
2073 escape sequences.
2074
2075 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2076 the remote end goes away.  qemu will delay this many seconds and then attempt
2077 to reconnect.  Zero disables reconnecting, and is the default.
2078
2079 TCP and unix socket options are given below:
2080
2081 @table @option
2082
2083 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
2084
2085 @option{host} for a listening socket specifies the local address to be bound.
2086 For a connecting socket species the remote host to connect to. @option{host} is
2087 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2088
2089 @option{port} for a listening socket specifies the local port to be bound. For a
2090 connecting socket specifies the port on the remote host to connect to.
2091 @option{port} can be given as either a port number or a service name.
2092 @option{port} is required.
2093
2094 @option{to} is only relevant to listening sockets. If it is specified, and
2095 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2096 to and including @option{to} until it succeeds. @option{to} must be specified
2097 as a port number.
2098
2099 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2100 If neither is specified the socket may use either protocol.
2101
2102 @option{nodelay} disables the Nagle algorithm.
2103
2104 @item unix options: path=@var{path}
2105
2106 @option{path} specifies the local path of the unix socket. @option{path} is
2107 required.
2108
2109 @end table
2110
2111 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2112
2113 Sends all traffic from the guest to a remote host over UDP.
2114
2115 @option{host} specifies the remote host to connect to. If not specified it
2116 defaults to @code{localhost}.
2117
2118 @option{port} specifies the port on the remote host to connect to. @option{port}
2119 is required.
2120
2121 @option{localaddr} specifies the local address to bind to. If not specified it
2122 defaults to @code{0.0.0.0}.
2123
2124 @option{localport} specifies the local port to bind to. If not specified any
2125 available local port will be used.
2126
2127 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2128 If neither is specified the device may use either protocol.
2129
2130 @item -chardev msmouse ,id=@var{id}
2131
2132 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2133 take any options.
2134
2135 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2136
2137 Connect to a QEMU text console. @option{vc} may optionally be given a specific
2138 size.
2139
2140 @option{width} and @option{height} specify the width and height respectively of
2141 the console, in pixels.
2142
2143 @option{cols} and @option{rows} specify that the console be sized to fit a text
2144 console with the given dimensions.
2145
2146 @item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
2147
2148 Create a ring buffer with fixed size @option{size}.
2149 @var{size} must be a power of two, and defaults to @code{64K}).
2150
2151 @item -chardev file ,id=@var{id} ,path=@var{path}
2152
2153 Log all traffic received from the guest to a file.
2154
2155 @option{path} specifies the path of the file to be opened. This file will be
2156 created if it does not already exist, and overwritten if it does. @option{path}
2157 is required.
2158
2159 @item -chardev pipe ,id=@var{id} ,path=@var{path}
2160
2161 Create a two-way connection to the guest. The behaviour differs slightly between
2162 Windows hosts and other hosts:
2163
2164 On Windows, a single duplex pipe will be created at
2165 @file{\\.pipe\@option{path}}.
2166
2167 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2168 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2169 received by the guest. Data written by the guest can be read from
2170 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2171 be present.
2172
2173 @option{path} forms part of the pipe path as described above. @option{path} is
2174 required.
2175
2176 @item -chardev console ,id=@var{id}
2177
2178 Send traffic from the guest to QEMU's standard output. @option{console} does not
2179 take any options.
2180
2181 @option{console} is only available on Windows hosts.
2182
2183 @item -chardev serial ,id=@var{id} ,path=@option{path}
2184
2185 Send traffic from the guest to a serial device on the host.
2186
2187 On Unix hosts serial will actually accept any tty device,
2188 not only serial lines.
2189
2190 @option{path} specifies the name of the serial device to open.
2191
2192 @item -chardev pty ,id=@var{id}
2193
2194 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2195 not take any options.
2196
2197 @option{pty} is not available on Windows hosts.
2198
2199 @item -chardev stdio ,id=@var{id} [,signal=on|off]
2200 Connect to standard input and standard output of the QEMU process.
2201
2202 @option{signal} controls if signals are enabled on the terminal, that includes
2203 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2204 default, use @option{signal=off} to disable it.
2205
2206 @option{stdio} is not available on Windows hosts.
2207
2208 @item -chardev braille ,id=@var{id}
2209
2210 Connect to a local BrlAPI server. @option{braille} does not take any options.
2211
2212 @item -chardev tty ,id=@var{id} ,path=@var{path}
2213
2214 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2215 DragonFlyBSD hosts.  It is an alias for @option{serial}.
2216
2217 @option{path} specifies the path to the tty. @option{path} is required.
2218
2219 @item -chardev parallel ,id=@var{id} ,path=@var{path}
2220 @item -chardev parport ,id=@var{id} ,path=@var{path}
2221
2222 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2223
2224 Connect to a local parallel port.
2225
2226 @option{path} specifies the path to the parallel port device. @option{path} is
2227 required.
2228
2229 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2230
2231 @option{spicevmc} is only available when spice support is built in.
2232
2233 @option{debug} debug level for spicevmc
2234
2235 @option{name} name of spice channel to connect to
2236
2237 Connect to a spice virtual machine channel, such as vdiport.
2238
2239 @item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2240
2241 @option{spiceport} is only available when spice support is built in.
2242
2243 @option{debug} debug level for spicevmc
2244
2245 @option{name} name of spice port to connect to
2246
2247 Connect to a spice port, allowing a Spice client to handle the traffic
2248 identified by a name (preferably a fqdn).
2249 ETEXI
2250
2251 STEXI
2252 @end table
2253 ETEXI
2254 DEFHEADING()
2255
2256 DEFHEADING(Device URL Syntax:)
2257 STEXI
2258
2259 In addition to using normal file images for the emulated storage devices,
2260 QEMU can also use networked resources such as iSCSI devices. These are
2261 specified using a special URL syntax.
2262
2263 @table @option
2264 @item iSCSI
2265 iSCSI support allows QEMU to access iSCSI resources directly and use as
2266 images for the guest storage. Both disk and cdrom images are supported.
2267
2268 Syntax for specifying iSCSI LUNs is
2269 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2270
2271 By default qemu will use the iSCSI initiator-name
2272 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2273 line or a configuration file.
2274
2275
2276 Example (without authentication):
2277 @example
2278 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2279                  -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2280                  -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2281 @end example
2282
2283 Example (CHAP username/password via URL):
2284 @example
2285 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
2286 @end example
2287
2288 Example (CHAP username/password via environment variables):
2289 @example
2290 LIBISCSI_CHAP_USERNAME="user" \
2291 LIBISCSI_CHAP_PASSWORD="password" \
2292 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2293 @end example
2294
2295 iSCSI support is an optional feature of QEMU and only available when
2296 compiled and linked against libiscsi.
2297 ETEXI
2298 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2299     "-iscsi [user=user][,password=password]\n"
2300     "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
2301     "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
2302     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
2303 STEXI
2304
2305 iSCSI parameters such as username and password can also be specified via
2306 a configuration file. See qemu-doc for more information and examples.
2307
2308 @item NBD
2309 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2310 as Unix Domain Sockets.
2311
2312 Syntax for specifying a NBD device using TCP
2313 ``nbd:<server-ip>:<port>[:exportname=<export>]''
2314
2315 Syntax for specifying a NBD device using Unix Domain Sockets
2316 ``nbd:unix:<domain-socket>[:exportname=<export>]''
2317
2318
2319 Example for TCP
2320 @example
2321 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
2322 @end example
2323
2324 Example for Unix Domain Sockets
2325 @example
2326 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
2327 @end example
2328
2329 @item SSH
2330 QEMU supports SSH (Secure Shell) access to remote disks.
2331
2332 Examples:
2333 @example
2334 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2335 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2336 @end example
2337
2338 Currently authentication must be done using ssh-agent.  Other
2339 authentication methods may be supported in future.
2340
2341 @item Sheepdog
2342 Sheepdog is a distributed storage system for QEMU.
2343 QEMU supports using either local sheepdog devices or remote networked
2344 devices.
2345
2346 Syntax for specifying a sheepdog device
2347 @example
2348 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
2349 @end example
2350
2351 Example
2352 @example
2353 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
2354 @end example
2355
2356 See also @url{http://http://www.osrg.net/sheepdog/}.
2357
2358 @item GlusterFS
2359 GlusterFS is an user space distributed file system.
2360 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2361 TCP, Unix Domain Sockets and RDMA transport protocols.
2362
2363 Syntax for specifying a VM disk image on GlusterFS volume is
2364 @example
2365 gluster[+transport]://[server[:port]]/volname/image[?socket=...]
2366 @end example
2367
2368
2369 Example
2370 @example
2371 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
2372 @end example
2373
2374 See also @url{http://www.gluster.org}.
2375
2376 @item HTTP/HTTPS/FTP/FTPS/TFTP
2377 QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp.
2378
2379 Syntax using a single filename:
2380 @example
2381 <protocol>://[<username>[:<password>]@@]<host>/<path>
2382 @end example
2383
2384 where:
2385 @table @option
2386 @item protocol
2387 'http', 'https', 'ftp', 'ftps', or 'tftp'.
2388
2389 @item username
2390 Optional username for authentication to the remote server.
2391
2392 @item password
2393 Optional password for authentication to the remote server.
2394
2395 @item host
2396 Address of the remote server.
2397
2398 @item path
2399 Path on the remote server, including any query string.
2400 @end table
2401
2402 The following options are also supported:
2403 @table @option
2404 @item url
2405 The full URL when passing options to the driver explicitly.
2406
2407 @item readahead
2408 The amount of data to read ahead with each range request to the remote server.
2409 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2410 does not have a suffix, it will be assumed to be in bytes. The value must be a
2411 multiple of 512 bytes. It defaults to 256k.
2412
2413 @item sslverify
2414 Whether to verify the remote server's certificate when connecting over SSL. It
2415 can have the value 'on' or 'off'. It defaults to 'on'.
2416
2417 @item cookie
2418 Send this cookie (it can also be a list of cookies separated by ';') with
2419 each outgoing request.  Only supported when using protocols such as HTTP
2420 which support cookies, otherwise ignored.
2421
2422 @item timeout
2423 Set the timeout in seconds of the CURL connection. This timeout is the time
2424 that CURL waits for a response from the remote server to get the size of the
2425 image to be downloaded. If not set, the default timeout of 5 seconds is used.
2426 @end table
2427
2428 Note that when passing options to qemu explicitly, @option{driver} is the value
2429 of <protocol>.
2430
2431 Example: boot from a remote Fedora 20 live ISO image
2432 @example
2433 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
2434
2435 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
2436 @end example
2437
2438 Example: boot from a remote Fedora 20 cloud image using a local overlay for
2439 writes, copy-on-read, and a readahead of 64k
2440 @example
2441 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
2442
2443 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
2444 @end example
2445
2446 Example: boot from an image stored on a VMware vSphere server with a self-signed
2447 certificate using a local overlay for writes, a readahead of 64k and a timeout
2448 of 10 seconds.
2449 @example
2450 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
2451
2452 qemu-system-x86_64 -drive file=/tmp/test.qcow2
2453 @end example
2454 ETEXI
2455
2456 STEXI
2457 @end table
2458 ETEXI
2459
2460 DEFHEADING(Bluetooth(R) options:)
2461 STEXI
2462 @table @option
2463 ETEXI
2464
2465 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
2466     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
2467     "-bt hci,host[:id]\n" \
2468     "                use host's HCI with the given name\n" \
2469     "-bt hci[,vlan=n]\n" \
2470     "                emulate a standard HCI in virtual scatternet 'n'\n" \
2471     "-bt vhci[,vlan=n]\n" \
2472     "                add host computer to virtual scatternet 'n' using VHCI\n" \
2473     "-bt device:dev[,vlan=n]\n" \
2474     "                emulate a bluetooth device 'dev' in scatternet 'n'\n",
2475     QEMU_ARCH_ALL)
2476 STEXI
2477 @item -bt hci[...]
2478 @findex -bt
2479 Defines the function of the corresponding Bluetooth HCI.  -bt options
2480 are matched with the HCIs present in the chosen machine type.  For
2481 example when emulating a machine with only one HCI built into it, only
2482 the first @code{-bt hci[...]} option is valid and defines the HCI's
2483 logic.  The Transport Layer is decided by the machine type.  Currently
2484 the machines @code{n800} and @code{n810} have one HCI and all other
2485 machines have none.
2486
2487 @anchor{bt-hcis}
2488 The following three types are recognized:
2489
2490 @table @option
2491 @item -bt hci,null
2492 (default) The corresponding Bluetooth HCI assumes no internal logic
2493 and will not respond to any HCI commands or emit events.
2494
2495 @item -bt hci,host[:@var{id}]
2496 (@code{bluez} only) The corresponding HCI passes commands / events
2497 to / from the physical HCI identified by the name @var{id} (default:
2498 @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
2499 capable systems like Linux.
2500
2501 @item -bt hci[,vlan=@var{n}]
2502 Add a virtual, standard HCI that will participate in the Bluetooth
2503 scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
2504 VLANs, devices inside a bluetooth network @var{n} can only communicate
2505 with other devices in the same network (scatternet).
2506 @end table
2507
2508 @item -bt vhci[,vlan=@var{n}]
2509 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2510 to the host bluetooth stack instead of to the emulated target.  This
2511 allows the host and target machines to participate in a common scatternet
2512 and communicate.  Requires the Linux @code{vhci} driver installed.  Can
2513 be used as following:
2514
2515 @example
2516 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2517 @end example
2518
2519 @item -bt device:@var{dev}[,vlan=@var{n}]
2520 Emulate a bluetooth device @var{dev} and place it in network @var{n}
2521 (default @code{0}).  QEMU can only emulate one type of bluetooth devices
2522 currently:
2523
2524 @table @option
2525 @item keyboard
2526 Virtual wireless keyboard implementing the HIDP bluetooth profile.
2527 @end table
2528 ETEXI
2529
2530 STEXI
2531 @end table
2532 ETEXI
2533 DEFHEADING()
2534
2535 #ifdef CONFIG_TPM
2536 DEFHEADING(TPM device options:)
2537
2538 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
2539     "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2540     "                use path to provide path to a character device; default is /dev/tpm0\n"
2541     "                use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
2542     "                not provided it will be searched for in /sys/class/misc/tpm?/device\n",
2543     QEMU_ARCH_ALL)
2544 STEXI
2545
2546 The general form of a TPM device option is:
2547 @table @option
2548
2549 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2550 @findex -tpmdev
2551 Backend type must be:
2552 @option{passthrough}.
2553
2554 The specific backend type will determine the applicable options.
2555 The @code{-tpmdev} option creates the TPM backend and requires a
2556 @code{-device} option that specifies the TPM frontend interface model.
2557
2558 Options to each backend are described below.
2559
2560 Use 'help' to print all available TPM backend types.
2561 @example
2562 qemu -tpmdev help
2563 @end example
2564
2565 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
2566
2567 (Linux-host only) Enable access to the host's TPM using the passthrough
2568 driver.
2569
2570 @option{path} specifies the path to the host's TPM device, i.e., on
2571 a Linux host this would be @code{/dev/tpm0}.
2572 @option{path} is optional and by default @code{/dev/tpm0} is used.
2573
2574 @option{cancel-path} specifies the path to the host TPM device's sysfs
2575 entry allowing for cancellation of an ongoing TPM command.
2576 @option{cancel-path} is optional and by default QEMU will search for the
2577 sysfs entry to use.
2578
2579 Some notes about using the host's TPM with the passthrough driver:
2580
2581 The TPM device accessed by the passthrough driver must not be
2582 used by any other application on the host.
2583
2584 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2585 the VM's firmware (BIOS/UEFI) will not be able to initialize the
2586 TPM again and may therefore not show a TPM-specific menu that would
2587 otherwise allow the user to configure the TPM, e.g., allow the user to
2588 enable/disable or activate/deactivate the TPM.
2589 Further, if TPM ownership is released from within a VM then the host's TPM
2590 will get disabled and deactivated. To enable and activate the
2591 TPM again afterwards, the host has to be rebooted and the user is
2592 required to enter the firmware's menu to enable and activate the TPM.
2593 If the TPM is left disabled and/or deactivated most TPM commands will fail.
2594
2595 To create a passthrough TPM use the following two options:
2596 @example
2597 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2598 @end example
2599 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2600 @code{tpmdev=tpm0} in the device option.
2601
2602 @end table
2603
2604 ETEXI
2605
2606 DEFHEADING()
2607
2608 #endif
2609
2610 DEFHEADING(Linux/Multiboot boot specific:)
2611 STEXI
2612
2613 When using these options, you can use a given Linux or Multiboot
2614 kernel without installing it in the disk image. It can be useful
2615 for easier testing of various kernels.
2616
2617 @table @option
2618 ETEXI
2619
2620 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
2621     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
2622 STEXI
2623 @item -kernel @var{bzImage}
2624 @findex -kernel
2625 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2626 or in multiboot format.
2627 ETEXI
2628
2629 DEF("append", HAS_ARG, QEMU_OPTION_append, \
2630     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
2631 STEXI
2632 @item -append @var{cmdline}
2633 @findex -append
2634 Use @var{cmdline} as kernel command line
2635 ETEXI
2636
2637 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
2638            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
2639 STEXI
2640 @item -initrd @var{file}
2641 @findex -initrd
2642 Use @var{file} as initial ram disk.
2643
2644 @item -initrd "@var{file1} arg=foo,@var{file2}"
2645
2646 This syntax is only available with multiboot.
2647
2648 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2649 first module.
2650 ETEXI
2651
2652 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
2653     "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
2654 STEXI
2655 @item -dtb @var{file}
2656 @findex -dtb
2657 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2658 on boot.
2659 ETEXI
2660
2661 STEXI
2662 @end table
2663 ETEXI
2664 DEFHEADING()
2665
2666 DEFHEADING(Debug/Expert options:)
2667 STEXI
2668 @table @option
2669 ETEXI
2670
2671 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
2672     "-serial dev     redirect the serial port to char device 'dev'\n",
2673     QEMU_ARCH_ALL)
2674 STEXI
2675 @item -serial @var{dev}
2676 @findex -serial
2677 Redirect the virtual serial port to host character device
2678 @var{dev}. The default device is @code{vc} in graphical mode and
2679 @code{stdio} in non graphical mode.
2680
2681 This option can be used several times to simulate up to 4 serial
2682 ports.
2683
2684 Use @code{-serial none} to disable all serial ports.
2685
2686 Available character devices are:
2687 @table @option
2688 @item vc[:@var{W}x@var{H}]
2689 Virtual console. Optionally, a width and height can be given in pixel with
2690 @example
2691 vc:800x600
2692 @end example
2693 It is also possible to specify width or height in characters:
2694 @example
2695 vc:80Cx24C
2696 @end example
2697 @item pty
2698 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2699 @item none
2700 No device is allocated.
2701 @item null
2702 void device
2703 @item chardev:@var{id}
2704 Use a named character device defined with the @code{-chardev} option.
2705 @item /dev/XXX
2706 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2707 parameters are set according to the emulated ones.
2708 @item /dev/parport@var{N}
2709 [Linux only, parallel port only] Use host parallel port
2710 @var{N}. Currently SPP and EPP parallel port features can be used.
2711 @item file:@var{filename}
2712 Write output to @var{filename}. No character can be read.
2713 @item stdio
2714 [Unix only] standard input/output
2715 @item pipe:@var{filename}
2716 name pipe @var{filename}
2717 @item COM@var{n}
2718 [Windows only] Use host serial port @var{n}
2719 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2720 This implements UDP Net Console.
2721 When @var{remote_host} or @var{src_ip} are not specified
2722 they default to @code{0.0.0.0}.
2723 When not using a specified @var{src_port} a random port is automatically chosen.
2724
2725 If you just want a simple readonly console you can use @code{netcat} or
2726 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
2727 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
2728 will appear in the netconsole session.
2729
2730 If you plan to send characters back via netconsole or you want to stop
2731 and start QEMU a lot of times, you should have QEMU use the same
2732 source port each time by using something like @code{-serial
2733 udp::4555@@:4556} to QEMU. Another approach is to use a patched
2734 version of netcat which can listen to a TCP port and send and receive
2735 characters via udp.  If you have a patched version of netcat which
2736 activates telnet remote echo and single char transfer, then you can
2737 use the following options to step up a netcat redirector to allow
2738 telnet on port 5555 to access the QEMU port.
2739 @table @code
2740 @item QEMU Options:
2741 -serial udp::4555@@:4556
2742 @item netcat options:
2743 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2744 @item telnet options:
2745 localhost 5555
2746 @end table
2747
2748 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
2749 The TCP Net Console has two modes of operation.  It can send the serial
2750 I/O to a location or wait for a connection from a location.  By default
2751 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
2752 the @var{server} option QEMU will wait for a client socket application
2753 to connect to the port before continuing, unless the @code{nowait}
2754 option was specified.  The @code{nodelay} option disables the Nagle buffering
2755 algorithm.  The @code{reconnect} option only applies if @var{noserver} is
2756 set, if the connection goes down it will attempt to reconnect at the
2757 given interval.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
2758 one TCP connection at a time is accepted. You can use @code{telnet} to
2759 connect to the corresponding character device.
2760 @table @code
2761 @item Example to send tcp console to 192.168.0.2 port 4444
2762 -serial tcp:192.168.0.2:4444
2763 @item Example to listen and wait on port 4444 for connection
2764 -serial tcp::4444,server
2765 @item Example to not wait and listen on ip 192.168.0.100 port 4444
2766 -serial tcp:192.168.0.100:4444,server,nowait
2767 @end table
2768
2769 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
2770 The telnet protocol is used instead of raw tcp sockets.  The options
2771 work the same as if you had specified @code{-serial tcp}.  The
2772 difference is that the port acts like a telnet server or client using
2773 telnet option negotiation.  This will also allow you to send the
2774 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
2775 sequence.  Typically in unix telnet you do it with Control-] and then
2776 type "send break" followed by pressing the enter key.
2777
2778 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
2779 A unix domain socket is used instead of a tcp socket.  The option works the
2780 same as if you had specified @code{-serial tcp} except the unix domain socket
2781 @var{path} is used for connections.
2782
2783 @item mon:@var{dev_string}
2784 This is a special option to allow the monitor to be multiplexed onto
2785 another serial port.  The monitor is accessed with key sequence of
2786 @key{Control-a} and then pressing @key{c}.
2787 @var{dev_string} should be any one of the serial devices specified
2788 above.  An example to multiplex the monitor onto a telnet server
2789 listening on port 4444 would be:
2790 @table @code
2791 @item -serial mon:telnet::4444,server,nowait
2792 @end table
2793 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
2794 QEMU any more but will be passed to the guest instead.
2795
2796 @item braille
2797 Braille device.  This will use BrlAPI to display the braille output on a real
2798 or fake device.
2799
2800 @item msmouse
2801 Three button serial mouse. Configure the guest to use Microsoft protocol.
2802 @end table
2803 ETEXI
2804
2805 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
2806     "-parallel dev   redirect the parallel port to char device 'dev'\n",
2807     QEMU_ARCH_ALL)
2808 STEXI
2809 @item -parallel @var{dev}
2810 @findex -parallel
2811 Redirect the virtual parallel port to host device @var{dev} (same
2812 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
2813 be used to use hardware devices connected on the corresponding host
2814 parallel port.
2815
2816 This option can be used several times to simulate up to 3 parallel
2817 ports.
2818
2819 Use @code{-parallel none} to disable all parallel ports.
2820 ETEXI
2821
2822 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
2823     "-monitor dev    redirect the monitor to char device 'dev'\n",
2824     QEMU_ARCH_ALL)
2825 STEXI
2826 @item -monitor @var{dev}
2827 @findex -monitor
2828 Redirect the monitor to host device @var{dev} (same devices as the
2829 serial port).
2830 The default device is @code{vc} in graphical mode and @code{stdio} in
2831 non graphical mode.
2832 Use @code{-monitor none} to disable the default monitor.
2833 ETEXI
2834 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
2835     "-qmp dev        like -monitor but opens in 'control' mode\n",
2836     QEMU_ARCH_ALL)
2837 STEXI
2838 @item -qmp @var{dev}
2839 @findex -qmp
2840 Like -monitor but opens in 'control' mode.
2841 ETEXI
2842 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
2843     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
2844     QEMU_ARCH_ALL)
2845 STEXI
2846 @item -qmp-pretty @var{dev}
2847 @findex -qmp-pretty
2848 Like -qmp but uses pretty JSON formatting.
2849 ETEXI
2850
2851 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
2852     "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
2853 STEXI
2854 @item -mon [chardev=]name[,mode=readline|control][,default]
2855 @findex -mon
2856 Setup monitor on chardev @var{name}.
2857 ETEXI
2858
2859 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
2860     "-debugcon dev   redirect the debug console to char device 'dev'\n",
2861     QEMU_ARCH_ALL)
2862 STEXI
2863 @item -debugcon @var{dev}
2864 @findex -debugcon
2865 Redirect the debug console to host device @var{dev} (same devices as the
2866 serial port).  The debug console is an I/O port which is typically port
2867 0xe9; writing to that I/O port sends output to this device.
2868 The default device is @code{vc} in graphical mode and @code{stdio} in
2869 non graphical mode.
2870 ETEXI
2871
2872 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
2873     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
2874 STEXI
2875 @item -pidfile @var{file}
2876 @findex -pidfile
2877 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
2878 from a script.
2879 ETEXI
2880
2881 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
2882     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
2883 STEXI
2884 @item -singlestep
2885 @findex -singlestep
2886 Run the emulation in single step mode.
2887 ETEXI
2888
2889 DEF("S", 0, QEMU_OPTION_S, \
2890     "-S              freeze CPU at startup (use 'c' to start execution)\n",
2891     QEMU_ARCH_ALL)
2892 STEXI
2893 @item -S
2894 @findex -S
2895 Do not start CPU at startup (you must type 'c' in the monitor).
2896 ETEXI
2897
2898 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
2899     "-realtime [mlock=on|off]\n"
2900     "                run qemu with realtime features\n"
2901     "                mlock=on|off controls mlock support (default: on)\n",
2902     QEMU_ARCH_ALL)
2903 STEXI
2904 @item -realtime mlock=on|off
2905 @findex -realtime
2906 Run qemu with realtime features.
2907 mlocking qemu and guest memory can be enabled via @option{mlock=on}
2908 (enabled by default).
2909 ETEXI
2910
2911 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
2912     "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
2913 STEXI
2914 @item -gdb @var{dev}
2915 @findex -gdb
2916 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
2917 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
2918 stdio are reasonable use case. The latter is allowing to start QEMU from
2919 within gdb and establish the connection via a pipe:
2920 @example
2921 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
2922 @end example
2923 ETEXI
2924
2925 DEF("s", 0, QEMU_OPTION_s, \
2926     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
2927     QEMU_ARCH_ALL)
2928 STEXI
2929 @item -s
2930 @findex -s
2931 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
2932 (@pxref{gdb_usage}).
2933 ETEXI
2934
2935 DEF("d", HAS_ARG, QEMU_OPTION_d, \
2936     "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
2937     QEMU_ARCH_ALL)
2938 STEXI
2939 @item -d @var{item1}[,...]
2940 @findex -d
2941 Enable logging of specified items. Use '-d help' for a list of log items.
2942 ETEXI
2943
2944 DEF("D", HAS_ARG, QEMU_OPTION_D, \
2945     "-D logfile      output log to logfile (default stderr)\n",
2946     QEMU_ARCH_ALL)
2947 STEXI
2948 @item -D @var{logfile}
2949 @findex -D
2950 Output log in @var{logfile} instead of to stderr
2951 ETEXI
2952
2953 DEF("L", HAS_ARG, QEMU_OPTION_L, \
2954     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
2955     QEMU_ARCH_ALL)
2956 STEXI
2957 @item -L  @var{path}
2958 @findex -L
2959 Set the directory for the BIOS, VGA BIOS and keymaps.
2960 ETEXI
2961
2962 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
2963     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
2964 STEXI
2965 @item -bios @var{file}
2966 @findex -bios
2967 Set the filename for the BIOS.
2968 ETEXI
2969
2970 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
2971     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
2972 STEXI
2973 @item -enable-kvm
2974 @findex -enable-kvm
2975 Enable KVM full virtualization support. This option is only available
2976 if KVM support is enabled when compiling.
2977 ETEXI
2978
2979 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
2980     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
2981 DEF("xen-create", 0, QEMU_OPTION_xen_create,
2982     "-xen-create     create domain using xen hypercalls, bypassing xend\n"
2983     "                warning: should not be used when xend is in use\n",
2984     QEMU_ARCH_ALL)
2985 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2986     "-xen-attach     attach to existing xen domain\n"
2987     "                xend will use this when starting QEMU\n",
2988     QEMU_ARCH_ALL)
2989 STEXI
2990 @item -xen-domid @var{id}
2991 @findex -xen-domid
2992 Specify xen guest domain @var{id} (XEN only).
2993 @item -xen-create
2994 @findex -xen-create
2995 Create domain using xen hypercalls, bypassing xend.
2996 Warning: should not be used when xend is in use (XEN only).
2997 @item -xen-attach
2998 @findex -xen-attach
2999 Attach to existing xen domain.
3000 xend will use this when starting QEMU (XEN only).
3001 ETEXI
3002
3003 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3004     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
3005 STEXI
3006 @item -no-reboot
3007 @findex -no-reboot
3008 Exit instead of rebooting.
3009 ETEXI
3010
3011 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3012     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
3013 STEXI
3014 @item -no-shutdown
3015 @findex -no-shutdown
3016 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3017 This allows for instance switching to monitor to commit changes to the
3018 disk image.
3019 ETEXI
3020
3021 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3022     "-loadvm [tag|id]\n" \
3023     "                start right away with a saved state (loadvm in monitor)\n",
3024     QEMU_ARCH_ALL)
3025 STEXI
3026 @item -loadvm @var{file}
3027 @findex -loadvm
3028 Start right away with a saved state (@code{loadvm} in monitor)
3029 ETEXI
3030
3031 #ifndef _WIN32
3032 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3033     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3034 #endif
3035 STEXI
3036 @item -daemonize
3037 @findex -daemonize
3038 Daemonize the QEMU process after initialization.  QEMU will not detach from
3039 standard IO until it is ready to receive connections on any of its devices.
3040 This option is a useful way for external programs to launch QEMU without having
3041 to cope with initialization race conditions.
3042 ETEXI
3043
3044 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3045     "-option-rom rom load a file, rom, into the option ROM space\n",
3046     QEMU_ARCH_ALL)
3047 STEXI
3048 @item -option-rom @var{file}
3049 @findex -option-rom
3050 Load the contents of @var{file} as an option ROM.
3051 This option is useful to load things like EtherBoot.
3052 ETEXI
3053
3054 HXCOMM Silently ignored for compatibility
3055 DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
3056
3057 HXCOMM Options deprecated by -rtc
3058 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3059 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
3060
3061 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3062     "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3063     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3064     QEMU_ARCH_ALL)
3065
3066 STEXI
3067
3068 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3069 @findex -rtc
3070 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3071 UTC or local time, respectively. @code{localtime} is required for correct date in
3072 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3073 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3074
3075 By default the RTC is driven by the host system time. This allows using of the
3076 RTC as accurate reference clock inside the guest, specifically if the host
3077 time is smoothly following an accurate external reference clock, e.g. via NTP.
3078 If you want to isolate the guest time from the host, you can set @option{clock}
3079 to @code{rt} instead.  To even prevent it from progressing during suspension,
3080 you can set it to @code{vm}.
3081
3082 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3083 specifically with Windows' ACPI HAL. This option will try to figure out how
3084 many timer interrupts were not processed by the Windows guest and will
3085 re-inject them.
3086 ETEXI
3087
3088 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
3089     "-icount [shift=N|auto][,align=on|off]\n" \
3090     "                enable virtual instruction counter with 2^N clock ticks per\n" \
3091     "                instruction and enable aligning the host and virtual clocks\n", QEMU_ARCH_ALL)
3092 STEXI
3093 @item -icount [shift=@var{N}|auto]
3094 @findex -icount
3095 Enable virtual instruction counter.  The virtual cpu will execute one
3096 instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
3097 then the virtual cpu speed will be automatically adjusted to keep virtual
3098 time within a few seconds of real time.
3099
3100 Note that while this option can give deterministic behavior, it does not
3101 provide cycle accurate emulation.  Modern CPUs contain superscalar out of
3102 order cores with complex cache hierarchies.  The number of instructions
3103 executed often has little or no correlation with actual performance.
3104
3105 @option{align=on} will activate the delay algorithm which will try to
3106 to synchronise the host clock and the virtual clock. The goal is to
3107 have a guest running at the real frequency imposed by the shift option.
3108 Whenever the guest clock is behind the host clock and if
3109 @option{align=on} is specified then we print a messsage to the user
3110 to inform about the delay.
3111 Currently this option does not work when @option{shift} is @code{auto}.
3112 Note: The sync algorithm will work for those shift values for which
3113 the guest clock runs ahead of the host clock. Typically this happens
3114 when the shift value is high (how high depends on the host machine).
3115 ETEXI
3116
3117 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3118     "-watchdog i6300esb|ib700\n" \
3119     "                enable virtual hardware watchdog [default=none]\n",
3120     QEMU_ARCH_ALL)
3121 STEXI
3122 @item -watchdog @var{model}
3123 @findex -watchdog
3124 Create a virtual hardware watchdog device.  Once enabled (by a guest
3125 action), the watchdog must be periodically polled by an agent inside
3126 the guest or else the guest will be restarted.
3127
3128 The @var{model} is the model of hardware watchdog to emulate.  Choices
3129 for model are: @code{ib700} (iBASE 700) which is a very simple ISA
3130 watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
3131 controller hub) which is a much more featureful PCI-based dual-timer
3132 watchdog.  Choose a model for which your guest has drivers.
3133
3134 Use @code{-watchdog help} to list available hardware models.  Only one
3135 watchdog can be enabled for a guest.
3136 ETEXI
3137
3138 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3139     "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
3140     "                action when watchdog fires [default=reset]\n",
3141     QEMU_ARCH_ALL)
3142 STEXI
3143 @item -watchdog-action @var{action}
3144 @findex -watchdog-action
3145
3146 The @var{action} controls what QEMU will do when the watchdog timer
3147 expires.
3148 The default is
3149 @code{reset} (forcefully reset the guest).
3150 Other possible actions are:
3151 @code{shutdown} (attempt to gracefully shutdown the guest),
3152 @code{poweroff} (forcefully poweroff the guest),
3153 @code{pause} (pause the guest),
3154 @code{debug} (print a debug message and continue), or
3155 @code{none} (do nothing).
3156
3157 Note that the @code{shutdown} action requires that the guest responds
3158 to ACPI signals, which it may not be able to do in the sort of
3159 situations where the watchdog would have expired, and thus
3160 @code{-watchdog-action shutdown} is not recommended for production use.
3161
3162 Examples:
3163
3164 @table @code
3165 @item -watchdog i6300esb -watchdog-action pause
3166 @item -watchdog ib700
3167 @end table
3168 ETEXI
3169
3170 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
3171     "-echr chr       set terminal escape character instead of ctrl-a\n",
3172     QEMU_ARCH_ALL)
3173 STEXI
3174
3175 @item -echr @var{numeric_ascii_value}
3176 @findex -echr
3177 Change the escape character used for switching to the monitor when using
3178 monitor and serial sharing.  The default is @code{0x01} when using the
3179 @code{-nographic} option.  @code{0x01} is equal to pressing
3180 @code{Control-a}.  You can select a different character from the ascii
3181 control keys where 1 through 26 map to Control-a through Control-z.  For
3182 instance you could use the either of the following to change the escape
3183 character to Control-t.
3184 @table @code
3185 @item -echr 0x14
3186 @item -echr 20
3187 @end table
3188 ETEXI
3189
3190 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3191     "-virtioconsole c\n" \
3192     "                set virtio console\n", QEMU_ARCH_ALL)
3193 STEXI
3194 @item -virtioconsole @var{c}
3195 @findex -virtioconsole
3196 Set virtio console.
3197
3198 This option is maintained for backward compatibility.
3199
3200 Please use @code{-device virtconsole} for the new way of invocation.
3201 ETEXI
3202
3203 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
3204     "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
3205 STEXI
3206 @item -show-cursor
3207 @findex -show-cursor
3208 Show cursor.
3209 ETEXI
3210
3211 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
3212     "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
3213 STEXI
3214 @item -tb-size @var{n}
3215 @findex -tb-size
3216 Set TB size.
3217 ETEXI
3218
3219 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
3220     "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3221     "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3222     "-incoming unix:socketpath\n" \
3223     "                prepare for incoming migration, listen on\n" \
3224     "                specified protocol and socket address\n" \
3225     "-incoming fd:fd\n" \
3226     "-incoming exec:cmdline\n" \
3227     "                accept incoming migration on given file descriptor\n" \
3228     "                or from given external command\n",
3229     QEMU_ARCH_ALL)
3230 STEXI
3231 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3232 @item -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3233 @findex -incoming
3234 Prepare for incoming migration, listen on a given tcp port.
3235
3236 @item -incoming unix:@var{socketpath}
3237 Prepare for incoming migration, listen on a given unix socket.
3238
3239 @item -incoming fd:@var{fd}
3240 Accept incoming migration from a given filedescriptor.
3241
3242 @item -incoming exec:@var{cmdline}
3243 Accept incoming migration as an output from specified external command.
3244 ETEXI
3245
3246 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
3247     "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
3248 STEXI
3249 @item -nodefaults
3250 @findex -nodefaults
3251 Don't create default devices. Normally, QEMU sets the default devices like serial
3252 port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3253 CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3254 default devices.
3255 ETEXI
3256
3257 #ifndef _WIN32
3258 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
3259     "-chroot dir     chroot to dir just before starting the VM\n",
3260     QEMU_ARCH_ALL)
3261 #endif
3262 STEXI
3263 @item -chroot @var{dir}
3264 @findex -chroot
3265 Immediately before starting guest execution, chroot to the specified
3266 directory.  Especially useful in combination with -runas.
3267 ETEXI
3268
3269 #ifndef _WIN32
3270 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
3271     "-runas user     change to user id user just before starting the VM\n",
3272     QEMU_ARCH_ALL)
3273 #endif
3274 STEXI
3275 @item -runas @var{user}
3276 @findex -runas
3277 Immediately before starting guest execution, drop root privileges, switching
3278 to the specified user.
3279 ETEXI
3280
3281 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3282     "-prom-env variable=value\n"
3283     "                set OpenBIOS nvram variables\n",
3284     QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
3285 STEXI
3286 @item -prom-env @var{variable}=@var{value}
3287 @findex -prom-env
3288 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3289 ETEXI
3290 DEF("semihosting", 0, QEMU_OPTION_semihosting,
3291     "-semihosting    semihosting mode\n",
3292     QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32)
3293 STEXI
3294 @item -semihosting
3295 @findex -semihosting
3296 Enable semihosting mode (ARM, M68K, Xtensa only).
3297 ETEXI
3298 DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
3299     "-semihosting-config [enable=on|off,]target=native|gdb|auto   semihosting configuration\n",
3300 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32)
3301 STEXI
3302 @item -semihosting-config [enable=on|off,]target=native|gdb|auto
3303 @findex -semihosting-config
3304 Enable semihosting and define where the semihosting calls will be addressed,
3305 to QEMU (@code{native}) or to GDB (@code{gdb}). The default is @code{auto}, which means
3306 @code{gdb} during debug sessions and @code{native} otherwise (ARM, M68K, Xtensa only).
3307 ETEXI
3308 DEF("old-param", 0, QEMU_OPTION_old_param,
3309     "-old-param      old param mode\n", QEMU_ARCH_ARM)
3310 STEXI
3311 @item -old-param
3312 @findex -old-param (ARM)
3313 Old param mode (ARM only).
3314 ETEXI
3315
3316 DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
3317     "-sandbox <arg>  Enable seccomp mode 2 system call filter (default 'off').\n",
3318     QEMU_ARCH_ALL)
3319 STEXI
3320 @item -sandbox @var{arg}
3321 @findex -sandbox
3322 Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3323 disable it.  The default is 'off'.
3324 ETEXI
3325
3326 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
3327     "-readconfig <file>\n", QEMU_ARCH_ALL)
3328 STEXI
3329 @item -readconfig @var{file}
3330 @findex -readconfig
3331 Read device configuration from @var{file}. This approach is useful when you want to spawn
3332 QEMU process with many command line options but you don't want to exceed the command line
3333 character limit.
3334 ETEXI
3335 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3336     "-writeconfig <file>\n"
3337     "                read/write config file\n", QEMU_ARCH_ALL)
3338 STEXI
3339 @item -writeconfig @var{file}
3340 @findex -writeconfig
3341 Write device configuration to @var{file}. The @var{file} can be either filename to save
3342 command line and device configuration into file or dash @code{-}) character to print the
3343 output to stdout. This can be later used as input file for @code{-readconfig} option.
3344 ETEXI
3345 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3346     "-nodefconfig\n"
3347     "                do not load default config files at startup\n",
3348     QEMU_ARCH_ALL)
3349 STEXI
3350 @item -nodefconfig
3351 @findex -nodefconfig
3352 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3353 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3354 ETEXI
3355 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3356     "-no-user-config\n"
3357     "                do not load user-provided config files at startup\n",
3358     QEMU_ARCH_ALL)
3359 STEXI
3360 @item -no-user-config
3361 @findex -no-user-config
3362 The @code{-no-user-config} option makes QEMU not load any of the user-provided
3363 config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
3364 files from @var{datadir}.
3365 ETEXI
3366 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
3367     "-trace [events=<file>][,file=<file>]\n"
3368     "                specify tracing options\n",
3369     QEMU_ARCH_ALL)
3370 STEXI
3371 HXCOMM This line is not accurate, as some sub-options are backend-specific but
3372 HXCOMM HX does not support conditional compilation of text.
3373 @item -trace [events=@var{file}][,file=@var{file}]
3374 @findex -trace
3375
3376 Specify tracing options.
3377
3378 @table @option
3379 @item events=@var{file}
3380 Immediately enable events listed in @var{file}.
3381 The file must contain one event name (as listed in the @var{trace-events} file)
3382 per line.
3383 This option is only available if QEMU has been compiled with
3384 either @var{simple} or @var{stderr} tracing backend.
3385 @item file=@var{file}
3386 Log output traces to @var{file}.
3387
3388 This option is only available if QEMU has been compiled with
3389 the @var{simple} tracing backend.
3390 @end table
3391 ETEXI
3392
3393 HXCOMM Internal use
3394 DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3395 DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
3396
3397 #ifdef __linux__
3398 DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3399     "-enable-fips    enable FIPS 140-2 compliance\n",
3400     QEMU_ARCH_ALL)
3401 #endif
3402 STEXI
3403 @item -enable-fips
3404 @findex -enable-fips
3405 Enable FIPS 140-2 compliance mode.
3406 ETEXI
3407
3408 HXCOMM Deprecated by -machine accel=tcg property
3409 DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
3410
3411 HXCOMM Deprecated by kvm-pit driver properties
3412 DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
3413     "", QEMU_ARCH_I386)
3414
3415 HXCOMM Deprecated (ignored)
3416 DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
3417
3418 HXCOMM Deprecated by -machine kernel_irqchip=on|off property
3419 DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
3420
3421 HXCOMM Deprecated (ignored)
3422 DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
3423
3424 DEF("object", HAS_ARG, QEMU_OPTION_object,
3425     "-object TYPENAME[,PROP1=VALUE1,...]\n"
3426     "                create an new object of type TYPENAME setting properties\n"
3427     "                in the order they are specified.  Note that the 'id'\n"
3428     "                property must be set.  These objects are placed in the\n"
3429     "                '/objects' path.\n",
3430     QEMU_ARCH_ALL)
3431 STEXI
3432 @item -object @var{typename}[,@var{prop1}=@var{value1},...]
3433 @findex -object
3434 Create an new object of type @var{typename} setting properties
3435 in the order they are specified.  Note that the 'id'
3436 property must be set.  These objects are placed in the
3437 '/objects' path.
3438 ETEXI
3439
3440 DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3441     "-msg timestamp[=on|off]\n"
3442     "                change the format of messages\n"
3443     "                on|off controls leading timestamps (default:on)\n",
3444     QEMU_ARCH_ALL)
3445 STEXI
3446 @item -msg timestamp[=on|off]
3447 @findex -msg
3448 prepend a timestamp to each log message.(default:on)
3449 ETEXI
3450
3451 DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3452     "-dump-vmstate <file>\n"
3453     "                Output vmstate information in JSON format to file.\n"
3454     "                Use the scripts/vmstate-static-checker.py file to\n"
3455     "                check for possible regressions in migration code\n"
3456     "                by comparing two such vmstate dumps.",
3457     QEMU_ARCH_ALL)
3458 STEXI
3459 @item -dump-vmstate @var{file}
3460 @findex -dump-vmstate
3461 Dump json-encoded vmstate information for current machine type to file
3462 in @var{file}
3463 ETEXI
3464
3465 HXCOMM This is the last statement. Insert new options before this line!
3466 STEXI
3467 @end table
3468 ETEXI