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