]> git.proxmox.com Git - mirror_qemu.git/blame - qemu-options.hx
Revert "vl: Fix to create migration object before block backends again"
[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
de6b4f90 9DEFHEADING(Standard options:)
5824d651
BS
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"
d661d9a4 34 " supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n"
32c18a2d 35 " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
d1048bef 36 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
96404013 37 " kvm_shadow_mem=size of KVM shadow MMU in bytes\n"
8490fc78 38 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
a52a7fdf 39 " mem-merge=on|off controls memory merge support (default: on)\n"
79814179 40 " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
2eb1cd07 41 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
9850c604 42 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
87252e1b 43 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
902c053d 44 " nvdimm=on|off controls NVDIMM support (default=off)\n"
274250c3 45 " enforce-config-section=on|off enforce configuration section migration (default=off)\n"
db588194 46 " memory-encryption=@var{} memory encryption object to use (default=none)\n",
80f52a66 47 QEMU_ARCH_ALL)
5824d651 48STEXI
80f52a66
JK
49@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
50@findex -machine
585f6036 51Select the emulated machine by @var{name}. Use @code{-machine help} to list
8bfce83a
DB
52available machines.
53
54For architectures which aim to support live migration compatibility
55across releases, each release will introduce a new versioned machine
56type. For example, the 2.8.0 release introduced machine types
57``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
58
59To allow live migration of guests from QEMU version 2.8.0, to QEMU
60version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
61and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
62to skip multiple intermediate releases when upgrading, new releases
63of QEMU will support machine types from many previous versions.
64
65Supported machine properties are:
80f52a66
JK
66@table @option
67@item accel=@var{accels1}[:@var{accels2}[:...]]
68This is used to enable an accelerator. Depending on the target architecture,
d661d9a4 69kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
bde4d920
TH
70more than one accelerator specified, the next one is used if the previous one
71fails to initialize.
6a48ffaa 72@item kernel_irqchip=on|off
32c18a2d 73Controls in-kernel irqchip support for the chosen accelerator when available.
79814179
TC
74@item gfx_passthru=on|off
75Enables IGD GFX passthrough support for the chosen machine when available.
d1048bef
DS
76@item vmport=on|off|auto
77Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
78value based on accel. For accel=xen the default is off otherwise the default
79is on.
39d6960a
JK
80@item kvm_shadow_mem=size
81Defines the size of the KVM shadow MMU.
ddb97f1d
JB
82@item dump-guest-core=on|off
83Include guest memory in a core dump. The default is on.
8490fc78
LC
84@item mem-merge=on|off
85Enables or disables memory merge support. This feature, when supported by
86the host, de-duplicates identical memory pages among VMs instances
87(enabled by default).
2eb1cd07
TK
88@item aes-key-wrap=on|off
89Enables or disables AES key wrapping support on s390-ccw hosts. This feature
90controls whether AES wrapping keys will be created to allow
91execution of AES cryptographic functions. The default is on.
92@item dea-key-wrap=on|off
93Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
94controls whether DEA wrapping keys will be created to allow
95execution of DEA cryptographic functions. The default is on.
87252e1b
XG
96@item nvdimm=on|off
97Enables or disables NVDIMM support. The default is off.
16f72448
PX
98@item enforce-config-section=on|off
99If @option{enforce-config-section} is set to @var{on}, force migration
100code to send configuration section even if the machine-type sets the
101@option{migration.send-configuration} property to @var{off}.
102NOTE: this parameter is deprecated. Please use @option{-global}
103@option{migration.send-configuration}=@var{on|off} instead.
db588194
BS
104@item memory-encryption=@var{}
105Memory encryption object to use. The default is none.
80f52a66 106@end table
5824d651
BS
107ETEXI
108
80f52a66
JK
109HXCOMM Deprecated by -machine
110DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
111
5824d651 112DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
585f6036 113 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
5824d651
BS
114STEXI
115@item -cpu @var{model}
6616b2ad 116@findex -cpu
585f6036 117Select CPU model (@code{-cpu help} for list and additional feature selection)
5824d651
BS
118ETEXI
119
8d4e9146
FK
120DEF("accel", HAS_ARG, QEMU_OPTION_accel,
121 "-accel [accel=]accelerator[,thread=single|multi]\n"
d661d9a4 122 " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
0b3c5c81 123 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
8d4e9146
FK
124STEXI
125@item -accel @var{name}[,prop=@var{value}[,...]]
126@findex -accel
127This is used to enable an accelerator. Depending on the target architecture,
d661d9a4 128kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
bde4d920
TH
129more than one accelerator specified, the next one is used if the previous one
130fails to initialize.
8d4e9146
FK
131@table @option
132@item thread=single|multi
133Controls number of TCG threads. When the TCG is multi-threaded there will be one
134thread per vCPU therefor taking advantage of additional host cores. The default
135is to enable multi-threading where both the back-end and front-ends support it and
136no incompatible TCG features have been enabled (e.g. icount/replay).
137@end table
138ETEXI
139
5824d651 140DEF("smp", HAS_ARG, QEMU_OPTION_smp,
12b7f57e 141 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
6be68d7e
JS
142 " set the number of CPUs to 'n' [default=1]\n"
143 " maxcpus= maximum number of total cpus, including\n"
ca1a8a06 144 " offline CPUs for hotplug, etc\n"
58a04db1
AP
145 " cores= number of CPU cores on one socket\n"
146 " threads= number of threads on one CPU core\n"
ad96090a
BS
147 " sockets= number of discrete sockets in the system\n",
148 QEMU_ARCH_ALL)
5824d651 149STEXI
12b7f57e 150@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
6616b2ad 151@findex -smp
5824d651
BS
152Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
153CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
154to 4.
58a04db1
AP
155For the PC target, the number of @var{cores} per socket, the number
156of @var{threads} per cores and the total number of @var{sockets} can be
157specified. Missing values will be computed. If any on the three values is
158given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
159specifies the maximum number of hotpluggable CPUs.
5824d651
BS
160ETEXI
161
268a362c 162DEF("numa", HAS_ARG, QEMU_OPTION_numa,
e0ee9fd0 163 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
0f203430 164 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
2d19c656
IM
165 "-numa dist,src=source,dst=destination,val=distance\n"
166 "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n",
167 QEMU_ARCH_ALL)
268a362c 168STEXI
e0ee9fd0
EH
169@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
170@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
0f203430 171@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
419fcdec 172@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
6616b2ad 173@findex -numa
4b9a5dd7 174Define a NUMA node and assign RAM and VCPUs to it.
0f203430 175Set the NUMA distance from a source node to a destination node.
4b9a5dd7 176
419fcdec 177Legacy VCPU assignment uses @samp{cpus} option where
4b9a5dd7
EH
178@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
179@samp{cpus} option represent a contiguous range of CPU indexes
180(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
181set of VCPUs can be represented by providing multiple @samp{cpus}
182options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
183split between them.
184
185For example, the following option assigns VCPUs 0, 1, 2 and 5 to
186a NUMA node:
187@example
188-numa node,cpus=0-2,cpus=5
189@end example
190
419fcdec
IM
191@samp{cpu} option is a new alternative to @samp{cpus} option
192which uses @samp{socket-id|core-id|thread-id} properties to assign
193CPU objects to a @var{node} using topology layout properties of CPU.
194The set of properties is machine specific, and depends on used
195machine type/@samp{smp} options. It could be queried with
196@samp{hotpluggable-cpus} monitor command.
197@samp{node-id} property specifies @var{node} to which CPU object
198will be assigned, it's required for @var{node} to be declared
199with @samp{node} option before it's used with @samp{cpu} option.
200
201For example:
202@example
203-M pc \
204-smp 1,sockets=2,maxcpus=2 \
205-numa node,nodeid=0 -numa node,nodeid=1 \
206-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
207@end example
208
4b9a5dd7
EH
209@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
210assigns RAM from a given memory backend device to a node. If
211@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
212split equally between them.
213
214@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
215if one node uses @samp{memdev}, all of them have to use it.
216
0f203430
HC
217@var{source} and @var{destination} are NUMA node IDs.
218@var{distance} is the NUMA distance from @var{source} to @var{destination}.
219The distance from a node to itself is always 10. If any pair of nodes is
220given a distance, then all pairs must be given distances. Although, when
221distances are only given in one direction for each pair of nodes, then
222the distances in the opposite directions are assumed to be the same. If,
223however, an asymmetrical pair of distances is given for even one node
224pair, then all node pairs must be provided distance values for both
225directions, even when they are symmetrical. When a node is unreachable
226from another node, set the pair's distance to 255.
227
4b9a5dd7
EH
228Note that the -@option{numa} option doesn't allocate any of the
229specified resources, it just assigns existing resources to NUMA
230nodes. This means that one still has to use the @option{-m},
231@option{-smp} options to allocate RAM and VCPUs respectively.
232
268a362c
AL
233ETEXI
234
587ed6be
CB
235DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
236 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
237 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
238STEXI
239@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
240@findex -add-fd
241
242Add a file descriptor to an fd set. Valid options are:
243
244@table @option
245@item fd=@var{fd}
246This option defines the file descriptor of which a duplicate is added to fd set.
247The file descriptor cannot be stdin, stdout, or stderr.
248@item set=@var{set}
249This option defines the ID of the fd set to add the file descriptor to.
250@item opaque=@var{opaque}
251This option defines a free-form string that can be used to describe @var{fd}.
252@end table
253
254You can open an image using pre-opened file descriptors from an fd set:
255@example
256qemu-system-i386
257-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
258-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
259-drive file=/dev/fdset/2,index=0,media=disk
260@end example
261ETEXI
262
6616b2ad
SW
263DEF("set", HAS_ARG, QEMU_OPTION_set,
264 "-set group.id.arg=value\n"
265 " set <arg> parameter for item <id> of type <group>\n"
ad96090a 266 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
6616b2ad 267STEXI
6265c43b 268@item -set @var{group}.@var{id}.@var{arg}=@var{value}
6616b2ad 269@findex -set
e1f3b974 270Set parameter @var{arg} for item @var{id} of type @var{group}
6616b2ad
SW
271ETEXI
272
273DEF("global", HAS_ARG, QEMU_OPTION_global,
3751d7c4
PB
274 "-global driver.property=value\n"
275 "-global driver=driver,property=property,value=value\n"
ad96090a
BS
276 " set a global default for a driver property\n",
277 QEMU_ARCH_ALL)
6616b2ad 278STEXI
3017b72c 279@item -global @var{driver}.@var{prop}=@var{value}
3751d7c4 280@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
6616b2ad 281@findex -global
3017b72c
MR
282Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
283
284@example
1c9f3b88 285qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
3017b72c
MR
286@end example
287
a295d244
MT
288In particular, you can use this to set driver properties for devices which are
289created automatically by the machine model. To create a device which is not
3017b72c 290created automatically and set properties on it, use -@option{device}.
3751d7c4 291
ae08fd5a
MA
292-global @var{driver}.@var{prop}=@var{value} is shorthand for -global
293driver=@var{driver},property=@var{prop},value=@var{value}. The
294longhand syntax works even when @var{driver} contains a dot.
6616b2ad
SW
295ETEXI
296
5824d651 297DEF("boot", HAS_ARG, QEMU_OPTION_boot,
2221dde5 298 "-boot [order=drives][,once=drives][,menu=on|off]\n"
c8a6ae8b 299 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
3d3b8303
WX
300 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
301 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
ac05f349
AK
302 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
303 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
ad96090a 304 QEMU_ARCH_ALL)
5824d651 305STEXI
c8a6ae8b 306@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 307@findex -boot
2221dde5 308Specify boot order @var{drives} as a string of drive letters. Valid
d274e07c 309drive letters depend on the target architecture. The x86 PC uses: a, b
2221dde5
JK
310(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
311from network adapter 1-4), hard disk boot is the default. To apply a
312particular boot order only on the first startup, specify it via
c0d9f7d0
TH
313@option{once}. Note that the @option{order} or @option{once} parameter
314should not be used together with the @option{bootindex} property of
315devices, since the firmware implementations normally do not support both
316at the same time.
2221dde5
JK
317
318Interactive boot menus/prompts can be enabled via @option{menu=on} as far
319as firmware/BIOS supports them. The default is non-interactive boot.
320
3d3b8303
WX
321A splash picture could be passed to bios, enabling user to show it as logo,
322when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
323supports them. Currently Seabios for X86 system support it.
324limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
325format(true color). The resolution should be supported by the SVGA mode, so
326the recommended is 320x240, 640x480, 800x640.
327
ac05f349
AK
328A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
329when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
330reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
331system support it.
332
c8a6ae8b
AK
333Do strict boot via @option{strict=on} as far as firmware/BIOS
334supports it. This only effects when boot priority is changed by
335bootindex options. The default is non-strict boot.
336
2221dde5
JK
337@example
338# try to boot from network first, then from hard disk
3804da9d 339qemu-system-i386 -boot order=nc
2221dde5 340# boot from CD-ROM first, switch back to default order after reboot
3804da9d 341qemu-system-i386 -boot once=d
3d3b8303 342# boot with a splash picture for 5 seconds.
3804da9d 343qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
2221dde5
JK
344@end example
345
346Note: The legacy format '-boot @var{drives}' is still supported but its
347use is discouraged as it may be removed from future versions.
5824d651
BS
348ETEXI
349
5824d651 350DEF("m", HAS_ARG, QEMU_OPTION_m,
89f3ea2b 351 "-m [size=]megs[,slots=n,maxmem=size]\n"
6e1d3c1c 352 " configure guest RAM\n"
0daba1f0 353 " size: initial amount of guest memory\n"
c270fb9e 354 " slots: number of hotplug slots (default: none)\n"
b6fe0124
MR
355 " maxmem: maximum amount of guest memory (default: none)\n"
356 "NOTE: Some architectures might enforce a specific granularity\n",
6e1d3c1c 357 QEMU_ARCH_ALL)
5824d651 358STEXI
9fcc0794 359@item -m [size=]@var{megs}[,slots=n,maxmem=size]
6616b2ad 360@findex -m
9fcc0794
LC
361Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
362Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
363megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
364could be used to set amount of hotpluggable memory slots and maximum amount of
365memory. Note that @var{maxmem} must be aligned to the page size.
366
367For example, the following command-line sets the guest startup RAM size to
3681GB, creates 3 slots to hotplug additional memory and sets the maximum
369memory the guest can reach to 4GB:
370
371@example
372qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
373@end example
374
375If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
376be enabled and the guest startup RAM will never increase.
5824d651
BS
377ETEXI
378
c902760f 379DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
ad96090a 380 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
c902760f
MT
381STEXI
382@item -mem-path @var{path}
b8f490eb 383@findex -mem-path
c902760f
MT
384Allocate guest RAM from a temporarily created file in @var{path}.
385ETEXI
386
c902760f 387DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
ad96090a
BS
388 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
389 QEMU_ARCH_ALL)
c902760f
MT
390STEXI
391@item -mem-prealloc
b8f490eb 392@findex -mem-prealloc
c902760f
MT
393Preallocate memory when using -mem-path.
394ETEXI
c902760f 395
5824d651 396DEF("k", HAS_ARG, QEMU_OPTION_k,
ad96090a
BS
397 "-k language use keyboard layout (for example 'fr' for French)\n",
398 QEMU_ARCH_ALL)
5824d651
BS
399STEXI
400@item -k @var{language}
6616b2ad 401@findex -k
5824d651
BS
402Use keyboard layout @var{language} (for example @code{fr} for
403French). This option is only needed where it is not easy to get raw PC
32945472 404keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
5824d651
BS
405display). You don't normally need to use it on PC/Linux or PC/Windows
406hosts.
407
408The available layouts are:
409@example
410ar de-ch es fo fr-ca hu ja mk no pt-br sv
411da en-gb et fr fr-ch is lt nl pl ru th
412de en-us fi fr-be hr it lv nl-be pt sl tr
413@end example
414
415The default is @code{en-us}.
416ETEXI
417
418
f0b3d811 419HXCOMM Deprecated by -audiodev
5824d651 420DEF("audio-help", 0, QEMU_OPTION_audio_help,
f0b3d811 421 "-audio-help show -audiodev equivalent of the currently specified audio settings\n",
ad96090a 422 QEMU_ARCH_ALL)
5824d651
BS
423STEXI
424@item -audio-help
6616b2ad 425@findex -audio-help
f0b3d811
KZ
426Will show the -audiodev equivalent of the currently specified
427(deprecated) environment variables.
428ETEXI
429
430DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
431 "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
432 " specifies the audio backend to use\n"
433 " id= identifier of the backend\n"
434 " timer-period= timer period in microseconds\n"
435 " in|out.fixed-settings= use fixed settings for host audio\n"
436 " in|out.frequency= frequency to use with fixed settings\n"
437 " in|out.channels= number of channels to use with fixed settings\n"
438 " in|out.format= sample format to use with fixed settings\n"
439 " valid values: s8, s16, s32, u8, u16, u32\n"
440 " in|out.voices= number of voices to use\n"
441 " in|out.buffer-len= length of buffer in microseconds\n"
442 "-audiodev none,id=id,[,prop[=value][,...]]\n"
443 " dummy driver that discards all output\n"
444#ifdef CONFIG_AUDIO_ALSA
445 "-audiodev alsa,id=id[,prop[=value][,...]]\n"
446 " in|out.dev= name of the audio device to use\n"
447 " in|out.period-len= length of period in microseconds\n"
448 " in|out.try-poll= attempt to use poll mode\n"
449 " threshold= threshold (in microseconds) when playback starts\n"
450#endif
451#ifdef CONFIG_AUDIO_COREAUDIO
452 "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
453 " in|out.buffer-count= number of buffers\n"
454#endif
455#ifdef CONFIG_AUDIO_DSOUND
456 "-audiodev dsound,id=id[,prop[=value][,...]]\n"
457 " latency= add extra latency to playback in microseconds\n"
458#endif
459#ifdef CONFIG_AUDIO_OSS
460 "-audiodev oss,id=id[,prop[=value][,...]]\n"
461 " in|out.dev= path of the audio device to use\n"
462 " in|out.buffer-count= number of buffers\n"
463 " in|out.try-poll= attempt to use poll mode\n"
464 " try-mmap= try using memory mapped access\n"
465 " exclusive= open device in exclusive mode\n"
466 " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
467#endif
468#ifdef CONFIG_AUDIO_PA
469 "-audiodev pa,id=id[,prop[=value][,...]]\n"
470 " server= PulseAudio server address\n"
471 " in|out.name= source/sink device name\n"
472#endif
473#ifdef CONFIG_AUDIO_SDL
474 "-audiodev sdl,id=id[,prop[=value][,...]]\n"
475#endif
476#ifdef CONFIG_SPICE
477 "-audiodev spice,id=id[,prop[=value][,...]]\n"
478#endif
479 "-audiodev wav,id=id[,prop[=value][,...]]\n"
480 " path= path of wav file to record\n",
481 QEMU_ARCH_ALL)
482STEXI
483@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]]
484@findex -audiodev
485Adds a new audio backend @var{driver} identified by @var{id}. There are
486global and driver specific properties. Some values can be set
487differently for input and output, they're marked with @code{in|out.}.
488You can set the input's property with @code{in.@var{prop}} and the
489output's property with @code{out.@var{prop}}. For example:
490@example
491-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
492-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
493@end example
494
495Valid global options are:
496
497@table @option
498@item id=@var{identifier}
499Identifies the audio backend.
500
501@item timer-period=@var{period}
502Sets the timer @var{period} used by the audio subsystem in microseconds.
503Default is 10000 (10 ms).
504
505@item in|out.fixed-settings=on|off
506Use fixed settings for host audio. When off, it will change based on
507how the guest opens the sound card. In this case you must not specify
508@var{frequency}, @var{channels} or @var{format}. Default is on.
509
510@item in|out.frequency=@var{frequency}
511Specify the @var{frequency} to use when using @var{fixed-settings}.
512Default is 44100Hz.
513
514@item in|out.channels=@var{channels}
515Specify the number of @var{channels} to use when using
516@var{fixed-settings}. Default is 2 (stereo).
517
518@item in|out.format=@var{format}
519Specify the sample @var{format} to use when using @var{fixed-settings}.
520Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
521@code{u16}, @code{u32}. Default is @code{s16}.
522
523@item in|out.voices=@var{voices}
524Specify the number of @var{voices} to use. Default is 1.
525
526@item in|out.buffer=@var{usecs}
527Sets the size of the buffer in microseconds.
528
529@end table
530
531@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]]
532Creates a dummy backend that discards all outputs. This backend has no
533backend specific properties.
534
535@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
536Creates backend using the ALSA. This backend is only available on
537Linux.
538
539ALSA specific options are:
540
541@table @option
542
543@item in|out.dev=@var{device}
544Specify the ALSA @var{device} to use for input and/or output. Default
545is @code{default}.
546
547@item in|out.period-len=@var{usecs}
548Sets the period length in microseconds.
549
550@item in|out.try-poll=on|off
551Attempt to use poll mode with the device. Default is on.
552
553@item threshold=@var{threshold}
554Threshold (in microseconds) when playback starts. Default is 0.
555
556@end table
557
558@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]]
559Creates a backend using Apple's Core Audio. This backend is only
560available on Mac OS and only supports playback.
561
562Core Audio specific options are:
563
564@table @option
565
566@item in|out.buffer-count=@var{count}
567Sets the @var{count} of the buffers.
568
569@end table
570
571@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]]
572Creates a backend using Microsoft's DirectSound. This backend is only
573available on Windows and only supports playback.
574
575DirectSound specific options are:
576
577@table @option
578
579@item latency=@var{usecs}
580Add extra @var{usecs} microseconds latency to playback. Default is
58110000 (10 ms).
582
583@end table
584
585@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]]
586Creates a backend using OSS. This backend is available on most
587Unix-like systems.
588
589OSS specific options are:
590
591@table @option
592
593@item in|out.dev=@var{device}
594Specify the file name of the OSS @var{device} to use. Default is
595@code{/dev/dsp}.
596
597@item in|out.buffer-count=@var{count}
598Sets the @var{count} of the buffers.
599
600@item in|out.try-poll=on|of
601Attempt to use poll mode with the device. Default is on.
602
603@item try-mmap=on|off
604Try using memory mapped device access. Default is off.
605
606@item exclusive=on|off
607Open the device in exclusive mode (vmix won't work in this case).
608Default is off.
609
610@item dsp-policy=@var{policy}
611Sets the timing policy (between 0 and 10, where smaller number means
612smaller latency but higher CPU usage). Use -1 to use buffer sizes
613specified by @code{buffer} and @code{buffer-count}. This option is
614ignored if you do not have OSS 4. Default is 5.
615
616@end table
617
618@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
619Creates a backend using PulseAudio. This backend is available on most
620systems.
621
622PulseAudio specific options are:
623
624@table @option
625
626@item server=@var{server}
627Sets the PulseAudio @var{server} to connect to.
628
629@item in|out.name=@var{sink}
630Use the specified source/sink for recording/playback.
631
632@end table
633
634@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
635Creates a backend using SDL. This backend is available on most systems,
636but you should use your platform's native backend if possible. This
637backend has no backend specific properties.
638
639@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]]
640Creates a backend that sends audio through SPICE. This backend requires
641@code{-spice} and automatically selected in that case, so usually you
642can ignore this option. This backend has no backend specific
643properties.
644
645@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
646Creates a backend that writes audio to a WAV file.
647
648Backend specific options are:
649
650@table @option
651
652@item path=@var{path}
653Write recorded audio into the specified file. Default is
654@code{qemu.wav}.
655
656@end table
5824d651
BS
657ETEXI
658
5824d651
BS
659DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
660 "-soundhw c1,... enable audio support\n"
661 " and only specified sound cards (comma separated list)\n"
585f6036
PM
662 " use '-soundhw help' to get the list of supported cards\n"
663 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
5824d651
BS
664STEXI
665@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
6616b2ad 666@findex -soundhw
585f6036 667Enable audio and selected sound hardware. Use 'help' to print all
5824d651
BS
668available sound hardware.
669
670@example
10adb8be
MA
671qemu-system-i386 -soundhw sb16,adlib disk.img
672qemu-system-i386 -soundhw es1370 disk.img
673qemu-system-i386 -soundhw ac97 disk.img
674qemu-system-i386 -soundhw hda disk.img
675qemu-system-i386 -soundhw all disk.img
676qemu-system-i386 -soundhw help
677@end example
678
679Note that Linux's i810_audio OSS kernel (for AC97) module might
680require manually specifying clocking.
681
682@example
683modprobe i810_audio clocking=48000
684@end example
685ETEXI
686
10adb8be
MA
687DEF("device", HAS_ARG, QEMU_OPTION_device,
688 "-device driver[,prop[=value][,...]]\n"
689 " add device (based on driver)\n"
690 " prop=value,... sets driver properties\n"
691 " use '-device help' to print all possible drivers\n"
692 " use '-device driver,help' to print all possible properties\n",
693 QEMU_ARCH_ALL)
694STEXI
695@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
696@findex -device
697Add device @var{driver}. @var{prop}=@var{value} sets driver
698properties. Valid properties depend on the driver. To get help on
699possible drivers and properties, use @code{-device help} and
700@code{-device @var{driver},help}.
f8490451
CM
701
702Some drivers are:
540c07d3 703@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
f8490451
CM
704
705Add an IPMI BMC. This is a simulation of a hardware management
706interface processor that normally sits on a system. It provides
707a watchdog and the ability to reset and power control the system.
708You need to connect this to an IPMI interface to make it useful
709
710The IPMI slave address to use for the BMC. The default is 0x20.
711This address is the BMC's address on the I2C network of management
712controllers. If you don't know what this means, it is safe to ignore
713it.
714
8c6fd7f3
CLG
715@table @option
716@item bmc=@var{id}
717The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
718@item slave_addr=@var{val}
719Define slave address to use for the BMC. The default is 0x20.
720@item sdrfile=@var{file}
540c07d3
CLG
721file containing raw Sensor Data Records (SDR) data. The default is none.
722@item fruareasize=@var{val}
723size of a Field Replaceable Unit (FRU) area. The default is 1024.
724@item frudatafile=@var{file}
725file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
8c6fd7f3
CLG
726@end table
727
f8490451
CM
728@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
729
730Add a connection to an external IPMI BMC simulator. Instead of
731locally emulating the BMC like the above item, instead connect
732to an external entity that provides the IPMI services.
733
734A connection is made to an external BMC simulator. If you do this, it
735is strongly recommended that you use the "reconnect=" chardev option
736to reconnect to the simulator if the connection is lost. Note that if
737this is not used carefully, it can be a security issue, as the
738interface has the ability to send resets, NMIs, and power off the VM.
739It's best if QEMU makes a connection to an external simulator running
740on a secure port on localhost, so neither the simulator nor QEMU is
741exposed to any outside network.
742
743See the "lanserv/README.vm" file in the OpenIPMI library for more
744details on the external interface.
745
746@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
747
748Add a KCS IPMI interafce on the ISA bus. This also adds a
749corresponding ACPI and SMBIOS entries, if appropriate.
750
751@table @option
752@item bmc=@var{id}
753The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
754@item ioport=@var{val}
755Define the I/O address of the interface. The default is 0xca0 for KCS.
756@item irq=@var{val}
757Define the interrupt to use. The default is 5. To disable interrupts,
758set this to 0.
759@end table
760
761@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
762
763Like the KCS interface, but defines a BT interface. The default port is
7640xe4 and the default interrupt is 5.
765
10adb8be
MA
766ETEXI
767
768DEF("name", HAS_ARG, QEMU_OPTION_name,
8f480de0 769 "-name string1[,process=string2][,debug-threads=on|off]\n"
10adb8be 770 " set the name of the guest\n"
479a5747
RB
771 " string1 sets the window title and string2 the process name\n"
772 " When debug-threads is enabled, individual threads are given a separate name\n"
8f480de0 773 " NOTE: The thread names are for debugging and not a stable API.\n",
10adb8be
MA
774 QEMU_ARCH_ALL)
775STEXI
776@item -name @var{name}
777@findex -name
778Sets the @var{name} of the guest.
779This name will be displayed in the SDL window caption.
780The @var{name} will also be used for the VNC server.
781Also optionally set the top visible process name in Linux.
8f480de0 782Naming of individual threads can also be enabled on Linux to aid debugging.
10adb8be
MA
783ETEXI
784
785DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
786 "-uuid %08x-%04x-%04x-%04x-%012x\n"
787 " specify machine UUID\n", QEMU_ARCH_ALL)
788STEXI
789@item -uuid @var{uuid}
790@findex -uuid
791Set system UUID.
792ETEXI
793
794STEXI
795@end table
796ETEXI
797DEFHEADING()
798
de6b4f90 799DEFHEADING(Block device options:)
10adb8be
MA
800STEXI
801@table @option
802ETEXI
803
804DEF("fda", HAS_ARG, QEMU_OPTION_fda,
805 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
806DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
807STEXI
808@item -fda @var{file}
f9cfd655 809@itemx -fdb @var{file}
10adb8be
MA
810@findex -fda
811@findex -fdb
92a539d2 812Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
10adb8be
MA
813ETEXI
814
815DEF("hda", HAS_ARG, QEMU_OPTION_hda,
816 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
817DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
818DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
819 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
820DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
821STEXI
822@item -hda @var{file}
f9cfd655
MA
823@itemx -hdb @var{file}
824@itemx -hdc @var{file}
825@itemx -hdd @var{file}
10adb8be
MA
826@findex -hda
827@findex -hdb
828@findex -hdc
829@findex -hdd
830Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
831ETEXI
832
833DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
834 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
835 QEMU_ARCH_ALL)
836STEXI
837@item -cdrom @var{file}
838@findex -cdrom
839Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
840@option{-cdrom} at the same time). You can use the host CD-ROM by
841using @file{/dev/cdrom} as filename (@pxref{host_drives}).
842ETEXI
843
42e5f393
MA
844DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
845 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
846 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
847 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
848 " [,driver specific parameters...]\n"
849 " configure a block backend\n", QEMU_ARCH_ALL)
dfaca464
KW
850STEXI
851@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
852@findex -blockdev
853
370e8328
KW
854Define a new block driver node. Some of the options apply to all block drivers,
855other options are only accepted for a specific block driver. See below for a
856list of generic options and options for the most common block drivers.
857
858Options that expect a reference to another node (e.g. @code{file}) can be
859given in two ways. Either you specify the node name of an already existing node
860(file=@var{node-name}), or you define a new node inline, adding options
861for the referenced node after a dot (file.filename=@var{path},file.aio=native).
862
863A block driver node created with @option{-blockdev} can be used for a guest
864device by specifying its node name for the @code{drive} property in a
865@option{-device} argument that defines a block device.
dfaca464
KW
866
867@table @option
868@item Valid options for any block driver node:
869
870@table @code
871@item driver
872Specifies the block driver to use for the given node.
873@item node-name
874This defines the name of the block driver node by which it will be referenced
875later. The name must be unique, i.e. it must not match the name of a different
876block driver node, or (if you use @option{-drive} as well) the ID of a drive.
877
878If no node name is specified, it is automatically generated. The generated node
879name is not intended to be predictable and changes between QEMU invocations.
880For the top level, an explicit node name must be specified.
881@item read-only
882Open the node read-only. Guest write attempts will fail.
883@item cache.direct
884The host page cache can be avoided with @option{cache.direct=on}. This will
885attempt to do disk IO directly to the guest's memory. QEMU may still perform an
886internal copy of the data.
887@item cache.no-flush
888In case you don't care about data integrity over host failures, you can use
889@option{cache.no-flush=on}. This option tells QEMU that it never needs to write
890any data to the disk but can instead keep things in cache. If anything goes
891wrong, like your host losing power, the disk storage getting disconnected
892accidentally, etc. your image will most probably be rendered unusable.
893@item discard=@var{discard}
894@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
895whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
896ignored or passed to the filesystem. Some machine types may not support
897discard requests.
898@item detect-zeroes=@var{detect-zeroes}
899@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
900conversion of plain zero writes by the OS to driver specific optimized
901zero write commands. You may even choose "unmap" if @var{discard} is set
902to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
903@end table
904
370e8328
KW
905@item Driver-specific options for @code{file}
906
907This is the protocol-level block driver for accessing regular files.
908
909@table @code
910@item filename
911The path to the image file in the local filesystem
912@item aio
913Specifies the AIO backend (threads/native, default: threads)
1878eaff
FZ
914@item locking
915Specifies whether the image file is protected with Linux OFD / POSIX locks. The
916default is to use the Linux Open File Descriptor API if available, otherwise no
917lock is applied. (auto/on/off, default: auto)
370e8328
KW
918@end table
919Example:
920@example
921-blockdev driver=file,node-name=disk,filename=disk.img
922@end example
923
924@item Driver-specific options for @code{raw}
925
926This is the image format block driver for raw images. It is usually
927stacked on top of a protocol level block driver such as @code{file}.
928
929@table @code
930@item file
931Reference to or definition of the data source block driver node
932(e.g. a @code{file} driver node)
933@end table
934Example 1:
935@example
936-blockdev driver=file,node-name=disk_file,filename=disk.img
937-blockdev driver=raw,node-name=disk,file=disk_file
938@end example
939Example 2:
940@example
941-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
942@end example
943
944@item Driver-specific options for @code{qcow2}
945
946This is the image format block driver for qcow2 images. It is usually
947stacked on top of a protocol level block driver such as @code{file}.
948
949@table @code
950@item file
951Reference to or definition of the data source block driver node
952(e.g. a @code{file} driver node)
953
954@item backing
955Reference to or definition of the backing file block device (default is taken
4f7be280
HR
956from the image file). It is allowed to pass @code{null} here in order to disable
957the default backing file.
370e8328
KW
958
959@item lazy-refcounts
960Whether to enable the lazy refcounts feature (on/off; default is taken from the
961image file)
962
963@item cache-size
964The maximum total size of the L2 table and refcount block caches in bytes
40fb215d 965(default: the sum of l2-cache-size and refcount-cache-size)
370e8328
KW
966
967@item l2-cache-size
968The maximum size of the L2 table cache in bytes
80668d0f
LB
969(default: if cache-size is not specified - 32M on Linux platforms, and 8M on
970non-Linux platforms; otherwise, as large as possible within the cache-size,
971while permitting the requested or the minimal refcount cache size)
370e8328
KW
972
973@item refcount-cache-size
974The maximum size of the refcount block cache in bytes
40fb215d
LB
975(default: 4 times the cluster size; or if cache-size is specified, the part of
976it which is not used for the L2 cache)
370e8328
KW
977
978@item cache-clean-interval
979Clean unused entries in the L2 and refcount caches. The interval is in seconds.
e3a7b455
LB
980The default value is 600 on supporting platforms, and 0 on other platforms.
981Setting it to 0 disables this feature.
370e8328
KW
982
983@item pass-discard-request
984Whether discard requests to the qcow2 device should be forwarded to the data
985source (on/off; default: on if discard=unmap is specified, off otherwise)
986
987@item pass-discard-snapshot
988Whether discard requests for the data source should be issued when a snapshot
989operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
990default: on)
991
992@item pass-discard-other
993Whether discard requests for the data source should be issued on other
994occasions where a cluster gets freed (on/off; default: off)
995
996@item overlap-check
997Which overlap checks to perform for writes to the image
998(none/constant/cached/all; default: cached). For details or finer
999granularity control refer to the QAPI documentation of @code{blockdev-add}.
1000@end table
1001
1002Example 1:
1003@example
1004-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1005-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1006@end example
1007Example 2:
1008@example
1009-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1010@end example
1011
1012@item Driver-specific options for other drivers
1013Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
1014
dfaca464
KW
1015@end table
1016
1017ETEXI
42e5f393 1018
10adb8be
MA
1019DEF("drive", HAS_ARG, QEMU_OPTION_drive,
1020 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
10adb8be 1021 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
572023f7 1022 " [,snapshot=on|off][,rerror=ignore|stop|report]\n"
d1db760d 1023 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
10adb8be 1024 " [,readonly=on|off][,copy-on-read=on|off]\n"
2f7133b2 1025 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
3e9fab69
BC
1026 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
1027 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
1028 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
1029 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
2024c1df 1030 " [[,iops_size=is]]\n"
76f4afb4 1031 " [[,group=g]]\n"
10adb8be
MA
1032 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
1033STEXI
1034@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
1035@findex -drive
1036
dfaca464
KW
1037Define a new drive. This includes creating a block driver node (the backend) as
1038well as a guest device, and is mostly a shortcut for defining the corresponding
1039@option{-blockdev} and @option{-device} options.
1040
1041@option{-drive} accepts all options that are accepted by @option{-blockdev}. In
1042addition, it knows the following options:
10adb8be
MA
1043
1044@table @option
1045@item file=@var{file}
1046This option defines which disk image (@pxref{disk_images}) to use with
1047this drive. If the filename contains comma, you must double it
1048(for instance, "file=my,,file" to use file "my,file").
1049
1050Special files such as iSCSI devices can be specified using protocol
1051specific URLs. See the section for "Device URL Syntax" for more information.
1052@item if=@var{interface}
1053This option defines on which type on interface the drive is connected.
ed1fcd00 1054Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
10adb8be
MA
1055@item bus=@var{bus},unit=@var{unit}
1056These options define where is connected the drive by defining the bus number and
1057the unit id.
1058@item index=@var{index}
1059This option defines where is connected the drive by using an index in the list
1060of available connectors of a given interface type.
1061@item media=@var{media}
1062This option defines the type of the media: disk or cdrom.
10adb8be 1063@item snapshot=@var{snapshot}
9d85d557
MT
1064@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
1065(see @option{-snapshot}).
10adb8be 1066@item cache=@var{cache}
dfaca464
KW
1067@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
1068and controls how the host cache is used to access block data. This is a
1069shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
1070options (as in @option{-blockdev}), and additionally @option{cache.writeback},
1071which provides a default for the @option{write-cache} option of block guest
1072devices (as in @option{-device}). The modes correspond to the following
1073settings:
1074
1075@c Our texi2pod.pl script doesn't support @multitable, so fall back to using
1076@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
1077@c and the HTML output.
1078@example
1079@ │ cache.writeback cache.direct cache.no-flush
1080─────────────┼─────────────────────────────────────────────────
1081writeback │ on off off
1082none │ on on off
1083writethrough │ off off off
1084directsync │ off on off
1085unsafe │ on off on
1086@end example
1087
1088The default mode is @option{cache=writeback}.
1089
10adb8be
MA
1090@item aio=@var{aio}
1091@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
1092@item format=@var{format}
1093Specify which disk @var{format} will be used rather than detecting
d33c8a7d 1094the format. Can be used to specify format=raw to avoid interpreting
10adb8be 1095an untrusted format header.
10adb8be
MA
1096@item werror=@var{action},rerror=@var{action}
1097Specify which @var{action} to take on write and read errors. Valid actions are:
1098"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
1099"report" (report the error to the guest), "enospc" (pause QEMU only if the
1100host disk is full; report the error to the guest otherwise).
1101The default setting is @option{werror=enospc} and @option{rerror=report}.
10adb8be
MA
1102@item copy-on-read=@var{copy-on-read}
1103@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
1104file sectors into the image file.
01f9cfab
SH
1105@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
1106Specify bandwidth throttling limits in bytes per second, either for all request
1107types or for reads or writes only. Small values can lead to timeouts or hangs
1108inside the guest. A safe minimum for disks is 2 MB/s.
1109@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
1110Specify bursts in bytes per second, either for all request types or for reads
1111or writes only. Bursts allow the guest I/O to spike above the limit
1112temporarily.
1113@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
1114Specify request rate limits in requests per second, either for all request
1115types or for reads or writes only.
1116@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
1117Specify bursts in requests per second, either for all request types or for reads
1118or writes only. Bursts allow the guest I/O to spike above the limit
1119temporarily.
1120@item iops_size=@var{is}
1121Let every @var{is} bytes of a request count as a new request for iops
1122throttling purposes. Use this option to prevent guests from circumventing iops
1123limits by sending fewer but larger requests.
1124@item group=@var{g}
1125Join a throttling quota group with given name @var{g}. All drives that are
1126members of the same group are accounted for together. Use this option to
1127prevent guests from circumventing throttling limits by using many small disks
1128instead of a single larger disk.
10adb8be
MA
1129@end table
1130
dfaca464 1131By default, the @option{cache.writeback=on} mode is used. It will report data
10adb8be
MA
1132writes as completed as soon as the data is present in the host page cache.
1133This is safe as long as your guest OS makes sure to correctly flush disk caches
1134where needed. If your guest OS does not handle volatile disk write caches
1135correctly and your host crashes or loses power, then the guest may experience
1136data corruption.
1137
dfaca464 1138For such guests, you should consider using @option{cache.writeback=off}. This
10adb8be
MA
1139means that the host page cache will be used to read and write data, but write
1140notification will be sent to the guest only after QEMU has made sure to flush
1141each write to the disk. Be aware that this has a major impact on performance.
1142
dfaca464 1143When using the @option{-snapshot} option, unsafe caching is always used.
10adb8be
MA
1144
1145Copy-on-read avoids accessing the same backing file sectors repeatedly and is
1146useful when the backing file is over a slow network. By default copy-on-read
1147is off.
1148
1149Instead of @option{-cdrom} you can use:
1150@example
1151qemu-system-i386 -drive file=file,index=2,media=cdrom
1152@end example
1153
1154Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
1155use:
1156@example
1157qemu-system-i386 -drive file=file,index=0,media=disk
1158qemu-system-i386 -drive file=file,index=1,media=disk
1159qemu-system-i386 -drive file=file,index=2,media=disk
1160qemu-system-i386 -drive file=file,index=3,media=disk
1161@end example
1162
1163You can open an image using pre-opened file descriptors from an fd set:
1164@example
1165qemu-system-i386
1166-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
1167-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
1168-drive file=/dev/fdset/2,index=0,media=disk
1169@end example
1170
1171You can connect a CDROM to the slave of ide0:
1172@example
1173qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
5824d651
BS
1174@end example
1175
10adb8be
MA
1176If you don't specify the "file=" argument, you define an empty drive:
1177@example
1178qemu-system-i386 -drive if=ide,index=1,media=cdrom
1179@end example
5824d651 1180
10adb8be
MA
1181Instead of @option{-fda}, @option{-fdb}, you can use:
1182@example
1183qemu-system-i386 -drive file=file,index=0,if=floppy
1184qemu-system-i386 -drive file=file,index=1,if=floppy
1185@end example
b1746ddd 1186
10adb8be
MA
1187By default, @var{interface} is "ide" and @var{index} is automatically
1188incremented:
1189@example
1190qemu-system-i386 -drive file=a -drive file=b"
1191@end example
1192is interpreted like:
1193@example
1194qemu-system-i386 -hda a -hdb b
1195@end example
84644c45
MA
1196ETEXI
1197
10adb8be
MA
1198DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
1199 "-mtdblock file use 'file' as on-board Flash memory image\n",
84644c45
MA
1200 QEMU_ARCH_ALL)
1201STEXI
10adb8be
MA
1202@item -mtdblock @var{file}
1203@findex -mtdblock
1204Use @var{file} as on-board Flash memory image.
84644c45
MA
1205ETEXI
1206
10adb8be
MA
1207DEF("sd", HAS_ARG, QEMU_OPTION_sd,
1208 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
5824d651 1209STEXI
10adb8be
MA
1210@item -sd @var{file}
1211@findex -sd
1212Use @var{file} as SecureDigital card image.
5824d651
BS
1213ETEXI
1214
10adb8be
MA
1215DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
1216 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
5824d651 1217STEXI
10adb8be
MA
1218@item -pflash @var{file}
1219@findex -pflash
1220Use @var{file} as a parallel flash image.
c70a01e4 1221ETEXI
5824d651 1222
10adb8be
MA
1223DEF("snapshot", 0, QEMU_OPTION_snapshot,
1224 "-snapshot write to temporary files instead of disk image files\n",
c70a01e4
MA
1225 QEMU_ARCH_ALL)
1226STEXI
10adb8be
MA
1227@item -snapshot
1228@findex -snapshot
1229Write to temporary files instead of disk image files. In this case,
1230the raw disk image you use is not written back. You can however force
1231the write back by pressing @key{C-a s} (@pxref{disk_images}).
5824d651
BS
1232ETEXI
1233
74db920c 1234DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
2c30dd74 1235 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
b96feb2c 1236 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
b8bbdb88
PJ
1237 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1238 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1239 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1240 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1241 " [[,throttling.iops-size=is]]\n",
74db920c
GS
1242 QEMU_ARCH_ALL)
1243
1244STEXI
1245
b96feb2c 1246@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}][,fmode=@var{fmode}][,dmode=@var{dmode}]
74db920c 1247@findex -fsdev
7c92a3d2
AK
1248Define a new file system device. Valid options are:
1249@table @option
1250@item @var{fsdriver}
1251This option specifies the fs driver backend to use.
93aee84f 1252Currently "local" and "proxy" file system drivers are supported.
7c92a3d2
AK
1253@item id=@var{id}
1254Specifies identifier for this device
1255@item path=@var{path}
1256Specifies the export path for the file system device. Files under
1257this path will be available to the 9p client on the guest.
1258@item security_model=@var{security_model}
1259Specifies the security model to be used for this export path.
2c30dd74 1260Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
7c92a3d2 1261In "passthrough" security model, files are stored using the same
b65ee4fa 1262credentials as they are created on the guest. This requires QEMU
2c30dd74 1263to run as root. In "mapped-xattr" security model, some of the file
7c92a3d2 1264attributes like uid, gid, mode bits and link target are stored as
2c30dd74
AK
1265file attributes. For "mapped-file" these attributes are stored in the
1266hidden .virtfs_metadata directory. Directories exported by this security model cannot
7c92a3d2
AK
1267interact with other unix tools. "none" security model is same as
1268passthrough except the sever won't report failures if it fails to
d9b36a6e 1269set file attributes like ownership. Security model is mandatory
93aee84f 1270only for local fsdriver. Other fsdrivers (like proxy) don't take
d9b36a6e 1271security model as a parameter.
7c92a3d2
AK
1272@item writeout=@var{writeout}
1273This is an optional argument. The only supported value is "immediate".
1274This means that host page cache will be used to read and write data but
1275write notification will be sent to the guest only when the data has been
1276reported as written by the storage subsystem.
2c74c2cb
MK
1277@item readonly
1278Enables exporting 9p share as a readonly mount for guests. By default
1279read-write access is given.
84a87cc4
MK
1280@item socket=@var{socket}
1281Enables proxy filesystem driver to use passed socket file for communicating
1282with virtfs-proxy-helper
f67e3ffd
MK
1283@item sock_fd=@var{sock_fd}
1284Enables proxy filesystem driver to use passed socket descriptor for
1285communicating with virtfs-proxy-helper. Usually a helper like libvirt
1286will create socketpair and pass one of the fds as sock_fd
b96feb2c
TS
1287@item fmode=@var{fmode}
1288Specifies the default mode for newly created files on the host. Works only
1289with security models "mapped-xattr" and "mapped-file".
1290@item dmode=@var{dmode}
1291Specifies the default mode for newly created directories on the host. Works
1292only with security models "mapped-xattr" and "mapped-file".
7c92a3d2 1293@end table
9ce56db6 1294
7c92a3d2
AK
1295-fsdev option is used along with -device driver "virtio-9p-pci".
1296@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1297Options for virtio-9p-pci driver are:
1298@table @option
1299@item fsdev=@var{id}
1300Specifies the id value specified along with -fsdev option
1301@item mount_tag=@var{mount_tag}
1302Specifies the tag name to be used by the guest to mount this export point
74db920c 1303@end table
7c92a3d2 1304
74db920c 1305ETEXI
74db920c 1306
3d54abc7 1307DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
2c30dd74 1308 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
b96feb2c 1309 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
3d54abc7
GS
1310 QEMU_ARCH_ALL)
1311
1312STEXI
1313
b96feb2c 1314@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}][,fmode=@var{fmode}][,dmode=@var{dmode}]
3d54abc7 1315@findex -virtfs
3d54abc7 1316
7c92a3d2
AK
1317The general form of a Virtual File system pass-through options are:
1318@table @option
1319@item @var{fsdriver}
1320This option specifies the fs driver backend to use.
93aee84f 1321Currently "local" and "proxy" file system drivers are supported.
7c92a3d2
AK
1322@item id=@var{id}
1323Specifies identifier for this device
1324@item path=@var{path}
1325Specifies the export path for the file system device. Files under
1326this path will be available to the 9p client on the guest.
1327@item security_model=@var{security_model}
1328Specifies the security model to be used for this export path.
2c30dd74 1329Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
7c92a3d2 1330In "passthrough" security model, files are stored using the same
b65ee4fa 1331credentials as they are created on the guest. This requires QEMU
2c30dd74 1332to run as root. In "mapped-xattr" security model, some of the file
7c92a3d2 1333attributes like uid, gid, mode bits and link target are stored as
2c30dd74
AK
1334file attributes. For "mapped-file" these attributes are stored in the
1335hidden .virtfs_metadata directory. Directories exported by this security model cannot
7c92a3d2
AK
1336interact with other unix tools. "none" security model is same as
1337passthrough except the sever won't report failures if it fails to
d9b36a6e 1338set file attributes like ownership. Security model is mandatory only
93aee84f 1339for local fsdriver. Other fsdrivers (like proxy) don't take security
d9b36a6e 1340model as a parameter.
7c92a3d2
AK
1341@item writeout=@var{writeout}
1342This is an optional argument. The only supported value is "immediate".
1343This means that host page cache will be used to read and write data but
1344write notification will be sent to the guest only when the data has been
1345reported as written by the storage subsystem.
2c74c2cb
MK
1346@item readonly
1347Enables exporting 9p share as a readonly mount for guests. By default
1348read-write access is given.
84a87cc4
MK
1349@item socket=@var{socket}
1350Enables proxy filesystem driver to use passed socket file for
1351communicating with virtfs-proxy-helper. Usually a helper like libvirt
1352will create socketpair and pass one of the fds as sock_fd
f67e3ffd
MK
1353@item sock_fd
1354Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1355descriptor for interfacing with virtfs-proxy-helper
b96feb2c
TS
1356@item fmode=@var{fmode}
1357Specifies the default mode for newly created files on the host. Works only
1358with security models "mapped-xattr" and "mapped-file".
1359@item dmode=@var{dmode}
1360Specifies the default mode for newly created directories on the host. Works
1361only with security models "mapped-xattr" and "mapped-file".
3d54abc7
GS
1362@end table
1363ETEXI
3d54abc7 1364
9db221ae
AK
1365DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1366 "-virtfs_synth Create synthetic file system image\n",
1367 QEMU_ARCH_ALL)
1368STEXI
1369@item -virtfs_synth
1370@findex -virtfs_synth
1371Create synthetic file system image
1372ETEXI
1373
61d70487
MA
1374DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1375 "-iscsi [user=user][,password=password]\n"
1376 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1377 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1378 " [,timeout=timeout]\n"
1379 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1380
44743148
MA
1381STEXI
1382@item -iscsi
1383@findex -iscsi
1384Configure iSCSI session parameters.
1385ETEXI
1386
5824d651
BS
1387STEXI
1388@end table
1389ETEXI
5824d651
BS
1390DEFHEADING()
1391
de6b4f90 1392DEFHEADING(USB options:)
10adb8be
MA
1393STEXI
1394@table @option
1395ETEXI
1396
1397DEF("usb", 0, QEMU_OPTION_usb,
a358a3af 1398 "-usb enable the USB driver (if it is not used by default yet)\n",
10adb8be
MA
1399 QEMU_ARCH_ALL)
1400STEXI
1401@item -usb
1402@findex -usb
a358a3af 1403Enable the USB driver (if it is not used by default yet).
10adb8be
MA
1404ETEXI
1405
1406DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1407 "-usbdevice name add the host or guest USB device 'name'\n",
1408 QEMU_ARCH_ALL)
1409STEXI
1410
1411@item -usbdevice @var{devname}
1412@findex -usbdevice
a358a3af
TH
1413Add the USB device @var{devname}. Note that this option is deprecated,
1414please use @code{-device usb-...} instead. @xref{usb_devices}.
10adb8be
MA
1415
1416@table @option
1417
1418@item mouse
1419Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1420
1421@item tablet
1422Pointer device that uses absolute coordinates (like a touchscreen). This
1423means QEMU is able to report the mouse position without having to grab the
1424mouse. Also overrides the PS/2 mouse emulation when activated.
1425
10adb8be
MA
1426@item braille
1427Braille device. This will use BrlAPI to display the braille output on a real
1428or fake device.
1429
10adb8be
MA
1430@end table
1431ETEXI
1432
1433STEXI
1434@end table
1435ETEXI
1436DEFHEADING()
1437
de6b4f90 1438DEFHEADING(Display options:)
5824d651
BS
1439STEXI
1440@table @option
1441ETEXI
1442
1472a95b 1443DEF("display", HAS_ARG, QEMU_OPTION_display,
d8aec9d9 1444 "-display spice-app[,gl=on|off]\n"
1472a95b 1445 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
4867e47c 1446 " [,window_close=on|off][,gl=on|core|es|off]\n"
f04ec5af
RH
1447 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1448 "-display vnc=<display>[,<optargs>]\n"
2f8b7cd5 1449 "-display curses[,charset=<encoding>]\n"
144aaa99
ES
1450 "-display none\n"
1451 "-display egl-headless[,rendernode=<file>]"
f04ec5af
RH
1452 " select display type\n"
1453 "The default display is equivalent to\n"
1454#if defined(CONFIG_GTK)
1455 "\t\"-display gtk\"\n"
1456#elif defined(CONFIG_SDL)
1457 "\t\"-display sdl\"\n"
1458#elif defined(CONFIG_COCOA)
1459 "\t\"-display cocoa\"\n"
1460#elif defined(CONFIG_VNC)
1461 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1462#else
1463 "\t\"-display none\"\n"
1464#endif
1465 , QEMU_ARCH_ALL)
1472a95b
JS
1466STEXI
1467@item -display @var{type}
1468@findex -display
1469Select type of display to use. This option is a replacement for the
1470old style -sdl/-curses/... options. Valid values for @var{type} are
1471@table @option
1472@item sdl
1473Display video output via SDL (usually in a separate graphics
1474window; see the SDL documentation for other possibilities).
1475@item curses
1476Display video output via curses. For graphics device models which
1477support a text mode, QEMU can display this output using a
1478curses/ncurses interface. Nothing is displayed when the graphics
1479device is in graphical mode or if the graphics device does not support
1480a text mode. Generally only the VGA device models support text mode.
2f8b7cd5
ST
1481The font charset used by the guest can be specified with the
1482@code{charset} option, for example @code{charset=CP850} for IBM CP850
1483encoding. The default is @code{CP437}.
4171d32e
JS
1484@item none
1485Do not display video output. The guest will still see an emulated
1486graphics card, but its output will not be displayed to the QEMU
1487user. This option differs from the -nographic option in that it
1488only affects what is done with video output; -nographic also changes
1489the destination of the serial and parallel port data.
881249c7
JK
1490@item gtk
1491Display video output in a GTK window. This interface provides drop-down
1492menus and other UI elements to configure and control the VM during
1493runtime.
3264ff12
JS
1494@item vnc
1495Start a VNC server on display <arg>
144aaa99
ES
1496@item egl-headless
1497Offload all OpenGL operations to a local DRI device. For any graphical display,
1498this display needs to be paired with either VNC or SPICE displays.
d8aec9d9
MAL
1499@item spice-app
1500Start QEMU as a Spice server and launch the default Spice client
1501application. The Spice server will redirect the serial consoles and
1502QEMU monitors. (Since 4.0)
1472a95b
JS
1503@end table
1504ETEXI
1505
5824d651 1506DEF("nographic", 0, QEMU_OPTION_nographic,
ad96090a
BS
1507 "-nographic disable graphical output and redirect serial I/Os to console\n",
1508 QEMU_ARCH_ALL)
5824d651
BS
1509STEXI
1510@item -nographic
6616b2ad 1511@findex -nographic
dc0a3e44
CL
1512Normally, if QEMU is compiled with graphical window support, it displays
1513output such as guest graphics, guest console, and the QEMU monitor in a
1514window. With this option, you can totally disable graphical output so
1515that QEMU is a simple command line application. The emulated serial port
1516is redirected on the console and muxed with the monitor (unless
1517redirected elsewhere explicitly). Therefore, you can still use QEMU to
1518debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1519switching between the console and monitor.
5824d651
BS
1520ETEXI
1521
5824d651 1522DEF("curses", 0, QEMU_OPTION_curses,
f04ec5af 1523 "-curses shorthand for -display curses\n",
ad96090a 1524 QEMU_ARCH_ALL)
5824d651
BS
1525STEXI
1526@item -curses
b8f490eb 1527@findex -curses
dc0a3e44
CL
1528Normally, if QEMU is compiled with graphical window support, it displays
1529output such as guest graphics, guest console, and the QEMU monitor in a
1530window. With this option, QEMU can display the VGA output when in text
1531mode using a curses/ncurses interface. Nothing is displayed in graphical
1532mode.
5824d651
BS
1533ETEXI
1534
5824d651 1535DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
ad96090a
BS
1536 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1537 QEMU_ARCH_ALL)
5824d651
BS
1538STEXI
1539@item -alt-grab
6616b2ad 1540@findex -alt-grab
de1db2a1
BH
1541Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1542affects the special keys (for fullscreen, monitor-mode switching, etc).
5824d651
BS
1543ETEXI
1544
0ca9f8a4 1545DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
ad96090a
BS
1546 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1547 QEMU_ARCH_ALL)
0ca9f8a4
DK
1548STEXI
1549@item -ctrl-grab
6616b2ad 1550@findex -ctrl-grab
de1db2a1
BH
1551Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1552affects the special keys (for fullscreen, monitor-mode switching, etc).
0ca9f8a4
DK
1553ETEXI
1554
5824d651 1555DEF("no-quit", 0, QEMU_OPTION_no_quit,
ad96090a 1556 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
5824d651
BS
1557STEXI
1558@item -no-quit
6616b2ad 1559@findex -no-quit
5824d651
BS
1560Disable SDL window close capability.
1561ETEXI
1562
5824d651 1563DEF("sdl", 0, QEMU_OPTION_sdl,
f04ec5af 1564 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
5824d651
BS
1565STEXI
1566@item -sdl
6616b2ad 1567@findex -sdl
5824d651
BS
1568Enable SDL.
1569ETEXI
1570
29b0040b 1571DEF("spice", HAS_ARG, QEMU_OPTION_spice,
27af7788
YH
1572 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1573 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1574 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
fe4831b1 1575 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
27af7788
YH
1576 " [,tls-ciphers=<list>]\n"
1577 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1578 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1579 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1580 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1581 " [,jpeg-wan-compression=[auto|never|always]]\n"
1582 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1583 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
5ad24e5f
HG
1584 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1585 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
7b525508 1586 " [,gl=[on|off]][,rendernode=<file>]\n"
27af7788
YH
1587 " enable spice\n"
1588 " at least one of {port, tls-port} is mandatory\n",
1589 QEMU_ARCH_ALL)
29b0040b
GH
1590STEXI
1591@item -spice @var{option}[,@var{option}[,...]]
1592@findex -spice
1593Enable the spice remote desktop protocol. Valid options are
1594
1595@table @option
1596
1597@item port=<nr>
c448e855 1598Set the TCP port spice is listening on for plaintext channels.
29b0040b 1599
333b0eeb
GH
1600@item addr=<addr>
1601Set the IP address spice is listening on. Default is any address.
1602
1603@item ipv4
f9cfd655
MA
1604@itemx ipv6
1605@itemx unix
333b0eeb
GH
1606Force using the specified IP version.
1607
29b0040b
GH
1608@item password=<secret>
1609Set the password you need to authenticate.
1610
48b3ed0a
MAL
1611@item sasl
1612Require that the client use SASL to authenticate with the spice.
1613The exact choice of authentication method used is controlled from the
1614system / user's SASL configuration file for the 'qemu' service. This
1615is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1616unprivileged user, an environment variable SASL_CONF_PATH can be used
1617to make it search alternate locations for the service config.
1618While some SASL auth methods can also provide data encryption (eg GSSAPI),
1619it is recommended that SASL always be combined with the 'tls' and
1620'x509' settings to enable use of SSL and server certificates. This
1621ensures a data encryption preventing compromise of authentication
1622credentials.
1623
29b0040b
GH
1624@item disable-ticketing
1625Allow client connects without authentication.
1626
d4970b07
HG
1627@item disable-copy-paste
1628Disable copy paste between the client and the guest.
1629
5ad24e5f
HG
1630@item disable-agent-file-xfer
1631Disable spice-vdagent based file-xfer between the client and the guest.
1632
c448e855
GH
1633@item tls-port=<nr>
1634Set the TCP port spice is listening on for encrypted channels.
1635
1636@item x509-dir=<dir>
1637Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1638
1639@item x509-key-file=<file>
f9cfd655
MA
1640@itemx x509-key-password=<file>
1641@itemx x509-cert-file=<file>
1642@itemx x509-cacert-file=<file>
1643@itemx x509-dh-key-file=<file>
c448e855
GH
1644The x509 file names can also be configured individually.
1645
1646@item tls-ciphers=<list>
1647Specify which ciphers to use.
1648
d70d6b31 1649@item tls-channel=[main|display|cursor|inputs|record|playback]
f9cfd655 1650@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
17b6dea0
GH
1651Force specific channel to be used with or without TLS encryption. The
1652options can be specified multiple times to configure multiple
1653channels. The special name "default" can be used to set the default
1654mode. For channels which are not explicitly forced into one mode the
1655spice client is allowed to pick tls/plaintext as he pleases.
1656
9f04e09e
YH
1657@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1658Configure image compression (lossless).
1659Default is auto_glz.
1660
1661@item jpeg-wan-compression=[auto|never|always]
f9cfd655 1662@itemx zlib-glz-wan-compression=[auto|never|always]
9f04e09e
YH
1663Configure wan image compression (lossy for slow links).
1664Default is auto.
1665
84a23f25 1666@item streaming-video=[off|all|filter]
93ca519e 1667Configure video stream detection. Default is off.
84a23f25
GH
1668
1669@item agent-mouse=[on|off]
1670Enable/disable passing mouse events via vdagent. Default is on.
1671
1672@item playback-compression=[on|off]
1673Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1674
8c957053
YH
1675@item seamless-migration=[on|off]
1676Enable/disable spice seamless migration. Default is off.
1677
474114b7
GH
1678@item gl=[on|off]
1679Enable/disable OpenGL context. Default is off.
1680
7b525508
MAL
1681@item rendernode=<file>
1682DRM render node for OpenGL rendering. If not specified, it will pick
1683the first available. (Since 2.9)
1684
29b0040b
GH
1685@end table
1686ETEXI
1687
5824d651 1688DEF("portrait", 0, QEMU_OPTION_portrait,
ad96090a
BS
1689 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1690 QEMU_ARCH_ALL)
5824d651
BS
1691STEXI
1692@item -portrait
6616b2ad 1693@findex -portrait
5824d651
BS
1694Rotate graphical output 90 deg left (only PXA LCD).
1695ETEXI
1696
9312805d
VK
1697DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1698 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1699 QEMU_ARCH_ALL)
1700STEXI
6265c43b 1701@item -rotate @var{deg}
9312805d
VK
1702@findex -rotate
1703Rotate graphical output some deg left (only PXA LCD).
1704ETEXI
1705
5824d651 1706DEF("vga", HAS_ARG, QEMU_OPTION_vga,
a94f0c5c 1707 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
ad96090a 1708 " select video card type\n", QEMU_ARCH_ALL)
5824d651 1709STEXI
e4558dca 1710@item -vga @var{type}
6616b2ad 1711@findex -vga
5824d651 1712Select type of VGA card to emulate. Valid values for @var{type} are
b3f046c2 1713@table @option
5824d651
BS
1714@item cirrus
1715Cirrus Logic GD5446 Video card. All Windows versions starting from
1716Windows 95 should recognize and use this graphic card. For optimal
1717performances, use 16 bit color depth in the guest and the host OS.
41eeb0e6 1718(This card was the default before QEMU 2.2)
5824d651
BS
1719@item std
1720Standard VGA card with Bochs VBE extensions. If your guest OS
1721supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1722to use high resolution modes (>= 1280x1024x16) then you should use
41eeb0e6 1723this option. (This card is the default since QEMU 2.2)
5824d651
BS
1724@item vmware
1725VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1726recent XFree86/XOrg server or Windows guest with a driver for this
1727card.
a19cbfb3
GH
1728@item qxl
1729QXL paravirtual graphic card. It is VGA compatible (including VESA
17302.0 VBE support). Works best with qxl guest drivers installed though.
1731Recommended choice when using the spice protocol.
33632788
MCA
1732@item tcx
1733(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1734sun4m machines and offers both 8-bit and 24-bit colour depths at a
1735fixed resolution of 1024x768.
1736@item cg3
1737(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1738for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1739resolutions aimed at people wishing to run older Solaris versions.
a94f0c5c
GH
1740@item virtio
1741Virtio VGA card.
5824d651
BS
1742@item none
1743Disable VGA card.
1744@end table
1745ETEXI
1746
1747DEF("full-screen", 0, QEMU_OPTION_full_screen,
ad96090a 1748 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
5824d651
BS
1749STEXI
1750@item -full-screen
6616b2ad 1751@findex -full-screen
5824d651
BS
1752Start in full screen.
1753ETEXI
1754
5824d651 1755DEF("g", 1, QEMU_OPTION_g ,
ad96090a
BS
1756 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1757 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
5824d651 1758STEXI
95d5f08b 1759@item -g @var{width}x@var{height}[x@var{depth}]
6616b2ad 1760@findex -g
95d5f08b 1761Set the initial graphical resolution and depth (PPC, SPARC only).
5824d651
BS
1762ETEXI
1763
1764DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
f04ec5af 1765 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
5824d651
BS
1766STEXI
1767@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
6616b2ad 1768@findex -vnc
dc0a3e44
CL
1769Normally, if QEMU is compiled with graphical window support, it displays
1770output such as guest graphics, guest console, and the QEMU monitor in a
1771window. With this option, you can have QEMU listen on VNC display
1772@var{display} and redirect the VGA display over the VNC session. It is
1773very useful to enable the usb tablet device when using this option
a358a3af 1774(option @option{-device usb-tablet}). When using the VNC display, you
dc0a3e44
CL
1775must use the @option{-k} parameter to set the keyboard layout if you are
1776not using en-us. Valid syntax for the @var{display} is
5824d651 1777
b3f046c2 1778@table @option
5824d651 1779
99a9a52a
RH
1780@item to=@var{L}
1781
1782With this option, QEMU will try next available VNC @var{display}s, until the
1783number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1784available, e.g. port 5900+@var{display} is already used by another
1785application. By default, to=0.
1786
5824d651
BS
1787@item @var{host}:@var{d}
1788
1789TCP connections will only be allowed from @var{host} on display @var{d}.
1790By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1791be omitted in which case the server will accept connections from any host.
1792
4e257e5e 1793@item unix:@var{path}
5824d651
BS
1794
1795Connections will be allowed over UNIX domain sockets where @var{path} is the
1796location of a unix socket to listen for connections on.
1797
1798@item none
1799
1800VNC is initialized but not started. The monitor @code{change} command
1801can be used to later start the VNC server.
1802
1803@end table
1804
1805Following the @var{display} value there may be one or more @var{option} flags
1806separated by commas. Valid options are
1807
b3f046c2 1808@table @option
5824d651
BS
1809
1810@item reverse
1811
1812Connect to a listening VNC client via a ``reverse'' connection. The
1813client is specified by the @var{display}. For reverse network
1814connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1815is a TCP port number, not a display number.
1816
7536ee4b
TH
1817@item websocket
1818
1819Opens an additional TCP listening port dedicated to VNC Websocket connections.
275e0d61
DB
1820If a bare @var{websocket} option is given, the Websocket port is
18215700+@var{display}. An alternative port can be specified with the
1822syntax @code{websocket}=@var{port}.
1823
1824If @var{host} is specified connections will only be allowed from this host.
1825It is possible to control the websocket listen address independently, using
1826the syntax @code{websocket}=@var{host}:@var{port}.
1827
3e305e4a
DB
1828If no TLS credentials are provided, the websocket connection runs in
1829unencrypted mode. If TLS credentials are provided, the websocket connection
1830requires encrypted client connections.
7536ee4b 1831
5824d651
BS
1832@item password
1833
1834Require that password based authentication is used for client connections.
86ee5bc3
MN
1835
1836The password must be set separately using the @code{set_password} command in
1837the @ref{pcsys_monitor}. The syntax to change your password is:
1838@code{set_password <protocol> <password>} where <protocol> could be either
1839"vnc" or "spice".
1840
1841If you would like to change <protocol> password expiration, you should use
1842@code{expire_password <protocol> <expiration-time>} where expiration time could
1843be one of the following options: now, never, +seconds or UNIX time of
1844expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1845to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1846date and time).
1847
1848You can also use keywords "now" or "never" for the expiration time to
1849allow <protocol> password to expire immediately or never expire.
5824d651 1850
3e305e4a
DB
1851@item tls-creds=@var{ID}
1852
1853Provides the ID of a set of TLS credentials to use to secure the
1854VNC server. They will apply to both the normal VNC server socket
1855and the websocket socket (if enabled). Setting TLS credentials
1856will cause the VNC server socket to enable the VeNCrypt auth
1857mechanism. The credentials should have been previously created
1858using the @option{-object tls-creds} argument.
1859
55cf09a0
DB
1860@item tls-authz=@var{ID}
1861
1862Provides the ID of the QAuthZ authorization object against which
1863the client's x509 distinguished name will validated. This object is
1864only resolved at time of use, so can be deleted and recreated on the
1865fly while the VNC server is active. If missing, it will default
1866to denying access.
1867
5824d651
BS
1868@item sasl
1869
1870Require that the client use SASL to authenticate with the VNC server.
1871The exact choice of authentication method used is controlled from the
1872system / user's SASL configuration file for the 'qemu' service. This
1873is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1874unprivileged user, an environment variable SASL_CONF_PATH can be used
1875to make it search alternate locations for the service config.
1876While some SASL auth methods can also provide data encryption (eg GSSAPI),
1877it is recommended that SASL always be combined with the 'tls' and
1878'x509' settings to enable use of SSL and server certificates. This
1879ensures a data encryption preventing compromise of authentication
1880credentials. See the @ref{vnc_security} section for details on using
1881SASL authentication.
1882
55cf09a0
DB
1883@item sasl-authz=@var{ID}
1884
1885Provides the ID of the QAuthZ authorization object against which
1886the client's SASL username will validated. This object is
1887only resolved at time of use, so can be deleted and recreated on the
1888fly while the VNC server is active. If missing, it will default
1889to denying access.
1890
5824d651
BS
1891@item acl
1892
55cf09a0
DB
1893Legacy method for enabling authorization of clients against the
1894x509 distinguished name and SASL username. It results in the creation
1895of two @code{authz-list} objects with IDs of @code{vnc.username} and
1896@code{vnc.x509dname}. The rules for these objects must be configured
1897with the HMP ACL commands.
1898
1899This option is deprecated and should no longer be used. The new
1900@option{sasl-authz} and @option{tls-authz} options are a
1901replacement.
5824d651 1902
6f9c78c1
CC
1903@item lossy
1904
1905Enable lossy compression methods (gradient, JPEG, ...). If this
1906option is set, VNC client may receive lossy framebuffer updates
1907depending on its encoding settings. Enabling this option can save
1908a lot of bandwidth at the expense of quality.
1909
80e0c8c3
CC
1910@item non-adaptive
1911
1912Disable adaptive encodings. Adaptive encodings are enabled by default.
1913An adaptive encoding will try to detect frequently updated screen regions,
1914and send updates in these regions using a lossy encoding (like JPEG).
61cc8701 1915This can be really helpful to save bandwidth when playing videos. Disabling
9d85d557 1916adaptive encodings restores the original static behavior of encodings
80e0c8c3
CC
1917like Tight.
1918
8cf36489
GH
1919@item share=[allow-exclusive|force-shared|ignore]
1920
1921Set display sharing policy. 'allow-exclusive' allows clients to ask
1922for exclusive access. As suggested by the rfb spec this is
1923implemented by dropping other connections. Connecting multiple
1924clients in parallel requires all clients asking for a shared session
1925(vncviewer: -shared switch). This is the default. 'force-shared'
1926disables exclusive client access. Useful for shared desktop sessions,
1927where you don't want someone forgetting specify -shared disconnect
1928everybody else. 'ignore' completely ignores the shared flag and
1929allows everybody connect unconditionally. Doesn't conform to the rfb
b65ee4fa 1930spec but is traditional QEMU behavior.
8cf36489 1931
c5ce8333
GH
1932@item key-delay-ms
1933
1934Set keyboard delay, for key down and key up events, in milliseconds.
d3b0db6d 1935Default is 10. Keyboards are low-bandwidth devices, so this slowdown
c5ce8333
GH
1936can help the device and guest to keep up and not lose events in case
1937events are arriving in bulk. Possible causes for the latter are flaky
1938network connections, or scripts for automated testing.
1939
5824d651
BS
1940@end table
1941ETEXI
1942
1943STEXI
1944@end table
1945ETEXI
a3adb7ad 1946ARCHHEADING(, QEMU_ARCH_I386)
5824d651 1947
de6b4f90 1948ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
5824d651
BS
1949STEXI
1950@table @option
1951ETEXI
1952
5824d651 1953DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
ad96090a
BS
1954 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1955 QEMU_ARCH_I386)
5824d651
BS
1956STEXI
1957@item -win2k-hack
6616b2ad 1958@findex -win2k-hack
5824d651
BS
1959Use it when installing Windows 2000 to avoid a disk full bug. After
1960Windows 2000 is installed, you no longer need this option (this option
1961slows down the IDE transfers).
1962ETEXI
1963
5824d651 1964DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
ad96090a
BS
1965 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1966 QEMU_ARCH_I386)
5824d651
BS
1967STEXI
1968@item -no-fd-bootchk
6616b2ad 1969@findex -no-fd-bootchk
4eda32f5 1970Disable boot signature checking for floppy disks in BIOS. May
5824d651
BS
1971be needed to boot from old floppy disks.
1972ETEXI
1973
5824d651 1974DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
f5d8c8cd 1975 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
5824d651
BS
1976STEXI
1977@item -no-acpi
6616b2ad 1978@findex -no-acpi
5824d651
BS
1979Disable ACPI (Advanced Configuration and Power Interface) support. Use
1980it if your guest OS complains about ACPI problems (PC target machine
1981only).
1982ETEXI
1983
5824d651 1984DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
ad96090a 1985 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
5824d651
BS
1986STEXI
1987@item -no-hpet
6616b2ad 1988@findex -no-hpet
5824d651
BS
1989Disable HPET support.
1990ETEXI
1991
5824d651 1992DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
104bf02e 1993 "-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 1994 " ACPI table description\n", QEMU_ARCH_I386)
5824d651
BS
1995STEXI
1996@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 1997@findex -acpitable
5824d651 1998Add ACPI table with specified header fields and context from specified files.
104bf02e
MT
1999For file=, take whole ACPI table from the specified files, including all
2000ACPI headers (possible overridden by other options).
2001For data=, only data
2002portion of the table is used, all header information is specified in the
2003command line.
ae123749
LE
2004If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
2005fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
2006to ensure the field matches required by the Microsoft SLIC spec and the ACPI
2007spec.
5824d651
BS
2008ETEXI
2009
b6f6e3d3
AL
2010DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2011 "-smbios file=binary\n"
ca1a8a06 2012 " load SMBIOS entry from binary file\n"
b155eb1d
GS
2013 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2014 " [,uefi=on|off]\n"
ca1a8a06 2015 " specify SMBIOS type 0 fields\n"
b6f6e3d3
AL
2016 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2017 " [,uuid=uuid][,sku=str][,family=str]\n"
b155eb1d
GS
2018 " specify SMBIOS type 1 fields\n"
2019 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2020 " [,asset=str][,location=str]\n"
2021 " specify SMBIOS type 2 fields\n"
2022 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2023 " [,sku=str]\n"
2024 " specify SMBIOS type 3 fields\n"
2025 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2026 " [,asset=str][,part=str]\n"
2027 " specify SMBIOS type 4 fields\n"
2028 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
3ebd6cc8 2029 " [,asset=str][,part=str][,speed=%d]\n"
b155eb1d 2030 " specify SMBIOS type 17 fields\n",
c30e1565 2031 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
b6f6e3d3
AL
2032STEXI
2033@item -smbios file=@var{binary}
6616b2ad 2034@findex -smbios
b6f6e3d3
AL
2035Load SMBIOS entry from binary file.
2036
84351843 2037@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
b6f6e3d3
AL
2038Specify SMBIOS type 0 fields
2039
b155eb1d 2040@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 2041Specify SMBIOS type 1 fields
b155eb1d
GS
2042
2043@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}]
2044Specify SMBIOS type 2 fields
2045
2046@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
2047Specify SMBIOS type 3 fields
2048
2049@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
2050Specify SMBIOS type 4 fields
2051
3ebd6cc8 2052@item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}]
b155eb1d 2053Specify SMBIOS type 17 fields
b6f6e3d3
AL
2054ETEXI
2055
5824d651
BS
2056STEXI
2057@end table
2058ETEXI
c70a01e4 2059DEFHEADING()
5824d651 2060
de6b4f90 2061DEFHEADING(Network options:)
5824d651
BS
2062STEXI
2063@table @option
2064ETEXI
2065
6a8b4a5b 2066DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
5824d651 2067#ifdef CONFIG_SLIRP
0b11c036
ST
2068 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
2069 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2070 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
f18d1375 2071 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
0fca92b9 2072 " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
ad196a9d 2073#ifndef _WIN32
c92ef6a2 2074 "[,smb=dir[,smbserver=addr]]\n"
ad196a9d 2075#endif
6a8b4a5b
TH
2076 " configure a user mode network backend with ID 'str',\n"
2077 " its DHCP server and optional services\n"
5824d651
BS
2078#endif
2079#ifdef _WIN32
6a8b4a5b
TH
2080 "-netdev tap,id=str,ifname=name\n"
2081 " configure a host TAP network backend with ID 'str'\n"
5824d651 2082#else
6a8b4a5b 2083 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
584613ea 2084 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
6a8b4a5b 2085 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
69e87b32 2086 " [,poll-us=n]\n"
6a8b4a5b 2087 " configure a host TAP network backend with ID 'str'\n"
584613ea 2088 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
a7c36ee4
CB
2089 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2090 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2091 " to deconfigure it\n"
ca1a8a06 2092 " use '[down]script=no' to disable script execution\n"
a7c36ee4
CB
2093 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2094 " configure it\n"
5824d651 2095 " use 'fd=h' to connect to an already opened TAP interface\n"
2ca81baa 2096 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
ca1a8a06 2097 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
f157ed20 2098 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
ca1a8a06
BR
2099 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2100 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
82b0d80e 2101 " use vhost=on to enable experimental in kernel accelerator\n"
5430a28f
MT
2102 " (only has effect for virtio guests which use MSIX)\n"
2103 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
82b0d80e 2104 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
2ca81baa 2105 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
ec396014 2106 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
69e87b32
JW
2107 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
2108 " spent on busy polling for vhost net\n"
6a8b4a5b
TH
2109 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2110 " configure a host TAP network backend with ID 'str' that is\n"
2111 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2112 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
3fb69aa1
AI
2113#endif
2114#ifdef __linux__
6a8b4a5b
TH
2115 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2116 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
2117 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
2118 " [,rxcookie=rxcookie][,offset=offset]\n"
2119 " configure a network backend with ID 'str' connected to\n"
2120 " an Ethernet over L2TPv3 pseudowire.\n"
3fb69aa1 2121 " Linux kernel 3.3+ as well as most routers can talk\n"
2f47b403 2122 " L2TPv3. This transport allows connecting a VM to a VM,\n"
3fb69aa1
AI
2123 " VM to a router and even VM to Host. It is a nearly-universal\n"
2124 " standard (RFC3391). Note - this implementation uses static\n"
2125 " pre-configured tunnels (same as the Linux kernel).\n"
2126 " use 'src=' to specify source address\n"
2127 " use 'dst=' to specify destination address\n"
2128 " use 'udp=on' to specify udp encapsulation\n"
3952651a 2129 " use 'srcport=' to specify source udp port\n"
3fb69aa1
AI
2130 " use 'dstport=' to specify destination udp port\n"
2131 " use 'ipv6=on' to force v6\n"
2132 " L2TPv3 uses cookies to prevent misconfiguration as\n"
2133 " well as a weak security measure\n"
2134 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
2135 " use 'txcookie=0x012345678' to specify a txcookie\n"
2136 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2137 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2138 " use 'pincounter=on' to work around broken counter handling in peer\n"
2139 " use 'offset=X' to add an extra offset between header and data\n"
5824d651 2140#endif
6a8b4a5b
TH
2141 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2142 " configure a network backend to connect to another network\n"
2143 " using a socket connection\n"
2144 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2145 " configure a network backend to connect to a multicast maddr and port\n"
3a75e74c 2146 " use 'localaddr=addr' to specify the host address to send packets from\n"
6a8b4a5b
TH
2147 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2148 " configure a network backend to connect to another network\n"
2149 " using an UDP tunnel\n"
5824d651 2150#ifdef CONFIG_VDE
6a8b4a5b
TH
2151 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2152 " configure a network backend to connect to port 'n' of a vde switch\n"
2153 " running on host and listening for incoming connections on 'socketpath'.\n"
5824d651
BS
2154 " Use group 'groupname' and mode 'octalmode' to change default\n"
2155 " ownership and permissions for communication port.\n"
58952137
VM
2156#endif
2157#ifdef CONFIG_NETMAP
6a8b4a5b 2158 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
58952137
VM
2159 " attach to the existing netmap-enabled network interface 'name', or to a\n"
2160 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2161 " netmap device, defaults to '/dev/netmap')\n"
5824d651 2162#endif
253dc14c 2163#ifdef CONFIG_POSIX
6a8b4a5b
TH
2164 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2165 " configure a vhost-user network, backed by a chardev 'dev'\n"
253dc14c 2166#endif
18d65d22 2167 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
af1a5c3e 2168 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
78cd6f7b 2169DEF("nic", HAS_ARG, QEMU_OPTION_nic,
dfaa7d50 2170 "-nic [tap|bridge|"
78cd6f7b
TH
2171#ifdef CONFIG_SLIRP
2172 "user|"
2173#endif
2174#ifdef __linux__
2175 "l2tpv3|"
2176#endif
2177#ifdef CONFIG_VDE
2178 "vde|"
2179#endif
2180#ifdef CONFIG_NETMAP
2181 "netmap|"
2182#endif
2183#ifdef CONFIG_POSIX
2184 "vhost-user|"
2185#endif
2186 "socket][,option][,...][mac=macaddr]\n"
2187 " initialize an on-board / default host NIC (using MAC address\n"
2188 " macaddr) and connect it to the given host network backend\n"
dfaa7d50 2189 "-nic none use it alone to have zero network devices (the default is to\n"
78cd6f7b
TH
2190 " provided a 'user' network connection)\n",
2191 QEMU_ARCH_ALL)
6a8b4a5b 2192DEF("net", HAS_ARG, QEMU_OPTION_net,
af1a5c3e 2193 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
0e60a82d 2194 " configure or create an on-board (or machine default) NIC and\n"
af1a5c3e 2195 " connect it to hub 0 (please use -nic unless you need a hub)\n"
6a8b4a5b 2196 "-net ["
a1ea458f
MM
2197#ifdef CONFIG_SLIRP
2198 "user|"
2199#endif
2200 "tap|"
a7c36ee4 2201 "bridge|"
a1ea458f
MM
2202#ifdef CONFIG_VDE
2203 "vde|"
58952137
VM
2204#endif
2205#ifdef CONFIG_NETMAP
2206 "netmap|"
a1ea458f 2207#endif
af1a5c3e 2208 "socket][,option][,option][,...]\n"
6a8b4a5b
TH
2209 " old way to initialize a host network interface\n"
2210 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
5824d651 2211STEXI
abbbb035
TH
2212@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2213@findex -nic
2214This option is a shortcut for configuring both the on-board (default) guest
2215NIC hardware and the host network backend in one go. The host backend options
2216are the same as with the corresponding @option{-netdev} options below.
2217The guest NIC model can be set with @option{model=@var{modelname}}.
2218Use @option{model=help} to list the available device types.
2219The hardware MAC address can be set with @option{mac=@var{macaddr}}.
2220
2221The following two example do exactly the same, to show how @option{-nic} can
2222be used to shorten the command line length (note that the e1000 is the default
2223on i386, so the @option{model=e1000} parameter could even be omitted here, too):
2224@example
2225qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2226qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2227@end example
2228
2229@item -nic none
2230Indicate that no network devices should be configured. It is used to override
2231the default configuration (default NIC with ``user'' host network backend)
2232which is activated if no other networking options are provided.
5824d651 2233
08d12022 2234@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
b8f490eb 2235@findex -netdev
abbbb035 2236Configure user mode host network backend which requires no administrator
ad196a9d
JK
2237privilege to run. Valid options are:
2238
b3f046c2 2239@table @option
08d12022 2240@item id=@var{id}
ad196a9d
JK
2241Assign symbolic name for use in monitor commands.
2242
abbbb035
TH
2243@item ipv4=on|off and ipv6=on|off
2244Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2245both protocols are enabled.
0b11c036 2246
c92ef6a2
JK
2247@item net=@var{addr}[/@var{mask}]
2248Set IP network address the guest will see. Optionally specify the netmask,
2249either in the form a.b.c.d or as number of valid top-most bits. Default is
b0b36e5d 225010.0.2.0/24.
c92ef6a2
JK
2251
2252@item host=@var{addr}
2253Specify the guest-visible address of the host. Default is the 2nd IP in the
2254guest network, i.e. x.x.x.2.
ad196a9d 2255
d8eb3864
ST
2256@item ipv6-net=@var{addr}[/@var{int}]
2257Set IPv6 network address the guest will see (default is fec0::/64). The
2258network prefix is given in the usual hexadecimal IPv6 address
2259notation. The prefix size is optional, and is given as the number of
2260valid top-most bits (default is 64).
7aac531e 2261
d8eb3864 2262@item ipv6-host=@var{addr}
7aac531e
YB
2263Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2264the guest network, i.e. xxxx::2.
2265
c54ed5bc 2266@item restrict=on|off
caef55ed 2267If this option is enabled, the guest will be isolated, i.e. it will not be
ad196a9d 2268able to contact the host and no guest IP packets will be routed over the host
caef55ed 2269to the outside. This option does not affect any explicitly set forwarding rules.
ad196a9d
JK
2270
2271@item hostname=@var{name}
63d2960b 2272Specifies the client hostname reported by the built-in DHCP server.
ad196a9d 2273
c92ef6a2
JK
2274@item dhcpstart=@var{addr}
2275Specify the first of the 16 IPs the built-in DHCP server can assign. Default
b0b36e5d 2276is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
c92ef6a2
JK
2277
2278@item dns=@var{addr}
2279Specify the guest-visible address of the virtual nameserver. The address must
2280be different from the host address. Default is the 3rd IP in the guest network,
2281i.e. x.x.x.3.
7aac531e 2282
d8eb3864 2283@item ipv6-dns=@var{addr}
7aac531e
YB
2284Specify the guest-visible address of the IPv6 virtual nameserver. The address
2285must be different from the host address. Default is the 3rd IP in the guest
2286network, i.e. xxxx::3.
c92ef6a2 2287
63d2960b
KS
2288@item dnssearch=@var{domain}
2289Provides an entry for the domain-search list sent by the built-in
2290DHCP server. More than one domain suffix can be transmitted by specifying
2291this option multiple times. If supported, this will cause the guest to
2292automatically try to append the given domain suffix(es) in case a domain name
2293can not be resolved.
2294
2295Example:
2296@example
abbbb035 2297qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
63d2960b
KS
2298@end example
2299
f18d1375
BD
2300@item domainname=@var{domain}
2301Specifies the client domain name reported by the built-in DHCP server.
2302
ad196a9d
JK
2303@item tftp=@var{dir}
2304When using the user mode network stack, activate a built-in TFTP
2305server. The files in @var{dir} will be exposed as the root of a TFTP server.
2306The TFTP client on the guest must be configured in binary mode (use the command
c92ef6a2 2307@code{bin} of the Unix TFTP client).
ad196a9d 2308
0fca92b9
FZ
2309@item tftp-server-name=@var{name}
2310In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
231166). This can be used to advise the guest to load boot files or configurations
2312from a different server than the host address.
2313
ad196a9d
JK
2314@item bootfile=@var{file}
2315When using the user mode network stack, broadcast @var{file} as the BOOTP
2316filename. In conjunction with @option{tftp}, this can be used to network boot
2317a guest from a local directory.
2318
2319Example (using pxelinux):
2320@example
abbbb035
TH
2321qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
2322 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
ad196a9d
JK
2323@end example
2324
c92ef6a2 2325@item smb=@var{dir}[,smbserver=@var{addr}]
ad196a9d
JK
2326When using the user mode network stack, activate a built-in SMB
2327server so that Windows OSes can access to the host files in @file{@var{dir}}
c92ef6a2
JK
2328transparently. The IP address of the SMB server can be set to @var{addr}. By
2329default the 4th IP in the guest network is used, i.e. x.x.x.4.
ad196a9d
JK
2330
2331In the guest Windows OS, the line:
2332@example
233310.0.2.4 smbserver
2334@end example
2335must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2336or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2337
2338Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2339
e2d8830e 2340Note that a SAMBA server must be installed on the host OS.
ad196a9d 2341
3c6a0580 2342@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
c92ef6a2
JK
2343Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2344the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2345@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
3c6a0580
JK
2346given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2347be bound to a specific host interface. If no connection type is set, TCP is
c92ef6a2 2348used. This option can be given multiple times.
ad196a9d
JK
2349
2350For example, to redirect host X11 connection from screen 1 to guest
2351screen 0, use the following:
2352
2353@example
2354# on the host
abbbb035 2355qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
ad196a9d
JK
2356# this host xterm should open in the guest X11 server
2357xterm -display :1
2358@end example
2359
2360To redirect telnet connections from host port 5555 to telnet port on
2361the guest, use the following:
2362
2363@example
2364# on the host
abbbb035 2365qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
ad196a9d
JK
2366telnet localhost 5555
2367@end example
2368
2369Then when you use on the host @code{telnet localhost 5555}, you
2370connect to the guest telnet server.
5824d651 2371
c92ef6a2 2372@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
f9cfd655 2373@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
3c6a0580 2374Forward guest TCP connections to the IP address @var{server} on port @var{port}
b412eb61
AG
2375to the character device @var{dev} or to a program executed by @var{cmd:command}
2376which gets spawned for each connection. This option can be given multiple times.
2377
43ffe61f 2378You can either use a chardev directly and have that one used throughout QEMU's
b412eb61
AG
2379lifetime, like in the following example:
2380
2381@example
2382# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2383# the guest accesses it
abbbb035 2384qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
b412eb61
AG
2385@end example
2386
2387Or you can execute a command on every TCP connection established by the guest,
43ffe61f 2388so that QEMU behaves similar to an inetd process for that virtual server:
b412eb61
AG
2389
2390@example
2391# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2392# and connect the TCP stream to its stdin/stdout
abbbb035 2393qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
b412eb61 2394@end example
ad196a9d
JK
2395
2396@end table
2397
584613ea 2398@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
abbbb035 2399Configure a host TAP network backend with ID @var{id}.
a7c36ee4
CB
2400
2401Use the network script @var{file} to configure it and the network script
5824d651 2402@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
a7c36ee4
CB
2403automatically provides one. The default network configure script is
2404@file{/etc/qemu-ifup} and the default network deconfigure script is
2405@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2406to disable script execution.
2407
2408If running QEMU as an unprivileged user, use the network helper
584613ea
AK
2409@var{helper} to configure the TAP interface and attach it to the bridge.
2410The default network helper executable is @file{/path/to/qemu-bridge-helper}
2411and the default bridge device is @file{br0}.
a7c36ee4
CB
2412
2413@option{fd}=@var{h} can be used to specify the handle of an already
2414opened host TAP interface.
2415
2416Examples:
5824d651
BS
2417
2418@example
a7c36ee4 2419#launch a QEMU instance with the default network script
abbbb035 2420qemu-system-i386 linux.img -nic tap
5824d651
BS
2421@end example
2422
5824d651 2423@example
a7c36ee4
CB
2424#launch a QEMU instance with two NICs, each one connected
2425#to a TAP device
3804da9d 2426qemu-system-i386 linux.img \
74f78b99
TH
2427 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2428 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
5824d651
BS
2429@end example
2430
a7c36ee4
CB
2431@example
2432#launch a QEMU instance with the default network helper to
2433#connect a TAP device to bridge br0
abbbb035
TH
2434qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
2435 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
a7c36ee4
CB
2436@end example
2437
08d12022 2438@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
a7c36ee4
CB
2439Connect a host TAP network interface to a host bridge device.
2440
2441Use the network helper @var{helper} to configure the TAP interface and
2442attach it to the bridge. The default network helper executable is
420508fb 2443@file{/path/to/qemu-bridge-helper} and the default bridge
a7c36ee4
CB
2444device is @file{br0}.
2445
2446Examples:
2447
2448@example
2449#launch a QEMU instance with the default network helper to
2450#connect a TAP device to bridge br0
abbbb035 2451qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
a7c36ee4
CB
2452@end example
2453
2454@example
2455#launch a QEMU instance with the default network helper to
2456#connect a TAP device to bridge qemubr0
abbbb035 2457qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
a7c36ee4
CB
2458@end example
2459
08d12022 2460@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
5824d651 2461
abbbb035
TH
2462This host network backend can be used to connect the guest's network to
2463another QEMU virtual machine using a TCP socket connection. If @option{listen}
2464is specified, QEMU waits for incoming connections on @var{port}
5824d651
BS
2465(@var{host} is optional). @option{connect} is used to connect to
2466another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2467specifies an already opened TCP socket.
2468
2469Example:
2470@example
2471# launch a first QEMU instance
3804da9d 2472qemu-system-i386 linux.img \
abbbb035
TH
2473 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2474 -netdev socket,id=n1,listen=:1234
2475# connect the network of this instance to the network of the first instance
3804da9d 2476qemu-system-i386 linux.img \
abbbb035
TH
2477 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2478 -netdev socket,id=n2,connect=127.0.0.1:1234
5824d651
BS
2479@end example
2480
08d12022 2481@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
5824d651 2482
abbbb035
TH
2483Configure a socket host network backend to share the guest's network traffic
2484with another QEMU virtual machines using a UDP multicast socket, effectively
2485making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
5824d651
BS
2486NOTES:
2487@enumerate
2488@item
2489Several QEMU can be running on different hosts and share same bus (assuming
2490correct multicast setup for these hosts).
2491@item
2492mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2493@url{http://user-mode-linux.sf.net}.
2494@item
2495Use @option{fd=h} to specify an already opened UDP multicast socket.
2496@end enumerate
2497
2498Example:
2499@example
2500# launch one QEMU instance
3804da9d 2501qemu-system-i386 linux.img \
abbbb035
TH
2502 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2503 -netdev socket,id=n1,mcast=230.0.0.1:1234
5824d651 2504# launch another QEMU instance on same "bus"
3804da9d 2505qemu-system-i386 linux.img \
abbbb035
TH
2506 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2507 -netdev socket,id=n2,mcast=230.0.0.1:1234
5824d651 2508# launch yet another QEMU instance on same "bus"
3804da9d 2509qemu-system-i386 linux.img \
37a4442a 2510 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
abbbb035 2511 -netdev socket,id=n3,mcast=230.0.0.1:1234
5824d651
BS
2512@end example
2513
2514Example (User Mode Linux compat.):
2515@example
abbbb035 2516# launch QEMU instance (note mcast address selected is UML's default)
3804da9d 2517qemu-system-i386 linux.img \
abbbb035
TH
2518 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2519 -netdev socket,id=n1,mcast=239.192.168.1:1102
5824d651
BS
2520# launch UML
2521/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2522@end example
2523
3a75e74c
MR
2524Example (send packets from host's 1.2.3.4):
2525@example
3804da9d 2526qemu-system-i386 linux.img \
abbbb035
TH
2527 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2528 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
3a75e74c
MR
2529@end example
2530
3fb69aa1 2531@item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
abbbb035
TH
2532Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
2533popular protocol to transport Ethernet (and other Layer 2) data frames between
3fb69aa1
AI
2534two systems. It is present in routers, firewalls and the Linux kernel
2535(from version 3.3 onwards).
2536
2537This transport allows a VM to communicate to another VM, router or firewall directly.
2538
1e9a7379 2539@table @option
3fb69aa1
AI
2540@item src=@var{srcaddr}
2541 source address (mandatory)
2542@item dst=@var{dstaddr}
2543 destination address (mandatory)
2544@item udp
2545 select udp encapsulation (default is ip).
2546@item srcport=@var{srcport}
2547 source udp port.
2548@item dstport=@var{dstport}
2549 destination udp port.
2550@item ipv6
2551 force v6, otherwise defaults to v4.
2552@item rxcookie=@var{rxcookie}
f9cfd655 2553@itemx txcookie=@var{txcookie}
3fb69aa1
AI
2554 Cookies are a weak form of security in the l2tpv3 specification.
2555Their function is mostly to prevent misconfiguration. By default they are 32
2556bit.
2557@item cookie64
2558 Set cookie size to 64 bit instead of the default 32
2559@item counter=off
2560 Force a 'cut-down' L2TPv3 with no counter as in
2561draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2562@item pincounter=on
2563 Work around broken counter handling in peer. This may also help on
2564networks which have packet reorder.
2565@item offset=@var{offset}
2566 Add an extra offset between header and data
1e9a7379 2567@end table
3fb69aa1
AI
2568
2569For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2570on the remote Linux host 1.2.3.4:
2571@example
2572# Setup tunnel on linux host using raw ip as encapsulation
2573# on 1.2.3.4
2574ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2575 encap udp udp_sport 16384 udp_dport 16384
2576ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2577 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2578ifconfig vmtunnel0 mtu 1500
2579ifconfig vmtunnel0 up
2580brctl addif br-lan vmtunnel0
2581
2582
2583# on 4.3.2.1
2584# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2585
abbbb035
TH
2586qemu-system-i386 linux.img -device e1000,netdev=n1 \
2587 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
3fb69aa1
AI
2588
2589@end example
2590
08d12022 2591@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
abbbb035 2592Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
5824d651
BS
2593listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2594and MODE @var{octalmode} to change default ownership and permissions for
c1ba4e0b 2595communication port. This option is only available if QEMU has been compiled
5824d651
BS
2596with vde support enabled.
2597
2598Example:
2599@example
2600# launch vde switch
2601vde_switch -F -sock /tmp/myswitch
2602# launch QEMU instance
abbbb035 2603qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
5824d651
BS
2604@end example
2605
b931bfbf 2606@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
03ce5744
NN
2607
2608Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2609be a unix domain socket backed one. The vhost-user uses a specifically defined
2610protocol to pass vhost ioctl replacement messages to an application on the other
2611end of the socket. On non-MSIX guests, the feature can be forced with
b931bfbf
CO
2612@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2613be created for multiqueue vhost-user.
03ce5744
NN
2614
2615Example:
2616@example
2617qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2618 -numa node,memdev=mem \
79cad2fa 2619 -chardev socket,id=chr0,path=/path/to/socket \
03ce5744
NN
2620 -netdev type=vhost-user,id=net0,chardev=chr0 \
2621 -device virtio-net-pci,netdev=net0
2622@end example
2623
abbbb035 2624@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
78cd6f7b 2625
abbbb035 2626Create a hub port on the emulated hub with ID @var{hubid}.
78cd6f7b 2627
abbbb035 2628The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
af1a5c3e
TH
2629single netdev. Alternatively, you can also connect the hubport to another
2630netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
abbbb035 2631
af1a5c3e 2632@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
abbbb035
TH
2633@findex -net
2634Legacy option to configure or create an on-board (or machine default) Network
af1a5c3e
TH
2635Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2636the default hub), or to the netdev @var{nd}.
abbbb035
TH
2637The NIC is an e1000 by default on the PC target. Optionally, the MAC address
2638can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
2639only), and a @var{name} can be assigned for use in monitor commands.
2640Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2641that the card should have; this option currently only affects virtio cards; set
2642@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2643NIC is created. QEMU can emulate several different models of network card.
2644Use @code{-net nic,model=help} for a list of available devices for your target.
2645
af1a5c3e 2646@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
abbbb035 2647Configure a host network backend (with the options corresponding to the same
af1a5c3e
TH
2648@option{-netdev} option) and connect it to the emulated hub 0 (the default
2649hub). Use @var{name} to specify the name of the hub port.
c70a01e4 2650ETEXI
5824d651 2651
c70a01e4 2652STEXI
5824d651
BS
2653@end table
2654ETEXI
7273a2db
MB
2655DEFHEADING()
2656
de6b4f90 2657DEFHEADING(Character device options:)
7273a2db
MB
2658
2659DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
517b3d40 2660 "-chardev help\n"
d0d7708b 2661 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
5dd1f02b 2662 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
981b06e7 2663 " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n"
fd4a5fd4 2664 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
981b06e7 2665 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n"
d0d7708b 2666 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
7273a2db 2667 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
97331287 2668 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
d0d7708b
DB
2669 " [,logfile=PATH][,logappend=on|off]\n"
2670 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
7273a2db 2671 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
d0d7708b
DB
2672 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2673 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2674 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2675 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
7273a2db 2676#ifdef _WIN32
d0d7708b
DB
2677 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2678 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
7273a2db 2679#else
d0d7708b
DB
2680 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2681 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
7273a2db
MB
2682#endif
2683#ifdef CONFIG_BRLAPI
d0d7708b 2684 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
7273a2db
MB
2685#endif
2686#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2687 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
d0d7708b
DB
2688 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2689 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
7273a2db
MB
2690#endif
2691#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
d0d7708b
DB
2692 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2693 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
cbcc6336
AL
2694#endif
2695#if defined(CONFIG_SPICE)
d0d7708b
DB
2696 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2697 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
7273a2db 2698#endif
ad96090a 2699 , QEMU_ARCH_ALL
7273a2db
MB
2700)
2701
2702STEXI
dddba068
MA
2703
2704The general form of a character device option is:
2705@table @option
16fdc56a 2706@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
6616b2ad 2707@findex -chardev
7273a2db
MB
2708Backend is one of:
2709@option{null},
2710@option{socket},
2711@option{udp},
2712@option{msmouse},
2713@option{vc},
4f57378f 2714@option{ringbuf},
7273a2db
MB
2715@option{file},
2716@option{pipe},
2717@option{console},
2718@option{serial},
2719@option{pty},
2720@option{stdio},
2721@option{braille},
2722@option{tty},
88a946d3 2723@option{parallel},
cbcc6336 2724@option{parport},
16fdc56a 2725@option{spicevmc},
5a49d3e9 2726@option{spiceport}.
7273a2db
MB
2727The specific backend will determine the applicable options.
2728
dddba068 2729Use @code{-chardev help} to print all available chardev backend types.
517b3d40 2730
7273a2db
MB
2731All devices must have an id, which can be any string up to 127 characters long.
2732It is used to uniquely identify this device in other command line directives.
2733
97331287 2734A character device may be used in multiplexing mode by multiple front-ends.
a40db1b3
PM
2735Specify @option{mux=on} to enable this mode.
2736A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2737backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2738If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2739create a multiplexer with your specified ID, and you can then configure multiple
2740front ends to use that chardev ID for their input/output. Up to four different
2741front ends can be connected to a single multiplexed chardev. (Without
2742multiplexing enabled, a chardev can only be used by a single front end.)
2743For instance you could use this to allow a single stdio chardev to be used by
2744two serial ports and the QEMU monitor:
2745
2746@example
2747-chardev stdio,mux=on,id=char0 \
bdbcb547 2748-mon chardev=char0,mode=readline \
a40db1b3
PM
2749-serial chardev:char0 \
2750-serial chardev:char0
2751@end example
2752
2753You can have more than one multiplexer in a system configuration; for instance
2754you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2755multiplexed between the QEMU monitor and a parallel port:
2756
2757@example
2758-chardev stdio,mux=on,id=char0 \
bdbcb547 2759-mon chardev=char0,mode=readline \
a40db1b3
PM
2760-parallel chardev:char0 \
2761-chardev tcp,...,mux=on,id=char1 \
2762-serial chardev:char1 \
2763-serial chardev:char1
2764@end example
2765
2766When you're using a multiplexed character device, some escape sequences are
2767interpreted in the input. @xref{mux_keys, Keys in the character backend
2768multiplexer}.
2769
2770Note that some other command line options may implicitly create multiplexed
2771character backends; for instance @option{-serial mon:stdio} creates a
2772multiplexed stdio backend connected to the serial port and the QEMU monitor,
2773and @option{-nographic} also multiplexes the console and the monitor to
2774stdio.
2775
2776There is currently no support for multiplexing in the other direction
2777(where a single QEMU front end takes input and output from multiple chardevs).
97331287 2778
d0d7708b
DB
2779Every backend supports the @option{logfile} option, which supplies the path
2780to a file to record all data transmitted via the backend. The @option{logappend}
2781option controls whether the log file will be truncated or appended to when
2782opened.
2783
dddba068 2784@end table
7273a2db 2785
dddba068
MA
2786The available backends are:
2787
2788@table @option
16fdc56a 2789@item -chardev null,id=@var{id}
7273a2db
MB
2790A void device. This device will not emit any data, and will drop any data it
2791receives. The null backend does not take any options.
2792
fd4a5fd4 2793@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}]
7273a2db
MB
2794
2795Create a two-way stream socket, which can be either a TCP or a unix socket. A
2796unix socket will be created if @option{path} is specified. Behaviour is
2797undefined if TCP options are specified for a unix socket.
2798
2799@option{server} specifies that the socket shall be a listening socket.
2800
2801@option{nowait} specifies that QEMU should not block waiting for a client to
2802connect to a listening socket.
2803
2804@option{telnet} specifies that traffic on the socket should interpret telnet
2805escape sequences.
2806
981b06e7
JS
2807@option{websocket} specifies that the socket uses WebSocket protocol for
2808communication.
2809
5dd1f02b
CM
2810@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2811the remote end goes away. qemu will delay this many seconds and then attempt
2812to reconnect. Zero disables reconnecting, and is the default.
2813
a8fb5427
DB
2814@option{tls-creds} requests enablement of the TLS protocol for encryption,
2815and specifies the id of the TLS credentials to use for the handshake. The
2816credentials must be previously created with the @option{-object tls-creds}
2817argument.
2818
fd4a5fd4
DB
2819@option{tls-auth} provides the ID of the QAuthZ authorization object against
2820which the client's x509 distinguished name will be validated. This object is
2821only resolved at time of use, so can be deleted and recreated on the fly
2822while the chardev server is active. If missing, it will default to denying
2823access.
2824
7273a2db
MB
2825TCP and unix socket options are given below:
2826
2827@table @option
2828
16fdc56a 2829@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
7273a2db
MB
2830
2831@option{host} for a listening socket specifies the local address to be bound.
2832For a connecting socket species the remote host to connect to. @option{host} is
2833optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2834
2835@option{port} for a listening socket specifies the local port to be bound. For a
2836connecting socket specifies the port on the remote host to connect to.
2837@option{port} can be given as either a port number or a service name.
2838@option{port} is required.
2839
2840@option{to} is only relevant to listening sockets. If it is specified, and
2841@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2842to and including @option{to} until it succeeds. @option{to} must be specified
2843as a port number.
2844
2845@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2846If neither is specified the socket may use either protocol.
2847
2848@option{nodelay} disables the Nagle algorithm.
2849
2850@item unix options: path=@var{path}
2851
2852@option{path} specifies the local path of the unix socket. @option{path} is
2853required.
2854
2855@end table
2856
16fdc56a 2857@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6]
7273a2db
MB
2858
2859Sends all traffic from the guest to a remote host over UDP.
2860
2861@option{host} specifies the remote host to connect to. If not specified it
2862defaults to @code{localhost}.
2863
2864@option{port} specifies the port on the remote host to connect to. @option{port}
2865is required.
2866
2867@option{localaddr} specifies the local address to bind to. If not specified it
2868defaults to @code{0.0.0.0}.
2869
2870@option{localport} specifies the local port to bind to. If not specified any
2871available local port will be used.
2872
2873@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2874If neither is specified the device may use either protocol.
2875
16fdc56a 2876@item -chardev msmouse,id=@var{id}
7273a2db
MB
2877
2878Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2879take any options.
2880
16fdc56a 2881@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]]
7273a2db
MB
2882
2883Connect to a QEMU text console. @option{vc} may optionally be given a specific
2884size.
2885
2886@option{width} and @option{height} specify the width and height respectively of
2887the console, in pixels.
2888
2889@option{cols} and @option{rows} specify that the console be sized to fit a text
2890console with the given dimensions.
2891
16fdc56a 2892@item -chardev ringbuf,id=@var{id}[,size=@var{size}]
51767e7c 2893
3949e594 2894Create a ring buffer with fixed size @option{size}.
e69f7d25 2895@var{size} must be a power of two and defaults to @code{64K}.
51767e7c 2896
16fdc56a 2897@item -chardev file,id=@var{id},path=@var{path}
7273a2db
MB
2898
2899Log all traffic received from the guest to a file.
2900
2901@option{path} specifies the path of the file to be opened. This file will be
2902created if it does not already exist, and overwritten if it does. @option{path}
2903is required.
2904
16fdc56a 2905@item -chardev pipe,id=@var{id},path=@var{path}
7273a2db
MB
2906
2907Create a two-way connection to the guest. The behaviour differs slightly between
2908Windows hosts and other hosts:
2909
2910On Windows, a single duplex pipe will be created at
2911@file{\\.pipe\@option{path}}.
2912
2913On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2914@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2915received by the guest. Data written by the guest can be read from
2916@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2917be present.
2918
2919@option{path} forms part of the pipe path as described above. @option{path} is
2920required.
2921
16fdc56a 2922@item -chardev console,id=@var{id}
7273a2db
MB
2923
2924Send traffic from the guest to QEMU's standard output. @option{console} does not
2925take any options.
2926
2927@option{console} is only available on Windows hosts.
2928
16fdc56a 2929@item -chardev serial,id=@var{id},path=@option{path}
7273a2db
MB
2930
2931Send traffic from the guest to a serial device on the host.
2932
d59044ef
GH
2933On Unix hosts serial will actually accept any tty device,
2934not only serial lines.
7273a2db
MB
2935
2936@option{path} specifies the name of the serial device to open.
2937
16fdc56a 2938@item -chardev pty,id=@var{id}
7273a2db
MB
2939
2940Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2941not take any options.
2942
2943@option{pty} is not available on Windows hosts.
2944
16fdc56a 2945@item -chardev stdio,id=@var{id}[,signal=on|off]
b65ee4fa 2946Connect to standard input and standard output of the QEMU process.
b7fdb3ab
AJ
2947
2948@option{signal} controls if signals are enabled on the terminal, that includes
2949exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2950default, use @option{signal=off} to disable it.
2951
16fdc56a 2952@item -chardev braille,id=@var{id}
7273a2db
MB
2953
2954Connect to a local BrlAPI server. @option{braille} does not take any options.
2955
16fdc56a 2956@item -chardev tty,id=@var{id},path=@var{path}
7273a2db 2957
7273a2db 2958@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
d037d6bb 2959DragonFlyBSD hosts. It is an alias for @option{serial}.
7273a2db
MB
2960
2961@option{path} specifies the path to the tty. @option{path} is required.
2962
16fdc56a
TH
2963@item -chardev parallel,id=@var{id},path=@var{path}
2964@itemx -chardev parport,id=@var{id},path=@var{path}
7273a2db 2965
88a946d3 2966@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
7273a2db
MB
2967
2968Connect to a local parallel port.
2969
2970@option{path} specifies the path to the parallel port device. @option{path} is
2971required.
2972
16fdc56a 2973@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
cbcc6336 2974
3a846906
SH
2975@option{spicevmc} is only available when spice support is built in.
2976
cbcc6336
AL
2977@option{debug} debug level for spicevmc
2978
2979@option{name} name of spice channel to connect to
2980
2981Connect to a spice virtual machine channel, such as vdiport.
cbcc6336 2982
16fdc56a 2983@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
5a49d3e9
MAL
2984
2985@option{spiceport} is only available when spice support is built in.
2986
2987@option{debug} debug level for spicevmc
2988
2989@option{name} name of spice port to connect to
2990
2991Connect to a spice port, allowing a Spice client to handle the traffic
2992identified by a name (preferably a fqdn).
c70a01e4 2993ETEXI
5a49d3e9 2994
c70a01e4 2995STEXI
7273a2db
MB
2996@end table
2997ETEXI
7273a2db
MB
2998DEFHEADING()
2999
de6b4f90 3000DEFHEADING(Bluetooth(R) options:)
c70a01e4
MA
3001STEXI
3002@table @option
3003ETEXI
7273a2db 3004
5824d651 3005DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
5824d651
BS
3006 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
3007 "-bt hci,host[:id]\n" \
3008 " use host's HCI with the given name\n" \
3009 "-bt hci[,vlan=n]\n" \
3010 " emulate a standard HCI in virtual scatternet 'n'\n" \
3011 "-bt vhci[,vlan=n]\n" \
3012 " add host computer to virtual scatternet 'n' using VHCI\n" \
3013 "-bt device:dev[,vlan=n]\n" \
ad96090a
BS
3014 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
3015 QEMU_ARCH_ALL)
5824d651 3016STEXI
5824d651 3017@item -bt hci[...]
6616b2ad 3018@findex -bt
5824d651
BS
3019Defines the function of the corresponding Bluetooth HCI. -bt options
3020are matched with the HCIs present in the chosen machine type. For
3021example when emulating a machine with only one HCI built into it, only
3022the first @code{-bt hci[...]} option is valid and defines the HCI's
3023logic. The Transport Layer is decided by the machine type. Currently
3024the machines @code{n800} and @code{n810} have one HCI and all other
3025machines have none.
3026
c0188e69
TH
3027Note: This option and the whole bluetooth subsystem is considered as deprecated.
3028If you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where
3029you describe your usecase.
3030
5824d651
BS
3031@anchor{bt-hcis}
3032The following three types are recognized:
3033
b3f046c2 3034@table @option
5824d651
BS
3035@item -bt hci,null
3036(default) The corresponding Bluetooth HCI assumes no internal logic
3037and will not respond to any HCI commands or emit events.
3038
3039@item -bt hci,host[:@var{id}]
3040(@code{bluez} only) The corresponding HCI passes commands / events
3041to / from the physical HCI identified by the name @var{id} (default:
3042@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
3043capable systems like Linux.
3044
3045@item -bt hci[,vlan=@var{n}]
3046Add a virtual, standard HCI that will participate in the Bluetooth
3047scatternet @var{n} (default @code{0}). Similarly to @option{-net}
3048VLANs, devices inside a bluetooth network @var{n} can only communicate
3049with other devices in the same network (scatternet).
3050@end table
3051
3052@item -bt vhci[,vlan=@var{n}]
3053(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
3054to the host bluetooth stack instead of to the emulated target. This
3055allows the host and target machines to participate in a common scatternet
3056and communicate. Requires the Linux @code{vhci} driver installed. Can
3057be used as following:
3058
3059@example
3804da9d 3060qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
5824d651
BS
3061@end example
3062
3063@item -bt device:@var{dev}[,vlan=@var{n}]
3064Emulate a bluetooth device @var{dev} and place it in network @var{n}
3065(default @code{0}). QEMU can only emulate one type of bluetooth devices
3066currently:
3067
b3f046c2 3068@table @option
5824d651
BS
3069@item keyboard
3070Virtual wireless keyboard implementing the HIDP bluetooth profile.
3071@end table
5824d651
BS
3072ETEXI
3073
c70a01e4
MA
3074STEXI
3075@end table
3076ETEXI
5824d651
BS
3077DEFHEADING()
3078
d1a0cf73 3079#ifdef CONFIG_TPM
de6b4f90 3080DEFHEADING(TPM device options:)
d1a0cf73
SB
3081
3082DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
92dcc234
SB
3083 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3084 " use path to provide path to a character device; default is /dev/tpm0\n"
3085 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
f4ede81e
AV
3086 " not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3087 "-tpmdev emulator,id=id,chardev=dev\n"
3088 " configure the TPM device using chardev backend\n",
d1a0cf73
SB
3089 QEMU_ARCH_ALL)
3090STEXI
3091
3092The general form of a TPM device option is:
3093@table @option
3094
16fdc56a 3095@item -tpmdev @var{backend},id=@var{id}[,@var{options}]
d1a0cf73 3096@findex -tpmdev
d1a0cf73
SB
3097
3098The specific backend type will determine the applicable options.
28c4fa32
CB
3099The @code{-tpmdev} option creates the TPM backend and requires a
3100@code{-device} option that specifies the TPM frontend interface model.
d1a0cf73 3101
2252aaf0 3102Use @code{-tpmdev help} to print all available TPM backend types.
d1a0cf73 3103
2252aaf0
MA
3104@end table
3105
3106The available backends are:
3107
3108@table @option
d1a0cf73 3109
16fdc56a 3110@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
4549a8b7
SB
3111
3112(Linux-host only) Enable access to the host's TPM using the passthrough
3113driver.
3114
3115@option{path} specifies the path to the host's TPM device, i.e., on
3116a Linux host this would be @code{/dev/tpm0}.
3117@option{path} is optional and by default @code{/dev/tpm0} is used.
3118
92dcc234
SB
3119@option{cancel-path} specifies the path to the host TPM device's sysfs
3120entry allowing for cancellation of an ongoing TPM command.
3121@option{cancel-path} is optional and by default QEMU will search for the
3122sysfs entry to use.
3123
4549a8b7
SB
3124Some notes about using the host's TPM with the passthrough driver:
3125
3126The TPM device accessed by the passthrough driver must not be
3127used by any other application on the host.
3128
3129Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3130the VM's firmware (BIOS/UEFI) will not be able to initialize the
3131TPM again and may therefore not show a TPM-specific menu that would
3132otherwise allow the user to configure the TPM, e.g., allow the user to
3133enable/disable or activate/deactivate the TPM.
3134Further, if TPM ownership is released from within a VM then the host's TPM
3135will get disabled and deactivated. To enable and activate the
3136TPM again afterwards, the host has to be rebooted and the user is
3137required to enter the firmware's menu to enable and activate the TPM.
3138If the TPM is left disabled and/or deactivated most TPM commands will fail.
3139
3140To create a passthrough TPM use the following two options:
3141@example
3142-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3143@end example
3144Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3145@code{tpmdev=tpm0} in the device option.
3146
16fdc56a 3147@item -tpmdev emulator,id=@var{id},chardev=@var{dev}
f4ede81e
AV
3148
3149(Linux-host only) Enable access to a TPM emulator using Unix domain socket based
3150chardev backend.
3151
3152@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
3153
3154To create a TPM emulator backend device with chardev socket backend:
3155@example
3156
3157-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3158
3159@end example
3160
d1a0cf73
SB
3161ETEXI
3162
2252aaf0
MA
3163STEXI
3164@end table
3165ETEXI
d1a0cf73
SB
3166DEFHEADING()
3167
3168#endif
3169
de6b4f90 3170DEFHEADING(Linux/Multiboot boot specific:)
5824d651 3171STEXI
7677f05d
AG
3172
3173When using these options, you can use a given Linux or Multiboot
3174kernel without installing it in the disk image. It can be useful
5824d651
BS
3175for easier testing of various kernels.
3176
3177@table @option
3178ETEXI
3179
3180DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
ad96090a 3181 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
5824d651
BS
3182STEXI
3183@item -kernel @var{bzImage}
6616b2ad 3184@findex -kernel
7677f05d
AG
3185Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3186or in multiboot format.
5824d651
BS
3187ETEXI
3188
3189DEF("append", HAS_ARG, QEMU_OPTION_append, \
ad96090a 3190 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
5824d651
BS
3191STEXI
3192@item -append @var{cmdline}
6616b2ad 3193@findex -append
5824d651
BS
3194Use @var{cmdline} as kernel command line
3195ETEXI
3196
3197DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
ad96090a 3198 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
5824d651
BS
3199STEXI
3200@item -initrd @var{file}
6616b2ad 3201@findex -initrd
5824d651 3202Use @var{file} as initial ram disk.
7677f05d
AG
3203
3204@item -initrd "@var{file1} arg=foo,@var{file2}"
3205
3206This syntax is only available with multiboot.
3207
3208Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3209first module.
5824d651
BS
3210ETEXI
3211
412beee6 3212DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
379b5c7c 3213 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
412beee6
GL
3214STEXI
3215@item -dtb @var{file}
3216@findex -dtb
3217Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3218on boot.
3219ETEXI
3220
5824d651
BS
3221STEXI
3222@end table
3223ETEXI
5824d651
BS
3224DEFHEADING()
3225
de6b4f90 3226DEFHEADING(Debug/Expert options:)
5824d651
BS
3227STEXI
3228@table @option
3229ETEXI
3230
81b2b810
GS
3231DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3232 "-fw_cfg [name=]<name>,file=<file>\n"
63d3145a 3233 " add named fw_cfg entry with contents from file\n"
6407d76e 3234 "-fw_cfg [name=]<name>,string=<str>\n"
63d3145a 3235 " add named fw_cfg entry with contents from string\n",
81b2b810
GS
3236 QEMU_ARCH_ALL)
3237STEXI
63d3145a 3238
81b2b810
GS
3239@item -fw_cfg [name=]@var{name},file=@var{file}
3240@findex -fw_cfg
63d3145a 3241Add named fw_cfg entry with contents from file @var{file}.
6407d76e
GS
3242
3243@item -fw_cfg [name=]@var{name},string=@var{str}
63d3145a
MA
3244Add named fw_cfg entry with contents from string @var{str}.
3245
3246The terminating NUL character of the contents of @var{str} will not be
3247included as part of the fw_cfg item data. To insert contents with
3248embedded NUL characters, you have to use the @var{file} parameter.
3249
3250The fw_cfg entries are passed by QEMU through to the guest.
3251
3252Example:
3253@example
3254 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3255@end example
3256creates an fw_cfg entry named opt/com.mycompany/blob with contents
3257from ./my_blob.bin.
3258
81b2b810
GS
3259ETEXI
3260
5824d651 3261DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
ad96090a
BS
3262 "-serial dev redirect the serial port to char device 'dev'\n",
3263 QEMU_ARCH_ALL)
5824d651
BS
3264STEXI
3265@item -serial @var{dev}
6616b2ad 3266@findex -serial
5824d651
BS
3267Redirect the virtual serial port to host character device
3268@var{dev}. The default device is @code{vc} in graphical mode and
3269@code{stdio} in non graphical mode.
3270
3271This option can be used several times to simulate up to 4 serial
3272ports.
3273
3274Use @code{-serial none} to disable all serial ports.
3275
3276Available character devices are:
b3f046c2 3277@table @option
4e257e5e 3278@item vc[:@var{W}x@var{H}]
5824d651
BS
3279Virtual console. Optionally, a width and height can be given in pixel with
3280@example
3281vc:800x600
3282@end example
3283It is also possible to specify width or height in characters:
3284@example
3285vc:80Cx24C
3286@end example
3287@item pty
3288[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3289@item none
3290No device is allocated.
3291@item null
3292void device
88e020e5
IL
3293@item chardev:@var{id}
3294Use a named character device defined with the @code{-chardev} option.
5824d651
BS
3295@item /dev/XXX
3296[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3297parameters are set according to the emulated ones.
3298@item /dev/parport@var{N}
3299[Linux only, parallel port only] Use host parallel port
3300@var{N}. Currently SPP and EPP parallel port features can be used.
3301@item file:@var{filename}
3302Write output to @var{filename}. No character can be read.
3303@item stdio
3304[Unix only] standard input/output
3305@item pipe:@var{filename}
3306name pipe @var{filename}
3307@item COM@var{n}
3308[Windows only] Use host serial port @var{n}
3309@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3310This implements UDP Net Console.
3311When @var{remote_host} or @var{src_ip} are not specified
3312they default to @code{0.0.0.0}.
3313When not using a specified @var{src_port} a random port is automatically chosen.
5824d651
BS
3314
3315If you just want a simple readonly console you can use @code{netcat} or
b65ee4fa
SW
3316@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3317@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
5824d651
BS
3318will appear in the netconsole session.
3319
3320If you plan to send characters back via netconsole or you want to stop
b65ee4fa 3321and start QEMU a lot of times, you should have QEMU use the same
5824d651 3322source port each time by using something like @code{-serial
b65ee4fa 3323udp::4555@@:4556} to QEMU. Another approach is to use a patched
5824d651
BS
3324version of netcat which can listen to a TCP port and send and receive
3325characters via udp. If you have a patched version of netcat which
3326activates telnet remote echo and single char transfer, then you can
bd1caa3f 3327use the following options to set up a netcat redirector to allow
b65ee4fa 3328telnet on port 5555 to access the QEMU port.
5824d651 3329@table @code
071c9394 3330@item QEMU Options:
5824d651
BS
3331-serial udp::4555@@:4556
3332@item netcat options:
3333-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3334@item telnet options:
3335localhost 5555
3336@end table
3337
5dd1f02b 3338@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
5824d651
BS
3339The TCP Net Console has two modes of operation. It can send the serial
3340I/O to a location or wait for a connection from a location. By default
3341the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3342the @var{server} option QEMU will wait for a client socket application
3343to connect to the port before continuing, unless the @code{nowait}
3344option was specified. The @code{nodelay} option disables the Nagle buffering
5dd1f02b
CM
3345algorithm. The @code{reconnect} option only applies if @var{noserver} is
3346set, if the connection goes down it will attempt to reconnect at the
3347given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
5824d651
BS
3348one TCP connection at a time is accepted. You can use @code{telnet} to
3349connect to the corresponding character device.
3350@table @code
3351@item Example to send tcp console to 192.168.0.2 port 4444
3352-serial tcp:192.168.0.2:4444
3353@item Example to listen and wait on port 4444 for connection
3354-serial tcp::4444,server
3355@item Example to not wait and listen on ip 192.168.0.100 port 4444
3356-serial tcp:192.168.0.100:4444,server,nowait
3357@end table
3358
3359@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3360The telnet protocol is used instead of raw tcp sockets. The options
3361work the same as if you had specified @code{-serial tcp}. The
3362difference is that the port acts like a telnet server or client using
3363telnet option negotiation. This will also allow you to send the
3364MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3365sequence. Typically in unix telnet you do it with Control-] and then
3366type "send break" followed by pressing the enter key.
3367
981b06e7
JS
3368@item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
3369The WebSocket protocol is used instead of raw tcp socket. The port acts as
3370a WebSocket server. Client mode is not supported.
3371
5dd1f02b 3372@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
5824d651
BS
3373A unix domain socket is used instead of a tcp socket. The option works the
3374same as if you had specified @code{-serial tcp} except the unix domain socket
3375@var{path} is used for connections.
3376
3377@item mon:@var{dev_string}
3378This is a special option to allow the monitor to be multiplexed onto
3379another serial port. The monitor is accessed with key sequence of
02c4bdf1 3380@key{Control-a} and then pressing @key{c}.
5824d651
BS
3381@var{dev_string} should be any one of the serial devices specified
3382above. An example to multiplex the monitor onto a telnet server
3383listening on port 4444 would be:
3384@table @code
3385@item -serial mon:telnet::4444,server,nowait
3386@end table
be022d61
MT
3387When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3388QEMU any more but will be passed to the guest instead.
5824d651
BS
3389
3390@item braille
3391Braille device. This will use BrlAPI to display the braille output on a real
3392or fake device.
3393
be8b28a9
KW
3394@item msmouse
3395Three button serial mouse. Configure the guest to use Microsoft protocol.
5824d651
BS
3396@end table
3397ETEXI
3398
3399DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
ad96090a
BS
3400 "-parallel dev redirect the parallel port to char device 'dev'\n",
3401 QEMU_ARCH_ALL)
5824d651
BS
3402STEXI
3403@item -parallel @var{dev}
6616b2ad 3404@findex -parallel
5824d651
BS
3405Redirect the virtual parallel port to host device @var{dev} (same
3406devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3407be used to use hardware devices connected on the corresponding host
3408parallel port.
3409
3410This option can be used several times to simulate up to 3 parallel
3411ports.
3412
3413Use @code{-parallel none} to disable all parallel ports.
3414ETEXI
3415
3416DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
ad96090a
BS
3417 "-monitor dev redirect the monitor to char device 'dev'\n",
3418 QEMU_ARCH_ALL)
5824d651 3419STEXI
4e307fc8 3420@item -monitor @var{dev}
6616b2ad 3421@findex -monitor
5824d651
BS
3422Redirect the monitor to host device @var{dev} (same devices as the
3423serial port).
3424The default device is @code{vc} in graphical mode and @code{stdio} in
3425non graphical mode.
70e098af 3426Use @code{-monitor none} to disable the default monitor.
5824d651 3427ETEXI
6ca5582d 3428DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
ad96090a
BS
3429 "-qmp dev like -monitor but opens in 'control' mode\n",
3430 QEMU_ARCH_ALL)
95d5f08b
SW
3431STEXI
3432@item -qmp @var{dev}
6616b2ad 3433@findex -qmp
95d5f08b
SW
3434Like -monitor but opens in 'control' mode.
3435ETEXI
4821cd4c
HR
3436DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3437 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3438 QEMU_ARCH_ALL)
3439STEXI
3440@item -qmp-pretty @var{dev}
3441@findex -qmp-pretty
3442Like -qmp but uses pretty JSON formatting.
3443ETEXI
5824d651 3444
22a0e04b 3445DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
ef670726 3446 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
22a0e04b 3447STEXI
ef670726 3448@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
6616b2ad 3449@findex -mon
ef670726
VJA
3450Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3451easing human reading and debugging.
22a0e04b
GH
3452ETEXI
3453
c9f398e5 3454DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
ad96090a
BS
3455 "-debugcon dev redirect the debug console to char device 'dev'\n",
3456 QEMU_ARCH_ALL)
c9f398e5
PA
3457STEXI
3458@item -debugcon @var{dev}
6616b2ad 3459@findex -debugcon
c9f398e5
PA
3460Redirect the debug console to host device @var{dev} (same devices as the
3461serial port). The debug console is an I/O port which is typically port
34620xe9; writing to that I/O port sends output to this device.
3463The default device is @code{vc} in graphical mode and @code{stdio} in
3464non graphical mode.
3465ETEXI
3466
5824d651 3467DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
ad96090a 3468 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
5824d651
BS
3469STEXI
3470@item -pidfile @var{file}
6616b2ad 3471@findex -pidfile
5824d651
BS
3472Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3473from a script.
3474ETEXI
3475
1b530a6d 3476DEF("singlestep", 0, QEMU_OPTION_singlestep, \
ad96090a 3477 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
1b530a6d
AJ
3478STEXI
3479@item -singlestep
6616b2ad 3480@findex -singlestep
1b530a6d
AJ
3481Run the emulation in single step mode.
3482ETEXI
3483
047f7038 3484DEF("preconfig", 0, QEMU_OPTION_preconfig, \
361ac948 3485 "--preconfig pause QEMU before machine is initialized (experimental)\n",
047f7038
IM
3486 QEMU_ARCH_ALL)
3487STEXI
3488@item --preconfig
3489@findex --preconfig
3490Pause QEMU for interactive configuration before the machine is created,
3491which allows querying and configuring properties that will affect
361ac948
MA
3492machine initialization. Use QMP command 'x-exit-preconfig' to exit
3493the preconfig state and move to the next state (i.e. run guest if -S
3494isn't used or pause the second time if -S is used). This option is
3495experimental.
047f7038
IM
3496ETEXI
3497
5824d651 3498DEF("S", 0, QEMU_OPTION_S, \
ad96090a
BS
3499 "-S freeze CPU at startup (use 'c' to start execution)\n",
3500 QEMU_ARCH_ALL)
5824d651
BS
3501STEXI
3502@item -S
6616b2ad 3503@findex -S
5824d651
BS
3504Do not start CPU at startup (you must type 'c' in the monitor).
3505ETEXI
3506
888a6bc6
SM
3507DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3508 "-realtime [mlock=on|off]\n"
3509 " run qemu with realtime features\n"
3510 " mlock=on|off controls mlock support (default: on)\n",
3511 QEMU_ARCH_ALL)
3512STEXI
3513@item -realtime mlock=on|off
3514@findex -realtime
3515Run qemu with realtime features.
3516mlocking qemu and guest memory can be enabled via @option{mlock=on}
3517(enabled by default).
3518ETEXI
3519
6f131f13 3520DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
dfaa7d50 3521 "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
6f131f13
MT
3522 " run qemu with overcommit hints\n"
3523 " mem-lock=on|off controls memory lock support (default: off)\n"
3524 " cpu-pm=on|off controls cpu power management (default: off)\n",
3525 QEMU_ARCH_ALL)
3526STEXI
3527@item -overcommit mem-lock=on|off
3528@item -overcommit cpu-pm=on|off
3529@findex -overcommit
3530Run qemu with hints about host resource overcommit. The default is
3531to assume that host overcommits all resources.
3532
3533Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3534by default). This works when host memory is not overcommitted and reduces the
3535worst-case latency for guest. This is equivalent to @option{realtime}.
3536
3537Guest ability to manage power state of host cpus (increasing latency for other
3538processes on the same host cpu, but decreasing latency for guest) can be
3539enabled via @option{cpu-pm=on} (disabled by default). This works best when
3540host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3541utilization will be incorrect, not taking into account guest idle time.
3542ETEXI
3543
59030a8c 3544DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
ad96090a 3545 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
59030a8c
AL
3546STEXI
3547@item -gdb @var{dev}
6616b2ad 3548@findex -gdb
59030a8c
AL
3549Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3550connections will likely be TCP-based, but also UDP, pseudo TTY, or even
b65ee4fa 3551stdio are reasonable use case. The latter is allowing to start QEMU from
59030a8c
AL
3552within gdb and establish the connection via a pipe:
3553@example
3804da9d 3554(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
59030a8c 3555@end example
5824d651
BS
3556ETEXI
3557
59030a8c 3558DEF("s", 0, QEMU_OPTION_s, \
ad96090a
BS
3559 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3560 QEMU_ARCH_ALL)
5824d651 3561STEXI
59030a8c 3562@item -s
6616b2ad 3563@findex -s
59030a8c
AL
3564Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3565(@pxref{gdb_usage}).
5824d651
BS
3566ETEXI
3567
3568DEF("d", HAS_ARG, QEMU_OPTION_d, \
989b697d 3569 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
ad96090a 3570 QEMU_ARCH_ALL)
5824d651 3571STEXI
989b697d 3572@item -d @var{item1}[,...]
6616b2ad 3573@findex -d
989b697d 3574Enable logging of specified items. Use '-d help' for a list of log items.
5824d651
BS
3575ETEXI
3576
c235d738 3577DEF("D", HAS_ARG, QEMU_OPTION_D, \
989b697d 3578 "-D logfile output log to logfile (default stderr)\n",
c235d738
MF
3579 QEMU_ARCH_ALL)
3580STEXI
8bd383b4 3581@item -D @var{logfile}
c235d738 3582@findex -D
989b697d 3583Output log in @var{logfile} instead of to stderr
c235d738
MF
3584ETEXI
3585
3514552e
AB
3586DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3587 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3588 QEMU_ARCH_ALL)
3589STEXI
3590@item -dfilter @var{range1}[,...]
3591@findex -dfilter
3592Filter debug output to that relevant to a range of target addresses. The filter
3593spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3594@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3595addresses and sizes required. For example:
3596@example
3597 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3598@end example
3599Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3600the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3601block starting at 0xffffffc00005f000.
3602ETEXI
3603
5824d651 3604DEF("L", HAS_ARG, QEMU_OPTION_L, \
ad96090a
BS
3605 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3606 QEMU_ARCH_ALL)
5824d651
BS
3607STEXI
3608@item -L @var{path}
6616b2ad 3609@findex -L
5824d651 3610Set the directory for the BIOS, VGA BIOS and keymaps.
37146e7e
RJ
3611
3612To list all the data directories, use @code{-L help}.
5824d651
BS
3613ETEXI
3614
3615DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
ad96090a 3616 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
5824d651
BS
3617STEXI
3618@item -bios @var{file}
6616b2ad 3619@findex -bios
5824d651
BS
3620Set the filename for the BIOS.
3621ETEXI
3622
5824d651 3623DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
ad96090a 3624 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
5824d651
BS
3625STEXI
3626@item -enable-kvm
6616b2ad 3627@findex -enable-kvm
5824d651
BS
3628Enable KVM full virtualization support. This option is only available
3629if KVM support is enabled when compiling.
3630ETEXI
3631
e37630ca 3632DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
ad96090a 3633 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
e37630ca
AL
3634DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3635 "-xen-attach attach to existing xen domain\n"
1077bcac 3636 " libxl will use this when starting QEMU\n",
ad96090a 3637 QEMU_ARCH_ALL)
1c599472
PD
3638DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3639 "-xen-domid-restrict restrict set of available xen operations\n"
3640 " to specified domain id. (Does not affect\n"
3641 " xenpv machine type).\n",
3642 QEMU_ARCH_ALL)
95d5f08b
SW
3643STEXI
3644@item -xen-domid @var{id}
6616b2ad 3645@findex -xen-domid
95d5f08b 3646Specify xen guest domain @var{id} (XEN only).
95d5f08b 3647@item -xen-attach
6616b2ad 3648@findex -xen-attach
95d5f08b 3649Attach to existing xen domain.
1077bcac 3650libxl will use this when starting QEMU (XEN only).
1c599472
PD
3651@findex -xen-domid-restrict
3652Restrict set of available xen operations to specified domain id (XEN only).
95d5f08b 3653ETEXI
e37630ca 3654
5824d651 3655DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
ad96090a 3656 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
5824d651
BS
3657STEXI
3658@item -no-reboot
6616b2ad 3659@findex -no-reboot
5824d651
BS
3660Exit instead of rebooting.
3661ETEXI
3662
3663DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
ad96090a 3664 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
5824d651
BS
3665STEXI
3666@item -no-shutdown
6616b2ad 3667@findex -no-shutdown
5824d651
BS
3668Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3669This allows for instance switching to monitor to commit changes to the
3670disk image.
3671ETEXI
3672
3673DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3674 "-loadvm [tag|id]\n" \
ad96090a
BS
3675 " start right away with a saved state (loadvm in monitor)\n",
3676 QEMU_ARCH_ALL)
5824d651
BS
3677STEXI
3678@item -loadvm @var{file}
6616b2ad 3679@findex -loadvm
5824d651
BS
3680Start right away with a saved state (@code{loadvm} in monitor)
3681ETEXI
3682
3683#ifndef _WIN32
3684DEF("daemonize", 0, QEMU_OPTION_daemonize, \
ad96090a 3685 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
5824d651
BS
3686#endif
3687STEXI
3688@item -daemonize
6616b2ad 3689@findex -daemonize
5824d651
BS
3690Daemonize the QEMU process after initialization. QEMU will not detach from
3691standard IO until it is ready to receive connections on any of its devices.
3692This option is a useful way for external programs to launch QEMU without having
3693to cope with initialization race conditions.
3694ETEXI
3695
3696DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
ad96090a
BS
3697 "-option-rom rom load a file, rom, into the option ROM space\n",
3698 QEMU_ARCH_ALL)
5824d651
BS
3699STEXI
3700@item -option-rom @var{file}
6616b2ad 3701@findex -option-rom
5824d651
BS
3702Load the contents of @var{file} as an option ROM.
3703This option is useful to load things like EtherBoot.
3704ETEXI
3705
1ed2fc1f 3706DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
238d1240 3707 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
ad96090a
BS
3708 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3709 QEMU_ARCH_ALL)
5824d651 3710
5824d651
BS
3711STEXI
3712
238d1240 3713@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
6616b2ad 3714@findex -rtc
1ed2fc1f
JK
3715Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3716UTC or local time, respectively. @code{localtime} is required for correct date in
238d1240 3717MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
1ed2fc1f
JK
3718format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3719
9d85d557 3720By default the RTC is driven by the host system time. This allows using of the
6875204c
JK
3721RTC as accurate reference clock inside the guest, specifically if the host
3722time is smoothly following an accurate external reference clock, e.g. via NTP.
78808141 3723If you want to isolate the guest time from the host, you can set @option{clock}
238d1240
AP
3724to @code{rt} instead, which provides a host monotonic clock if host support it.
3725To even prevent the RTC from progressing during suspension, you can set @option{clock}
3726to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
3727icount mode in order to preserve determinism; however, note that in icount mode
3728the speed of the virtual clock is variable and can in general differ from the
3729host clock.
6875204c 3730
1ed2fc1f
JK
3731Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3732specifically with Windows' ACPI HAL. This option will try to figure out how
3733many timer interrupts were not processed by the Windows guest and will
3734re-inject them.
5824d651
BS
3735ETEXI
3736
3737DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
9c2037d0 3738 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
bc14ca24 3739 " enable virtual instruction counter with 2^N clock ticks per\n" \
f1f4b57e
VC
3740 " instruction, enable aligning the host and virtual clocks\n" \
3741 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
5824d651 3742STEXI
9c2037d0 3743@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
6616b2ad 3744@findex -icount
5824d651 3745Enable virtual instruction counter. The virtual cpu will execute one
4e257e5e 3746instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
5824d651
BS
3747then the virtual cpu speed will be automatically adjusted to keep virtual
3748time within a few seconds of real time.
3749
f1f4b57e 3750When the virtual cpu is sleeping, the virtual time will advance at default
778d9f9b
PK
3751speed unless @option{sleep=on|off} is specified.
3752With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
f1f4b57e
VC
3753instantly whenever the virtual cpu goes to sleep mode and will not advance
3754if no timer is enabled. This behavior give deterministic execution times from
3755the guest point of view.
3756
5824d651
BS
3757Note that while this option can give deterministic behavior, it does not
3758provide cycle accurate emulation. Modern CPUs contain superscalar out of
3759order cores with complex cache hierarchies. The number of instructions
3760executed often has little or no correlation with actual performance.
a8bfac37 3761
b6af0975 3762@option{align=on} will activate the delay algorithm which will try
a8bfac37
ST
3763to synchronise the host clock and the virtual clock. The goal is to
3764have a guest running at the real frequency imposed by the shift option.
3765Whenever the guest clock is behind the host clock and if
82597615 3766@option{align=on} is specified then we print a message to the user
a8bfac37
ST
3767to inform about the delay.
3768Currently this option does not work when @option{shift} is @code{auto}.
3769Note: The sync algorithm will work for those shift values for which
3770the guest clock runs ahead of the host clock. Typically this happens
3771when the shift value is high (how high depends on the host machine).
4c27b859
PD
3772
3773When @option{rr} option is specified deterministic record/replay is enabled.
3774Replay log is written into @var{filename} file in record mode and
3775read from this file in replay mode.
9c2037d0
PD
3776
3777Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3778at the start of execution recording. In replay mode this option is used
3779to load the initial VM state.
5824d651
BS
3780ETEXI
3781
9dd986cc 3782DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
d7933ef3 3783 "-watchdog model\n" \
ad96090a
BS
3784 " enable virtual hardware watchdog [default=none]\n",
3785 QEMU_ARCH_ALL)
9dd986cc
RJ
3786STEXI
3787@item -watchdog @var{model}
6616b2ad 3788@findex -watchdog
9dd986cc
RJ
3789Create a virtual hardware watchdog device. Once enabled (by a guest
3790action), the watchdog must be periodically polled by an agent inside
d7933ef3
XW
3791the guest or else the guest will be restarted. Choose a model for
3792which your guest has drivers.
9dd986cc 3793
d7933ef3
XW
3794The @var{model} is the model of hardware watchdog to emulate. Use
3795@code{-watchdog help} to list available hardware models. Only one
9dd986cc 3796watchdog can be enabled for a guest.
d7933ef3
XW
3797
3798The following models may be available:
3799@table @option
3800@item ib700
3801iBASE 700 is a very simple ISA watchdog with a single timer.
3802@item i6300esb
3803Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3804dual-timer watchdog.
188f24c2
XW
3805@item diag288
3806A virtual watchdog for s390x backed by the diagnose 288 hypercall
3807(currently KVM only).
d7933ef3 3808@end table
9dd986cc
RJ
3809ETEXI
3810
3811DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
7ad9270e 3812 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
ad96090a
BS
3813 " action when watchdog fires [default=reset]\n",
3814 QEMU_ARCH_ALL)
9dd986cc
RJ
3815STEXI
3816@item -watchdog-action @var{action}
b8f490eb 3817@findex -watchdog-action
9dd986cc
RJ
3818
3819The @var{action} controls what QEMU will do when the watchdog timer
3820expires.
3821The default is
3822@code{reset} (forcefully reset the guest).
3823Other possible actions are:
3824@code{shutdown} (attempt to gracefully shutdown the guest),
3825@code{poweroff} (forcefully poweroff the guest),
7ad9270e 3826@code{inject-nmi} (inject a NMI into the guest),
9dd986cc
RJ
3827@code{pause} (pause the guest),
3828@code{debug} (print a debug message and continue), or
3829@code{none} (do nothing).
3830
3831Note that the @code{shutdown} action requires that the guest responds
3832to ACPI signals, which it may not be able to do in the sort of
3833situations where the watchdog would have expired, and thus
3834@code{-watchdog-action shutdown} is not recommended for production use.
3835
3836Examples:
3837
3838@table @code
3839@item -watchdog i6300esb -watchdog-action pause
f9cfd655 3840@itemx -watchdog ib700
9dd986cc
RJ
3841@end table
3842ETEXI
3843
5824d651 3844DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
ad96090a
BS
3845 "-echr chr set terminal escape character instead of ctrl-a\n",
3846 QEMU_ARCH_ALL)
5824d651
BS
3847STEXI
3848
4e257e5e 3849@item -echr @var{numeric_ascii_value}
6616b2ad 3850@findex -echr
5824d651
BS
3851Change the escape character used for switching to the monitor when using
3852monitor and serial sharing. The default is @code{0x01} when using the
3853@code{-nographic} option. @code{0x01} is equal to pressing
3854@code{Control-a}. You can select a different character from the ascii
3855control keys where 1 through 26 map to Control-a through Control-z. For
3856instance you could use the either of the following to change the escape
3857character to Control-t.
3858@table @code
3859@item -echr 0x14
f9cfd655 3860@itemx -echr 20
5824d651
BS
3861@end table
3862ETEXI
3863
5824d651 3864DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
ad96090a 3865 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
5824d651 3866STEXI
95d5f08b 3867@item -show-cursor
6616b2ad 3868@findex -show-cursor
95d5f08b 3869Show cursor.
5824d651
BS
3870ETEXI
3871
3872DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
ad96090a 3873 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
5824d651 3874STEXI
95d5f08b 3875@item -tb-size @var{n}
6616b2ad 3876@findex -tb-size
95d5f08b 3877Set TB size.
5824d651
BS
3878ETEXI
3879
3880DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
7c601803
MT
3881 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3882 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3883 "-incoming unix:socketpath\n" \
3884 " prepare for incoming migration, listen on\n" \
3885 " specified protocol and socket address\n" \
3886 "-incoming fd:fd\n" \
3887 "-incoming exec:cmdline\n" \
3888 " accept incoming migration on given file descriptor\n" \
1597051b
DDAG
3889 " or from given external command\n" \
3890 "-incoming defer\n" \
3891 " wait for the URI to be specified via migrate_incoming\n",
ad96090a 3892 QEMU_ARCH_ALL)
5824d651 3893STEXI
7c601803 3894@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
f9cfd655 3895@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
6616b2ad 3896@findex -incoming
7c601803
MT
3897Prepare for incoming migration, listen on a given tcp port.
3898
3899@item -incoming unix:@var{socketpath}
3900Prepare for incoming migration, listen on a given unix socket.
3901
3902@item -incoming fd:@var{fd}
3903Accept incoming migration from a given filedescriptor.
3904
3905@item -incoming exec:@var{cmdline}
3906Accept incoming migration as an output from specified external command.
1597051b
DDAG
3907
3908@item -incoming defer
3909Wait for the URI to be specified via migrate_incoming. The monitor can
3910be used to change settings (such as migration parameters) prior to issuing
3911the migrate_incoming to allow the migration to begin.
5824d651
BS
3912ETEXI
3913
d15c05fc
AA
3914DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3915 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3916STEXI
3917@item -only-migratable
3918@findex -only-migratable
3919Only allow migratable devices. Devices will not be allowed to enter an
3920unmigratable state.
3921ETEXI
3922
d8c208dd 3923DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
ad96090a 3924 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
d8c208dd 3925STEXI
3dbf2c7f 3926@item -nodefaults
6616b2ad 3927@findex -nodefaults
66c19bf1
MN
3928Don't create default devices. Normally, QEMU sets the default devices like serial
3929port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3930CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3931default devices.
d8c208dd
GH
3932ETEXI
3933
5824d651
BS
3934#ifndef _WIN32
3935DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
ad96090a
BS
3936 "-chroot dir chroot to dir just before starting the VM\n",
3937 QEMU_ARCH_ALL)
5824d651
BS
3938#endif
3939STEXI
4e257e5e 3940@item -chroot @var{dir}
6616b2ad 3941@findex -chroot
5824d651
BS
3942Immediately before starting guest execution, chroot to the specified
3943directory. Especially useful in combination with -runas.
3944ETEXI
3945
3946#ifndef _WIN32
3947DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
2c42f1e8
IJ
3948 "-runas user change to user id user just before starting the VM\n" \
3949 " user can be numeric uid:gid instead\n",
ad96090a 3950 QEMU_ARCH_ALL)
5824d651
BS
3951#endif
3952STEXI
4e257e5e 3953@item -runas @var{user}
6616b2ad 3954@findex -runas
5824d651
BS
3955Immediately before starting guest execution, drop root privileges, switching
3956to the specified user.
3957ETEXI
3958
5824d651
BS
3959DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3960 "-prom-env variable=value\n"
ad96090a
BS
3961 " set OpenBIOS nvram variables\n",
3962 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
95d5f08b
SW
3963STEXI
3964@item -prom-env @var{variable}=@var{value}
6616b2ad 3965@findex -prom-env
95d5f08b
SW
3966Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3967ETEXI
5824d651 3968DEF("semihosting", 0, QEMU_OPTION_semihosting,
f7bbcfb5 3969 "-semihosting semihosting mode\n",
3b3c1694
LA
3970 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3971 QEMU_ARCH_MIPS)
95d5f08b
SW
3972STEXI
3973@item -semihosting
6616b2ad 3974@findex -semihosting
3b3c1694 3975Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
a38bb079
LI
3976ETEXI
3977DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
a59d31a1
LA
3978 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3979 " semihosting configuration\n",
3b3c1694
LA
3980QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3981QEMU_ARCH_MIPS)
a38bb079 3982STEXI
a59d31a1 3983@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
a38bb079 3984@findex -semihosting-config
3b3c1694 3985Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
a59d31a1
LA
3986@table @option
3987@item target=@code{native|gdb|auto}
3988Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3989or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3990during debug sessions and @code{native} otherwise.
3991@item arg=@var{str1},arg=@var{str2},...
3992Allows the user to pass input arguments, and can be used multiple times to build
3993up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3994command line is still supported for backward compatibility. If both the
3995@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3996specified, the former is passed to semihosting as it always takes precedence.
3997@end table
95d5f08b 3998ETEXI
5824d651 3999DEF("old-param", 0, QEMU_OPTION_old_param,
ad96090a 4000 "-old-param old param mode\n", QEMU_ARCH_ARM)
95d5f08b
SW
4001STEXI
4002@item -old-param
6616b2ad 4003@findex -old-param (ARM)
95d5f08b
SW
4004Old param mode (ARM only).
4005ETEXI
4006
7d76ad4f 4007DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
73a1e647 4008 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
24f8cdc5 4009 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
2b716fa6
EO
4010 " Enable seccomp mode 2 system call filter (default 'off').\n" \
4011 " use 'obsolete' to allow obsolete system calls that are provided\n" \
4012 " by the kernel, but typically no longer used by modern\n" \
73a1e647
EO
4013 " C library implementations.\n" \
4014 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
4015 " its privileges by blacklisting all set*uid|gid system calls.\n" \
4016 " The value 'children' will deny set*uid|gid system calls for\n" \
995a226f
EO
4017 " main QEMU process but will allow forks and execves to run unprivileged\n" \
4018 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
24f8cdc5
EO
4019 " blacklisting *fork and execve\n" \
4020 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
7d76ad4f
EO
4021 QEMU_ARCH_ALL)
4022STEXI
24f8cdc5 4023@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
7d76ad4f
EO
4024@findex -sandbox
4025Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
4026disable it. The default is 'off'.
2b716fa6
EO
4027@table @option
4028@item obsolete=@var{string}
4029Enable Obsolete system calls
73a1e647
EO
4030@item elevateprivileges=@var{string}
4031Disable set*uid|gid system calls
995a226f
EO
4032@item spawn=@var{string}
4033Disable *fork and execve
24f8cdc5
EO
4034@item resourcecontrol=@var{string}
4035Disable process affinity and schedular priority
2b716fa6 4036@end table
7d76ad4f
EO
4037ETEXI
4038
715a664a 4039DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
ad96090a 4040 "-readconfig <file>\n", QEMU_ARCH_ALL)
3dbf2c7f
SW
4041STEXI
4042@item -readconfig @var{file}
6616b2ad 4043@findex -readconfig
ed24cfac
MN
4044Read device configuration from @var{file}. This approach is useful when you want to spawn
4045QEMU process with many command line options but you don't want to exceed the command line
4046character limit.
3dbf2c7f 4047ETEXI
715a664a
GH
4048DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
4049 "-writeconfig <file>\n"
ad96090a 4050 " read/write config file\n", QEMU_ARCH_ALL)
3dbf2c7f
SW
4051STEXI
4052@item -writeconfig @var{file}
6616b2ad 4053@findex -writeconfig
ed24cfac
MN
4054Write device configuration to @var{file}. The @var{file} can be either filename to save
4055command line and device configuration into file or dash @code{-}) character to print the
4056output to stdout. This can be later used as input file for @code{-readconfig} option.
3dbf2c7f 4057ETEXI
2feac451 4058
f29a5614
EH
4059DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
4060 "-no-user-config\n"
3478eae9 4061 " do not load default user-provided config files at startup\n",
f29a5614
EH
4062 QEMU_ARCH_ALL)
4063STEXI
4064@item -no-user-config
4065@findex -no-user-config
4066The @code{-no-user-config} option makes QEMU not load any of the user-provided
3478eae9 4067config files on @var{sysconfdir}.
292444cb 4068ETEXI
2feac451 4069
ab6540d5 4070DEF("trace", HAS_ARG, QEMU_OPTION_trace,
10578a25 4071 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
23d15e86 4072 " specify tracing options\n",
ab6540d5
PS
4073 QEMU_ARCH_ALL)
4074STEXI
23d15e86
LV
4075HXCOMM This line is not accurate, as some sub-options are backend-specific but
4076HXCOMM HX does not support conditional compilation of text.
e370ad99 4077@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
ab6540d5 4078@findex -trace
eeb2b8f7 4079@include qemu-option-trace.texi
ab6540d5 4080ETEXI
3dbf2c7f 4081
31e70d6c
MA
4082HXCOMM Internal use
4083DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
4084DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
c7f0f3b1 4085
0f66998f
PM
4086#ifdef __linux__
4087DEF("enable-fips", 0, QEMU_OPTION_enablefips,
4088 "-enable-fips enable FIPS 140-2 compliance\n",
4089 QEMU_ARCH_ALL)
4090#endif
4091STEXI
4092@item -enable-fips
4093@findex -enable-fips
4094Enable FIPS 140-2 compliance mode.
4095ETEXI
4096
a0dac021 4097HXCOMM Deprecated by -machine accel=tcg property
c6e88b3b 4098DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
a0dac021 4099
5e2ac519
SA
4100DEF("msg", HAS_ARG, QEMU_OPTION_msg,
4101 "-msg timestamp[=on|off]\n"
4102 " change the format of messages\n"
4103 " on|off controls leading timestamps (default:on)\n",
4104 QEMU_ARCH_ALL)
4105STEXI
4106@item -msg timestamp[=on|off]
4107@findex -msg
4108prepend a timestamp to each log message.(default:on)
4109ETEXI
4110
abfd9ce3
AS
4111DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
4112 "-dump-vmstate <file>\n"
4113 " Output vmstate information in JSON format to file.\n"
4114 " Use the scripts/vmstate-static-checker.py file to\n"
4115 " check for possible regressions in migration code\n"
2382053f 4116 " by comparing two such vmstate dumps.\n",
abfd9ce3
AS
4117 QEMU_ARCH_ALL)
4118STEXI
4119@item -dump-vmstate @var{file}
4120@findex -dump-vmstate
4121Dump json-encoded vmstate information for current machine type to file
4122in @var{file}
4123ETEXI
4124
12df189d
EC
4125DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
4126 "-enable-sync-profile\n"
4127 " enable synchronization profiling\n",
4128 QEMU_ARCH_ALL)
4129STEXI
4130@item -enable-sync-profile
4131@findex -enable-sync-profile
4132Enable synchronization profiling.
4133ETEXI
4134
43f187a5
PB
4135STEXI
4136@end table
4137ETEXI
4138DEFHEADING()
de6b4f90
MA
4139
4140DEFHEADING(Generic object creation:)
43f187a5
PB
4141STEXI
4142@table @option
4143ETEXI
b9174d4f
DB
4144
4145DEF("object", HAS_ARG, QEMU_OPTION_object,
4146 "-object TYPENAME[,PROP1=VALUE1,...]\n"
4147 " create a new object of type TYPENAME setting properties\n"
4148 " in the order they are specified. Note that the 'id'\n"
4149 " property must be set. These objects are placed in the\n"
4150 " '/objects' path.\n",
4151 QEMU_ARCH_ALL)
4152STEXI
4153@item -object @var{typename}[,@var{prop1}=@var{value1},...]
4154@findex -object
4155Create a new object of type @var{typename} setting properties
4156in the order they are specified. Note that the 'id'
4157property must be set. These objects are placed in the
4158'/objects' path.
4159
4160@table @option
4161
98376843 4162@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},align=@var{align}
b9174d4f
DB
4163
4164Creates a memory file backend object, which can be used to back
c7cddce1
SH
4165the guest RAM with huge pages.
4166
4167The @option{id} parameter is a unique ID that will be used to reference this
4168memory region when configuring the @option{-numa} argument.
4169
4170The @option{size} option provides the size of the memory region, and accepts
4171common suffixes, eg @option{500M}.
4172
4173The @option{mem-path} provides the path to either a shared memory or huge page
4174filesystem mount.
4175
b9174d4f
DB
4176The @option{share} boolean option determines whether the memory
4177region is marked as private to QEMU, or shared. The latter allows
4178a co-operating external process to access the QEMU memory region.
c7cddce1 4179
06329cce
MA
4180The @option{share} is also required for pvrdma devices due to
4181limitations in the RDMA API provided by Linux.
4182
4183Setting share=on might affect the ability to configure NUMA
4184bindings for the memory backend under some circumstances, see
4185Documentation/vm/numa_memory_policy.txt on the Linux kernel
4186source tree for additional details.
4187
11ae6ed8
EH
4188Setting the @option{discard-data} boolean option to @var{on}
4189indicates that file contents can be destroyed when QEMU exits,
4190to avoid unnecessarily flushing data to the backing file. Note
4191that @option{discard-data} is only an optimization, and QEMU
4192might not discard file contents if it aborts unexpectedly or is
4193terminated using SIGKILL.
b9174d4f 4194
c7cddce1
SH
4195The @option{merge} boolean option enables memory merge, also known as
4196MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
4197memory deduplication.
4198
4199Setting the @option{dump} boolean option to @var{off} excludes the memory from
4200core dumps. This feature is also known as MADV_DONTDUMP.
4201
4202The @option{prealloc} boolean option enables memory preallocation.
4203
4204The @option{host-nodes} option binds the memory range to a list of NUMA host
4205nodes.
4206
4207The @option{policy} option sets the NUMA policy to one of the following values:
4208
4209@table @option
4210@item @var{default}
4211default host policy
4212
4213@item @var{preferred}
4214prefer the given host node list for allocation
4215
4216@item @var{bind}
4217restrict memory allocation to the given host node list
4218
4219@item @var{interleave}
4220interleave memory allocations across the given host node list
4221@end table
4222
98376843
HZ
4223The @option{align} option specifies the base address alignment when
4224QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
4225@option{2M}. Some backend store specified by @option{mem-path}
4226requires an alignment different than the default one used by QEMU, eg
4227the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
4228such cases, users can specify the required alignment via this option.
4229
a4de8552
JH
4230The @option{pmem} option specifies whether the backing file specified
4231by @option{mem-path} is in host persistent memory that can be accessed
4232using the SNIA NVM programming model (e.g. Intel NVDIMM).
4233If @option{pmem} is set to 'on', QEMU will take necessary operations to
4234guarantee the persistence of its own writes to @option{mem-path}
4235(e.g. in vNVDIMM label emulation and live migration).
4236
06329cce 4237@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave}
cd19491a
SH
4238
4239Creates a memory backend object, which can be used to back the guest RAM.
4240Memory backend objects offer more control than the @option{-m} option that is
4241traditionally used to define guest RAM. Please refer to
4242@option{memory-backend-file} for a description of the options.
4243
36ea3979 4244@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size}
dbb9e0f4
MAL
4245
4246Creates an anonymous memory file backend object, which allows QEMU to
4247share the memory with an external process (e.g. when using
4248vhost-user). The memory is allocated with memfd and optional
4249sealing. (Linux only)
4250
4251The @option{seal} option creates a sealed-file, that will block
4252further resizing the memory ('on' by default).
4253
4254The @option{hugetlb} option specify the file to be created resides in
4255the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
4256the @option{hugetlb} option, the @option{hugetlbsize} option specify
4257the hugetlb page size on systems that support multiple hugetlb page
4258sizes (it must be a power of 2 value supported by the system).
4259
4260In some versions of Linux, the @option{hugetlb} option is incompatible
4261with the @option{seal} option (requires at least Linux 4.16).
4262
4263Please refer to @option{memory-backend-file} for a description of the
4264other options.
4265
36ea3979
MAL
4266The @option{share} boolean option is @var{on} by default with memfd.
4267
b9174d4f
DB
4268@item -object rng-random,id=@var{id},filename=@var{/dev/random}
4269
4270Creates a random number generator backend which obtains entropy from
4271a device on the host. The @option{id} parameter is a unique ID that
4272will be used to reference this entropy backend from the @option{virtio-rng}
4273device. The @option{filename} parameter specifies which file to obtain
4274entropy from and if omitted defaults to @option{/dev/random}.
4275
4276@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4277
4278Creates a random number generator backend which obtains entropy from
4279an external daemon running on the host. The @option{id} parameter is
4280a unique ID that will be used to reference this entropy backend from
4281the @option{virtio-rng} device. The @option{chardev} parameter is
4282the unique ID of a character device backend that provides the connection
4283to the RNG daemon.
4284
e00adf6c
DB
4285@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4286
4287Creates a TLS anonymous credentials object, which can be used to provide
4288TLS support on network backends. The @option{id} parameter is a unique
4289ID which network backends will use to access the credentials. The
4290@option{endpoint} is either @option{server} or @option{client} depending
4291on whether the QEMU network backend that uses the credentials will be
4292acting as a client or as a server. If @option{verify-peer} is enabled
4293(the default) then once the handshake is completed, the peer credentials
4294will be verified, though this is a no-op for anonymous credentials.
4295
4296The @var{dir} parameter tells QEMU where to find the credential
4297files. For server endpoints, this directory may contain a file
4298@var{dh-params.pem} providing diffie-hellman parameters to use
4299for the TLS server. If the file is missing, QEMU will generate
4300a set of DH parameters at startup. This is a computationally
4301expensive operation that consumes random pool entropy, so it is
4302recommended that a persistent set of parameters be generated
4303upfront and saved.
4304
e1a6dc91
RJ
4305@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}]
4306
4307Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide
4308TLS support on network backends. The @option{id} parameter is a unique
4309ID which network backends will use to access the credentials. The
4310@option{endpoint} is either @option{server} or @option{client} depending
4311on whether the QEMU network backend that uses the credentials will be
4312acting as a client or as a server. For clients only, @option{username}
4313is the username which will be sent to the server. If omitted
4314it defaults to ``qemu''.
4315
4316The @var{dir} parameter tells QEMU where to find the keys file.
4317It is called ``@var{dir}/keys.psk'' and contains ``username:key''
4318pairs. This file can most easily be created using the GnuTLS
4319@code{psktool} program.
4320
4321For server endpoints, @var{dir} may also contain a file
4322@var{dh-params.pem} providing diffie-hellman parameters to use
4323for the TLS server. If the file is missing, QEMU will generate
4324a set of DH parameters at startup. This is a computationally
4325expensive operation that consumes random pool entropy, so it is
4326recommended that a persistent set of parameters be generated
4327up front and saved.
4328
00e5e9df 4329@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id}
85bcbc78
DB
4330
4331Creates a TLS anonymous credentials object, which can be used to provide
4332TLS support on network backends. The @option{id} parameter is a unique
4333ID which network backends will use to access the credentials. The
4334@option{endpoint} is either @option{server} or @option{client} depending
4335on whether the QEMU network backend that uses the credentials will be
4336acting as a client or as a server. If @option{verify-peer} is enabled
4337(the default) then once the handshake is completed, the peer credentials
4338will be verified. With x509 certificates, this implies that the clients
4339must be provided with valid client certificates too.
4340
4341The @var{dir} parameter tells QEMU where to find the credential
4342files. For server endpoints, this directory may contain a file
4343@var{dh-params.pem} providing diffie-hellman parameters to use
4344for the TLS server. If the file is missing, QEMU will generate
4345a set of DH parameters at startup. This is a computationally
4346expensive operation that consumes random pool entropy, so it is
4347recommended that a persistent set of parameters be generated
4348upfront and saved.
4349
4350For x509 certificate credentials the directory will contain further files
4351providing the x509 certificates. The certificates must be stored
4352in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4353@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4354@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4355
1d7b5b4a
DB
4356For the @var{server-key.pem} and @var{client-key.pem} files which
4357contain sensitive private keys, it is possible to use an encrypted
4358version by providing the @var{passwordid} parameter. This provides
4359the ID of a previously created @code{secret} object containing the
4360password for decryption.
4361
00e5e9df
CF
4362The @var{priority} parameter allows to override the global default
4363priority used by gnutls. This can be useful if the system administrator
4364needs to use a weaker set of crypto priorities for QEMU without
4365potentially forcing the weakness onto all applications. Or conversely
4366if one wants wants a stronger default for QEMU than for all other
4367applications, they can do this through this parameter. Its format is
4368a gnutls priority string as described at
4369@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
4370
338d3f41 4371@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
7dbb11c8
YH
4372
4373Interval @var{t} can't be 0, this filter batches the packet delivery: all
4374packets arriving in a given interval on netdev @var{netdevid} are delayed
4375until the end of the interval. Interval is in microseconds.
338d3f41
HZ
4376@option{status} is optional that indicate whether the netfilter is
4377on (enabled) or off (disabled), the default status for netfilter will be 'on'.
7dbb11c8
YH
4378
4379queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4380
4381@option{all}: the filter is attached both to the receive and the transmit
4382 queue of the netdev (default).
4383
4384@option{rx}: the filter is attached to the receive queue of the netdev,
4385 where it will receive packets sent to the netdev.
4386
4387@option{tx}: the filter is attached to the transmit queue of the netdev,
4388 where it will receive packets sent by the netdev.
4389
e2521f0e 4390@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
f6d3afb5 4391
e2521f0e 4392filter-mirror on netdev @var{netdevid},mirror net packet to chardev@var{chardevid}, if it has the vnet_hdr_support flag, filter-mirror will mirror packet with vnet_hdr_len.
f6d3afb5 4393
00d5c240 4394@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
d46f75b2
ZC
4395
4396filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
00d5c240
ZC
4397@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4398filter-redirector will redirect packet with vnet_hdr_len.
d46f75b2
ZC
4399Create a filter-redirector we need to differ outdev id from indev id, id can not
4400be the same. we can just use indev or outdev, but at least one of indev or outdev
4401need to be specified.
4402
4b39bdce 4403@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support]
e6eee8ab
ZC
4404
4405Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4406secondary from primary to keep secondary tcp connection,and rewrite
4407tcp packet to primary from secondary make tcp packet can be handled by
4b39bdce 4408client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
e6eee8ab
ZC
4409
4410usage:
4411colo secondary:
4412-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4413-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4414-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4415
c551cd52 4416@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
d3e0c032
TH
4417
4418Dump the network traffic on netdev @var{dev} to the file specified by
4419@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4420The file format is libpcap, so it can be analyzed with tools such as tcpdump
4421or Wireshark.
4422
aa3a7032 4423@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid}[,vnet_hdr_support]
7dce4e6f
ZC
4424
4425Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4426secondary packet. If the packets are same, we will output primary
4427packet to outdev@var{chardevid}, else we will notify colo-frame
4428do checkpoint and send primary packet to outdev@var{chardevid}.
aa3a7032 4429if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
7dce4e6f
ZC
4430
4431we must use it with the help of filter-mirror and filter-redirector.
4432
4433@example
4434
4435primary:
4436-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4437-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4438-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4439-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4440-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4441-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4442-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4443-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4444-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4445-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4446-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4447-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4448
4449secondary:
4450-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4451-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4452-chardev socket,id=red0,host=3.3.3.3,port=9003
4453-chardev socket,id=red1,host=3.3.3.3,port=9004
4454-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4455-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4456
4457@end example
4458
4459If you want to know the detail of above command line, you can read
4460the colo-compare git log.
4461
1653a5f3
GA
4462@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4463
4464Creates a cryptodev backend which executes crypto opreation from
4465the QEMU cipher APIS. The @var{id} parameter is
4466a unique ID that will be used to reference this cryptodev backend from
4467the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4468which specify the queue number of cryptodev backend, the default of
4469@var{queues} is 1.
4470
4471@example
4472
4473 # qemu-system-x86_64 \
4474 [...] \
4475 -object cryptodev-backend-builtin,id=cryptodev0 \
4476 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4477 [...]
4478@end example
4479
042cea27
GA
4480@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
4481
4482Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
4483The @var{id} parameter is a unique ID that will be used to reference this
4484cryptodev backend from the @option{virtio-crypto} device.
4485The chardev should be a unix domain socket backed one. The vhost-user uses
4486a specifically defined protocol to pass vhost ioctl replacement messages
4487to an application on the other end of the socket.
4488The @var{queues} parameter is optional, which specify the queue number
4489of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
4490
4491@example
4492
4493 # qemu-system-x86_64 \
4494 [...] \
4495 -chardev socket,id=chardev0,path=/path/to/socket \
4496 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4497 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4498 [...]
4499@end example
4500
ac1d8878
DB
4501@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4502@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4503
4504Defines a secret to store a password, encryption key, or some other sensitive
4505data. The sensitive data can either be passed directly via the @var{data}
4506parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4507parameter is insecure unless the sensitive data is encrypted.
4508
4509The sensitive data can be provided in raw format (the default), or base64.
4510When encoded as JSON, the raw format only supports valid UTF-8 characters,
4511so base64 is recommended for sending binary data. QEMU will convert from
4512which ever format is provided to the format it needs internally. eg, an
4513RBD password can be provided in raw format, even though it will be base64
4514encoded when passed onto the RBD sever.
4515
4516For added protection, it is possible to encrypt the data associated with
4517a secret using the AES-256-CBC cipher. Use of encryption is indicated
4518by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4519parameter provides the ID of a previously defined secret that contains
4520the AES-256 decryption key. This key should be 32-bytes long and be
4521base64 encoded. The @var{iv} parameter provides the random initialization
4522vector used for encryption of this particular secret and should be a
69c0b278 4523base64 encrypted string of the 16-byte IV.
ac1d8878
DB
4524
4525The simplest (insecure) usage is to provide the secret inline
4526
4527@example
4528
4529 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4530
4531@end example
4532
4533The simplest secure usage is to provide the secret via a file
4534
b43671f8 4535 # printf "letmein" > mypasswd.txt
ac1d8878
DB
4536 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4537
4538For greater security, AES-256-CBC should be used. To illustrate usage,
4539consider the openssl command line tool which can encrypt the data. Note
4540that when encrypting, the plaintext must be padded to the cipher block
4541size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4542
4543First a master key needs to be created in base64 encoding:
4544
4545@example
4546 # openssl rand -base64 32 > key.b64
4547 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4548@end example
4549
4550Each secret to be encrypted needs to have a random initialization vector
4551generated. These do not need to be kept secret
4552
4553@example
4554 # openssl rand -base64 16 > iv.b64
4555 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4556@end example
4557
4558The secret to be defined can now be encrypted, in this case we're
4559telling openssl to base64 encode the result, but it could be left
4560as raw bytes if desired.
4561
4562@example
b43671f8 4563 # SECRET=$(printf "letmein" |
ac1d8878
DB
4564 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4565@end example
4566
4567When launching QEMU, create a master secret pointing to @code{key.b64}
4568and specify that to be used to decrypt the user password. Pass the
4569contents of @code{iv.b64} to the second secret
4570
4571@example
4572 # $QEMU \
4573 -object secret,id=secmaster0,format=base64,file=key.b64 \
4574 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4575 data=$SECRET,iv=$(<iv.b64)
4576@end example
4577
a9b4942f
BS
4578@item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}]
4579
4580Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
4581to provide the guest memory encryption support on AMD processors.
4582
4583When memory encryption is enabled, one of the physical address bit (aka the
4584C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
4585is used to provide the C-bit position. The C-bit position is Host family dependent
4586hence user must provide this value. On EPYC, the value should be 47.
4587
4588When memory encryption is enabled, we loose certain bits in physical address space.
4589The @option{reduced-phys-bits} is used to provide the number of bits we loose in
4590physical address space. Similar to C-bit, the value is Host family dependent.
4591On EPYC, the value should be 5.
4592
4593The @option{sev-device} provides the device file to use for communicating with
4594the SEV firmware running inside AMD Secure Processor. The default device is
4595'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
4596created by CCP driver.
4597
4598The @option{policy} provides the guest policy to be enforced by the SEV firmware
4599and restrict what configuration and operational commands can be performed on this
4600guest by the hypervisor. The policy should be provided by the guest owner and is
4601bound to the guest and cannot be changed throughout the lifetime of the guest.
4602The default is 0.
4603
4604If guest @option{policy} allows sharing the key with another SEV guest then
4605@option{handle} can be use to provide handle of the guest from which to share
4606the key.
4607
4608The @option{dh-cert-file} and @option{session-file} provides the guest owner's
4609Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
4610are used for establishing a cryptographic session with the guest owner to
4611negotiate keys used for attestation. The file must be encoded in base64.
4612
4613e.g to launch a SEV guest
4614@example
4615 # $QEMU \
4616 ......
4617 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4618 -machine ...,memory-encryption=sev0
4619 .....
4620
4621@end example
fb5c4ebc
DB
4622
4623
4624@item -object authz-simple,id=@var{id},identity=@var{string}
4625
4626Create an authorization object that will control access to network services.
4627
4628The @option{identity} parameter is identifies the user and its format
4629depends on the network service that authorization object is associated
4630with. For authorizing based on TLS x509 certificates, the identity must
4631be the x509 distinguished name. Note that care must be taken to escape
4632any commas in the distinguished name.
4633
4634An example authorization object to validate a x509 distinguished name
4635would look like:
4636@example
4637 # $QEMU \
4638 ...
4639 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
4640 ...
4641@end example
4642
4643Note the use of quotes due to the x509 distinguished name containing
4644whitespace, and escaping of ','.
4645
55d86984
DB
4646@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no}
4647
4648Create an authorization object that will control access to network services.
4649
4650The @option{filename} parameter is the fully qualified path to a file
4651containing the access control list rules in JSON format.
4652
4653An example set of rules that match against SASL usernames might look
4654like:
4655
4656@example
4657 @{
4658 "rules": [
4659 @{ "match": "fred", "policy": "allow", "format": "exact" @},
4660 @{ "match": "bob", "policy": "allow", "format": "exact" @},
4661 @{ "match": "danb", "policy": "deny", "format": "glob" @},
4662 @{ "match": "dan*", "policy": "allow", "format": "exact" @},
4663 ],
4664 "policy": "deny"
4665 @}
4666@end example
4667
4668When checking access the object will iterate over all the rules and
4669the first rule to match will have its @option{policy} value returned
4670as the result. If no rules match, then the default @option{policy}
4671value is returned.
4672
4673The rules can either be an exact string match, or they can use the
4674simple UNIX glob pattern matching to allow wildcards to be used.
4675
4676If @option{refresh} is set to true the file will be monitored
4677and automatically reloaded whenever its content changes.
4678
4679As with the @code{authz-simple} object, the format of the identity
4680strings being matched depends on the network service, but is usually
4681a TLS x509 distinguished name, or a SASL username.
4682
4683An example authorization object to validate a SASL username
4684would look like:
4685@example
4686 # $QEMU \
4687 ...
4688 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
4689 ...
4690@end example
4691
8953caf3
DB
4692@item -object authz-pam,id=@var{id},service=@var{string}
4693
4694Create an authorization object that will control access to network services.
4695
4696The @option{service} parameter provides the name of a PAM service to use
4697for authorization. It requires that a file @code{/etc/pam.d/@var{service}}
4698exist to provide the configuration for the @code{account} subsystem.
4699
4700An example authorization object to validate a TLS x509 distinguished
4701name would look like:
4702
4703@example
4704 # $QEMU \
4705 ...
4706 -object authz-pam,id=auth0,service=qemu-vnc
4707 ...
4708@end example
4709
4710There would then be a corresponding config file for PAM at
4711@code{/etc/pam.d/qemu-vnc} that contains:
4712
4713@example
4714account requisite pam_listfile.so item=user sense=allow \
4715 file=/etc/qemu/vnc.allow
4716@end example
4717
4718Finally the @code{/etc/qemu/vnc.allow} file would contain
4719the list of x509 distingished names that are permitted
4720access
4721
4722@example
4723CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4724@end example
4725
4726
b9174d4f
DB
4727@end table
4728
4729ETEXI
4730
4731
3dbf2c7f
SW
4732HXCOMM This is the last statement. Insert new options before this line!
4733STEXI
4734@end table
4735ETEXI