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