blob: f63f7dc946fd7e47c9d2cf1a0df62691b8c65674 [file] [log] [blame]
blueswir15824d652009-03-28 06:44:27 +00001HXCOMM 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
Blue Swirlad960902010-03-29 19:23:52 +00004HXCOMM 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.
blueswir15824d652009-03-28 06:44:27 +00007HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8
Paolo Bonzini43f187a2017-01-04 13:50:37 +01009DEFHEADING(Standard options)
blueswir15824d652009-03-28 06:44:27 +000010STEXI
11@table @option
12ETEXI
13
14DEF("help", 0, QEMU_OPTION_h,
Blue Swirlad960902010-03-29 19:23:52 +000015 "-h or -help display this help and exit\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000016STEXI
17@item -h
Stefan Weil6616b2a2010-02-05 23:52:05 +010018@findex -h
blueswir15824d652009-03-28 06:44:27 +000019Display help and exit
20ETEXI
21
pbrook9bd7e6d2009-04-07 22:58:45 +000022DEF("version", 0, QEMU_OPTION_version,
Blue Swirlad960902010-03-29 19:23:52 +000023 "-version display version information and exit\n", QEMU_ARCH_ALL)
pbrook9bd7e6d2009-04-07 22:58:45 +000024STEXI
25@item -version
Stefan Weil6616b2a2010-02-05 23:52:05 +010026@findex -version
pbrook9bd7e6d2009-04-07 22:58:45 +000027Display version information and exit
28ETEXI
29
Jan Kiszka80f52a62011-07-23 12:39:46 +020030DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31 "-machine [type=]name[,prop[=value][,...]]\n"
Peter Maydell585f6032012-10-04 16:22:01 +010032 " selects emulated machine ('-machine help' for list)\n"
Jan Kiszka80f52a62011-07-23 12:39:46 +020033 " property accel=accel1[:accel2[:...]] selects accelerator\n"
Thomas Huthbde4d922017-05-04 07:24:41 +020034 " supported accelerators are kvm, xen, hax or tcg (default: tcg)\n"
Matt Gingell32c18a22015-11-16 10:03:06 -080035 " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
Don Slutzd1048be2014-11-21 11:18:52 -050036 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
Peter Maydell96404012016-05-10 16:49:29 +010037 " kvm_shadow_mem=size of KVM shadow MMU in bytes\n"
Luiz Capitulino8490fc72012-09-05 16:50:16 -030038 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
Le Tana52a7fd2014-08-16 13:55:40 +080039 " mem-merge=on|off controls memory merge support (default: on)\n"
Tiejun Chen79814172015-07-15 13:37:45 +080040 " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
Tony Krowiak2eb1cd02015-03-12 13:53:51 +010041 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
Alexander Graf9850c602015-02-23 13:56:42 +010042 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
Xiao Guangrong87252e12015-12-02 15:20:58 +080043 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
Greg Kurz902c0532016-02-18 12:32:25 +010044 " nvdimm=on|off controls NVDIMM support (default=off)\n"
45 " enforce-config-section=on|off enforce configuration section migration (default=off)\n",
Jan Kiszka80f52a62011-07-23 12:39:46 +020046 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000047STEXI
Jan Kiszka80f52a62011-07-23 12:39:46 +020048@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
49@findex -machine
Peter Maydell585f6032012-10-04 16:22:01 +010050Select the emulated machine by @var{name}. Use @code{-machine help} to list
Jan Kiszka80f52a62011-07-23 12:39:46 +020051available machines. Supported machine properties are:
52@table @option
53@item accel=@var{accels1}[:@var{accels2}[:...]]
54This is used to enable an accelerator. Depending on the target architecture,
Thomas Huthbde4d922017-05-04 07:24:41 +020055kvm, xen, hax or tcg can be available. By default, tcg is used. If there is
56more than one accelerator specified, the next one is used if the previous one
57fails to initialize.
Jan Kiszka6a48ffa2011-10-15 13:43:48 +020058@item kernel_irqchip=on|off
Matt Gingell32c18a22015-11-16 10:03:06 -080059Controls in-kernel irqchip support for the chosen accelerator when available.
Tiejun Chen79814172015-07-15 13:37:45 +080060@item gfx_passthru=on|off
61Enables IGD GFX passthrough support for the chosen machine when available.
Don Slutzd1048be2014-11-21 11:18:52 -050062@item vmport=on|off|auto
63Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
64value based on accel. For accel=xen the default is off otherwise the default
65is on.
Jan Kiszka39d69602012-01-25 18:14:15 +010066@item kvm_shadow_mem=size
67Defines the size of the KVM shadow MMU.
Jason Baronddb97f12012-08-02 15:44:16 -040068@item dump-guest-core=on|off
69Include guest memory in a core dump. The default is on.
Luiz Capitulino8490fc72012-09-05 16:50:16 -030070@item mem-merge=on|off
71Enables or disables memory merge support. This feature, when supported by
72the host, de-duplicates identical memory pages among VMs instances
73(enabled by default).
Tony Krowiak2eb1cd02015-03-12 13:53:51 +010074@item aes-key-wrap=on|off
75Enables or disables AES key wrapping support on s390-ccw hosts. This feature
76controls whether AES wrapping keys will be created to allow
77execution of AES cryptographic functions. The default is on.
78@item dea-key-wrap=on|off
79Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
80controls whether DEA wrapping keys will be created to allow
81execution of DEA cryptographic functions. The default is on.
Xiao Guangrong87252e12015-12-02 15:20:58 +080082@item nvdimm=on|off
83Enables or disables NVDIMM support. The default is off.
Jan Kiszka80f52a62011-07-23 12:39:46 +020084@end table
blueswir15824d652009-03-28 06:44:27 +000085ETEXI
86
Jan Kiszka80f52a62011-07-23 12:39:46 +020087HXCOMM Deprecated by -machine
88DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
89
blueswir15824d652009-03-28 06:44:27 +000090DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
Peter Maydell585f6032012-10-04 16:22:01 +010091 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000092STEXI
93@item -cpu @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +010094@findex -cpu
Peter Maydell585f6032012-10-04 16:22:01 +010095Select CPU model (@code{-cpu help} for list and additional feature selection)
blueswir15824d652009-03-28 06:44:27 +000096ETEXI
97
KONRAD Frederic8d4e9142017-02-23 18:29:08 +000098DEF("accel", HAS_ARG, QEMU_OPTION_accel,
99 "-accel [accel=]accelerator[,thread=single|multi]\n"
Thomas Huthbde4d922017-05-04 07:24:41 +0200100 " select accelerator (kvm, xen, hax or tcg; use 'help' for a list)\n"
101 " thread=single|multi (enable multi-threaded TCG)", QEMU_ARCH_ALL)
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000102STEXI
103@item -accel @var{name}[,prop=@var{value}[,...]]
104@findex -accel
105This is used to enable an accelerator. Depending on the target architecture,
Thomas Huthbde4d922017-05-04 07:24:41 +0200106kvm, xen, hax or tcg can be available. By default, tcg is used. If there is
107more than one accelerator specified, the next one is used if the previous one
108fails to initialize.
KONRAD Frederic8d4e9142017-02-23 18:29:08 +0000109@table @option
110@item thread=single|multi
111Controls number of TCG threads. When the TCG is multi-threaded there will be one
112thread per vCPU therefor taking advantage of additional host cores. The default
113is to enable multi-threading where both the back-end and front-ends support it and
114no incompatible TCG features have been enabled (e.g. icount/replay).
115@end table
116ETEXI
117
blueswir15824d652009-03-28 06:44:27 +0000118DEF("smp", HAS_ARG, QEMU_OPTION_smp,
Michael Tokarev12b7f572013-06-24 15:06:52 +0400119 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
Jes Sorensen6be68d72009-07-23 17:03:42 +0200120 " set the number of CPUs to 'n' [default=1]\n"
121 " maxcpus= maximum number of total cpus, including\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -0700122 " offline CPUs for hotplug, etc\n"
Andre Przywara58a04db2009-08-28 10:49:57 +0200123 " cores= number of CPU cores on one socket\n"
124 " threads= number of threads on one CPU core\n"
Blue Swirlad960902010-03-29 19:23:52 +0000125 " sockets= number of discrete sockets in the system\n",
126 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000127STEXI
Michael Tokarev12b7f572013-06-24 15:06:52 +0400128@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100129@findex -smp
blueswir15824d652009-03-28 06:44:27 +0000130Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
131CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
132to 4.
Andre Przywara58a04db2009-08-28 10:49:57 +0200133For the PC target, the number of @var{cores} per socket, the number
134of @var{threads} per cores and the total number of @var{sockets} can be
135specified. Missing values will be computed. If any on the three values is
136given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
137specifies the maximum number of hotpluggable CPUs.
blueswir15824d652009-03-28 06:44:27 +0000138ETEXI
139
aliguori268a3622009-04-21 22:30:27 +0000140DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200141 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
He Chen0f203432017-04-27 10:35:58 +0800142 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
143 "-numa dist,src=source,dst=destination,val=distance\n", QEMU_ARCH_ALL)
aliguori268a3622009-04-21 22:30:27 +0000144STEXI
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200145@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
146@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
He Chen0f203432017-04-27 10:35:58 +0800147@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
Igor Mammedov419fcde2017-05-10 13:30:01 +0200148@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100149@findex -numa
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200150Define a NUMA node and assign RAM and VCPUs to it.
He Chen0f203432017-04-27 10:35:58 +0800151Set the NUMA distance from a source node to a destination node.
Paolo Bonzini7febe362014-05-14 17:43:17 +0800152
Igor Mammedov419fcde2017-05-10 13:30:01 +0200153Legacy VCPU assignment uses @samp{cpus} option where
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200154@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
155@samp{cpus} option represent a contiguous range of CPU indexes
156(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
157set of VCPUs can be represented by providing multiple @samp{cpus}
158options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
159split between them.
160
161For example, the following option assigns VCPUs 0, 1, 2 and 5 to
162a NUMA node:
163@example
164-numa node,cpus=0-2,cpus=5
165@end example
166
Igor Mammedov419fcde2017-05-10 13:30:01 +0200167@samp{cpu} option is a new alternative to @samp{cpus} option
168which uses @samp{socket-id|core-id|thread-id} properties to assign
169CPU objects to a @var{node} using topology layout properties of CPU.
170The set of properties is machine specific, and depends on used
171machine type/@samp{smp} options. It could be queried with
172@samp{hotpluggable-cpus} monitor command.
173@samp{node-id} property specifies @var{node} to which CPU object
174will be assigned, it's required for @var{node} to be declared
175with @samp{node} option before it's used with @samp{cpu} option.
176
177For example:
178@example
179-M pc \
180-smp 1,sockets=2,maxcpus=2 \
181-numa node,nodeid=0 -numa node,nodeid=1 \
182-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
183@end example
184
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200185@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
186assigns RAM from a given memory backend device to a node. If
187@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
188split equally between them.
189
190@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
191if one node uses @samp{memdev}, all of them have to use it.
192
He Chen0f203432017-04-27 10:35:58 +0800193@var{source} and @var{destination} are NUMA node IDs.
194@var{distance} is the NUMA distance from @var{source} to @var{destination}.
195The distance from a node to itself is always 10. If any pair of nodes is
196given a distance, then all pairs must be given distances. Although, when
197distances are only given in one direction for each pair of nodes, then
198the distances in the opposite directions are assumed to be the same. If,
199however, an asymmetrical pair of distances is given for even one node
200pair, then all node pairs must be provided distance values for both
201directions, even when they are symmetrical. When a node is unreachable
202from another node, set the pair's distance to 255.
203
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200204Note that the -@option{numa} option doesn't allocate any of the
205specified resources, it just assigns existing resources to NUMA
206nodes. This means that one still has to use the @option{-m},
207@option{-smp} options to allocate RAM and VCPUs respectively.
208
aliguori268a3622009-04-21 22:30:27 +0000209ETEXI
210
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100211DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
212 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
213 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
214STEXI
215@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
216@findex -add-fd
217
218Add a file descriptor to an fd set. Valid options are:
219
220@table @option
221@item fd=@var{fd}
222This option defines the file descriptor of which a duplicate is added to fd set.
223The file descriptor cannot be stdin, stdout, or stderr.
224@item set=@var{set}
225This option defines the ID of the fd set to add the file descriptor to.
226@item opaque=@var{opaque}
227This option defines a free-form string that can be used to describe @var{fd}.
228@end table
229
230You can open an image using pre-opened file descriptors from an fd set:
231@example
232qemu-system-i386
233-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
234-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
235-drive file=/dev/fdset/2,index=0,media=disk
236@end example
237ETEXI
238
239DEF("set", HAS_ARG, QEMU_OPTION_set,
240 "-set group.id.arg=value\n"
241 " set <arg> parameter for item <id> of type <group>\n"
242 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
243STEXI
244@item -set @var{group}.@var{id}.@var{arg}=@var{value}
245@findex -set
Michael Tokareve1f3b972016-10-16 17:21:37 +0300246Set parameter @var{arg} for item @var{id} of type @var{group}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100247ETEXI
248
249DEF("global", HAS_ARG, QEMU_OPTION_global,
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200250 "-global driver.property=value\n"
251 "-global driver=driver,property=property,value=value\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100252 " set a global default for a driver property\n",
253 QEMU_ARCH_ALL)
254STEXI
255@item -global @var{driver}.@var{prop}=@var{value}
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200256@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100257@findex -global
258Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
259
260@example
261qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
262@end example
263
264In particular, you can use this to set driver properties for devices which are
265created automatically by the machine model. To create a device which is not
266created automatically and set properties on it, use -@option{device}.
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200267
Markus Armbrusterae08fd52015-06-15 14:35:58 +0200268-global @var{driver}.@var{prop}=@var{value} is shorthand for -global
269driver=@var{driver},property=@var{prop},value=@var{value}. The
270longhand syntax works even when @var{driver} contains a dot.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100271ETEXI
272
273DEF("boot", HAS_ARG, QEMU_OPTION_boot,
274 "-boot [order=drives][,once=drives][,menu=on|off]\n"
Amos Kongc8a6ae82013-03-19 14:23:27 +0800275 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100276 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
277 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
278 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
279 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
280 QEMU_ARCH_ALL)
281STEXI
Amos Kongc8a6ae82013-03-19 14:23:27 +0800282@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]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100283@findex -boot
284Specify boot order @var{drives} as a string of drive letters. Valid
Gongleid274e072015-07-03 17:50:57 +0800285drive letters depend on the target architecture. The x86 PC uses: a, b
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100286(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
287from network adapter 1-4), hard disk boot is the default. To apply a
288particular boot order only on the first startup, specify it via
Thomas Huthc0d9f7d2017-02-28 18:40:01 +0100289@option{once}. Note that the @option{order} or @option{once} parameter
290should not be used together with the @option{bootindex} property of
291devices, since the firmware implementations normally do not support both
292at the same time.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100293
294Interactive boot menus/prompts can be enabled via @option{menu=on} as far
295as firmware/BIOS supports them. The default is non-interactive boot.
296
297A splash picture could be passed to bios, enabling user to show it as logo,
298when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
299supports them. Currently Seabios for X86 system support it.
300limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
301format(true color). The resolution should be supported by the SVGA mode, so
302the recommended is 320x240, 640x480, 800x640.
303
304A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
305when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
306reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
307system support it.
308
Amos Kongc8a6ae82013-03-19 14:23:27 +0800309Do strict boot via @option{strict=on} as far as firmware/BIOS
310supports it. This only effects when boot priority is changed by
311bootindex options. The default is non-strict boot.
312
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100313@example
314# try to boot from network first, then from hard disk
315qemu-system-i386 -boot order=nc
316# boot from CD-ROM first, switch back to default order after reboot
317qemu-system-i386 -boot once=d
318# boot with a splash picture for 5 seconds.
319qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
320@end example
321
322Note: The legacy format '-boot @var{drives}' is still supported but its
323use is discouraged as it may be removed from future versions.
324ETEXI
325
326DEF("m", HAS_ARG, QEMU_OPTION_m,
Michael Tokarev89f3ea22016-11-10 17:51:32 +0300327 "-m [size=]megs[,slots=n,maxmem=size]\n"
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100328 " configure guest RAM\n"
Alexander Graf0daba1f2015-06-05 11:05:03 +0200329 " size: initial amount of guest memory\n"
Igor Mammedovc270fb92014-06-02 15:25:02 +0200330 " slots: number of hotplug slots (default: none)\n"
Matthew Rosatob6fe0122014-08-28 11:25:33 -0400331 " maxmem: maximum amount of guest memory (default: none)\n"
332 "NOTE: Some architectures might enforce a specific granularity\n",
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100333 QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100334STEXI
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500335@item -m [size=]@var{megs}[,slots=n,maxmem=size]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100336@findex -m
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500337Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
338Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
339megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
340could be used to set amount of hotpluggable memory slots and maximum amount of
341memory. Note that @var{maxmem} must be aligned to the page size.
342
343For example, the following command-line sets the guest startup RAM size to
3441GB, creates 3 slots to hotplug additional memory and sets the maximum
345memory the guest can reach to 4GB:
346
347@example
348qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
349@end example
350
351If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
352be enabled and the guest startup RAM will never increase.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100353ETEXI
354
355DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
356 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
357STEXI
358@item -mem-path @var{path}
359@findex -mem-path
360Allocate guest RAM from a temporarily created file in @var{path}.
361ETEXI
362
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100363DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
364 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
365 QEMU_ARCH_ALL)
366STEXI
367@item -mem-prealloc
368@findex -mem-prealloc
369Preallocate memory when using -mem-path.
370ETEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100371
372DEF("k", HAS_ARG, QEMU_OPTION_k,
373 "-k language use keyboard layout (for example 'fr' for French)\n",
374 QEMU_ARCH_ALL)
375STEXI
376@item -k @var{language}
377@findex -k
378Use keyboard layout @var{language} (for example @code{fr} for
379French). This option is only needed where it is not easy to get raw PC
Samuel Thibault32945472016-06-22 17:48:31 +0200380keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100381display). You don't normally need to use it on PC/Linux or PC/Windows
382hosts.
383
384The available layouts are:
385@example
386ar de-ch es fo fr-ca hu ja mk no pt-br sv
387da en-gb et fr fr-ch is lt nl pl ru th
388de en-us fi fr-be hr it lv nl-be pt sl tr
389@end example
390
391The default is @code{en-us}.
392ETEXI
393
394
395DEF("audio-help", 0, QEMU_OPTION_audio_help,
396 "-audio-help print list of audio drivers and their options\n",
397 QEMU_ARCH_ALL)
398STEXI
399@item -audio-help
400@findex -audio-help
401Will show the audio subsystem help: list of drivers, tunable
402parameters.
403ETEXI
404
405DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
406 "-soundhw c1,... enable audio support\n"
407 " and only specified sound cards (comma separated list)\n"
408 " use '-soundhw help' to get the list of supported cards\n"
409 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
410STEXI
411@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
412@findex -soundhw
413Enable audio and selected sound hardware. Use 'help' to print all
414available sound hardware.
415
416@example
417qemu-system-i386 -soundhw sb16,adlib disk.img
418qemu-system-i386 -soundhw es1370 disk.img
419qemu-system-i386 -soundhw ac97 disk.img
420qemu-system-i386 -soundhw hda disk.img
421qemu-system-i386 -soundhw all disk.img
422qemu-system-i386 -soundhw help
423@end example
424
425Note that Linux's i810_audio OSS kernel (for AC97) module might
426require manually specifying clocking.
427
428@example
429modprobe i810_audio clocking=48000
430@end example
431ETEXI
432
433DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
434 "-balloon none disable balloon device\n"
435 "-balloon virtio[,addr=str]\n"
436 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
437STEXI
438@item -balloon none
439@findex -balloon
440Disable balloon device.
441@item -balloon virtio[,addr=@var{addr}]
442Enable virtio balloon device (default), optionally with PCI address
443@var{addr}.
444ETEXI
445
446DEF("device", HAS_ARG, QEMU_OPTION_device,
447 "-device driver[,prop[=value][,...]]\n"
448 " add device (based on driver)\n"
449 " prop=value,... sets driver properties\n"
450 " use '-device help' to print all possible drivers\n"
451 " use '-device driver,help' to print all possible properties\n",
452 QEMU_ARCH_ALL)
453STEXI
454@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
455@findex -device
456Add device @var{driver}. @var{prop}=@var{value} sets driver
457properties. Valid properties depend on the driver. To get help on
458possible drivers and properties, use @code{-device help} and
459@code{-device @var{driver},help}.
Corey Minyardf8490452015-12-17 12:50:10 -0600460
461Some drivers are:
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200462@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
Corey Minyardf8490452015-12-17 12:50:10 -0600463
464Add an IPMI BMC. This is a simulation of a hardware management
465interface processor that normally sits on a system. It provides
466a watchdog and the ability to reset and power control the system.
467You need to connect this to an IPMI interface to make it useful
468
469The IPMI slave address to use for the BMC. The default is 0x20.
470This address is the BMC's address on the I2C network of management
471controllers. If you don't know what this means, it is safe to ignore
472it.
473
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200474@table @option
475@item bmc=@var{id}
476The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
477@item slave_addr=@var{val}
478Define slave address to use for the BMC. The default is 0x20.
479@item sdrfile=@var{file}
Cédric Le Goater540c07d2017-04-05 14:41:32 +0200480file containing raw Sensor Data Records (SDR) data. The default is none.
481@item fruareasize=@var{val}
482size of a Field Replaceable Unit (FRU) area. The default is 1024.
483@item frudatafile=@var{file}
484file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
Cédric Le Goater8c6fd7f2017-04-05 14:41:31 +0200485@end table
486
Corey Minyardf8490452015-12-17 12:50:10 -0600487@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
488
489Add a connection to an external IPMI BMC simulator. Instead of
490locally emulating the BMC like the above item, instead connect
491to an external entity that provides the IPMI services.
492
493A connection is made to an external BMC simulator. If you do this, it
494is strongly recommended that you use the "reconnect=" chardev option
495to reconnect to the simulator if the connection is lost. Note that if
496this is not used carefully, it can be a security issue, as the
497interface has the ability to send resets, NMIs, and power off the VM.
498It's best if QEMU makes a connection to an external simulator running
499on a secure port on localhost, so neither the simulator nor QEMU is
500exposed to any outside network.
501
502See the "lanserv/README.vm" file in the OpenIPMI library for more
503details on the external interface.
504
505@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
506
507Add a KCS IPMI interafce on the ISA bus. This also adds a
508corresponding ACPI and SMBIOS entries, if appropriate.
509
510@table @option
511@item bmc=@var{id}
512The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
513@item ioport=@var{val}
514Define the I/O address of the interface. The default is 0xca0 for KCS.
515@item irq=@var{val}
516Define the interrupt to use. The default is 5. To disable interrupts,
517set this to 0.
518@end table
519
520@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
521
522Like the KCS interface, but defines a BT interface. The default port is
5230xe4 and the default interrupt is 5.
524
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100525ETEXI
526
527DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000528 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100529 " set the name of the guest\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000530 " string1 sets the window title and string2 the process name (on Linux)\n"
531 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
532 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100533 QEMU_ARCH_ALL)
534STEXI
535@item -name @var{name}
536@findex -name
537Sets the @var{name} of the guest.
538This name will be displayed in the SDL window caption.
539The @var{name} will also be used for the VNC server.
540Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000541Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100542ETEXI
543
544DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
545 "-uuid %08x-%04x-%04x-%04x-%012x\n"
546 " specify machine UUID\n", QEMU_ARCH_ALL)
547STEXI
548@item -uuid @var{uuid}
549@findex -uuid
550Set system UUID.
551ETEXI
552
553STEXI
554@end table
555ETEXI
556DEFHEADING()
557
Paolo Bonzini43f187a2017-01-04 13:50:37 +0100558DEFHEADING(Block device options)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100559STEXI
560@table @option
561ETEXI
562
blueswir15824d652009-03-28 06:44:27 +0000563DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000564 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
565DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000566STEXI
567@item -fda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200568@itemx -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100569@findex -fda
570@findex -fdb
Markus Armbruster92a539d2015-03-17 17:02:20 +0100571Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
blueswir15824d652009-03-28 06:44:27 +0000572ETEXI
573
574DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000575 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
576DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000577DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000578 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
579DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000580STEXI
581@item -hda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200582@itemx -hdb @var{file}
583@itemx -hdc @var{file}
584@itemx -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100585@findex -hda
586@findex -hdb
587@findex -hdc
588@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000589Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
590ETEXI
591
592DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000593 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
594 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000595STEXI
596@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100597@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000598Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
599@option{-cdrom} at the same time). You can use the host CD-ROM by
600using @file{/dev/cdrom} as filename (@pxref{host_drives}).
601ETEXI
602
Markus Armbruster42e5f392017-02-28 22:27:07 +0100603DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
604 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
605 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
606 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
607 " [,driver specific parameters...]\n"
608 " configure a block backend\n", QEMU_ARCH_ALL)
609
blueswir15824d652009-03-28 06:44:27 +0000610DEF("drive", HAS_ARG, QEMU_OPTION_drive,
611 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
612 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100613 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +0200614 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
615 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000616 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +0200617 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +0200618 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
619 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
620 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
621 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +0200622 " [[,iops_size=is]]\n"
Alberto Garcia76f4afb2015-06-08 18:17:44 +0200623 " [[,group=g]]\n"
Blue Swirlad960902010-03-29 19:23:52 +0000624 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000625STEXI
626@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100627@findex -drive
blueswir15824d652009-03-28 06:44:27 +0000628
629Define a new drive. Valid options are:
630
Kevin Wolfb3f046c2009-10-09 10:58:35 +0200631@table @option
blueswir15824d652009-03-28 06:44:27 +0000632@item file=@var{file}
633This option defines which disk image (@pxref{disk_images}) to use with
634this drive. If the filename contains comma, you must double it
635(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +1100636
637Special files such as iSCSI devices can be specified using protocol
638specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +0000639@item if=@var{interface}
640This option defines on which type on interface the drive is connected.
Craig Jellicked1fcd02017-03-17 08:49:55 -0700641Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
blueswir15824d652009-03-28 06:44:27 +0000642@item bus=@var{bus},unit=@var{unit}
643These options define where is connected the drive by defining the bus number and
644the unit id.
645@item index=@var{index}
646This option defines where is connected the drive by using an index in the list
647of available connectors of a given interface type.
648@item media=@var{media}
649This option defines the type of the media: disk or cdrom.
650@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
651These options have the same definition as they have in @option{-hdachs}.
652@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +0400653@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
654(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +0000655@item cache=@var{cache}
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100656@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data.
Christoph Hellwig5c6c3a62009-08-20 16:58:35 +0200657@item aio=@var{aio}
658@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
Paolo Bonzinia9384af2013-02-08 14:06:12 +0100659@item discard=@var{discard}
660@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are ignored or passed to the filesystem. Some machine types may not support discard requests.
blueswir15824d652009-03-28 06:44:27 +0000661@item format=@var{format}
662Specify which disk @var{format} will be used rather than detecting
Michael Tokarevd33c8a72016-05-18 15:47:53 +0300663the format. Can be used to specify format=raw to avoid interpreting
blueswir15824d652009-03-28 06:44:27 +0000664an untrusted format header.
665@item serial=@var{serial}
666This option specifies the serial number to assign to the device.
Markus Armbrusterc2cc47a2009-06-18 15:14:10 +0200667@item addr=@var{addr}
668Specify the controller's PCI address (if=virtio only).
Luiz Capitulinoae73e592011-07-12 17:35:08 -0300669@item werror=@var{action},rerror=@var{action}
670Specify which @var{action} to take on write and read errors. Valid actions are:
671"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
672"report" (report the error to the guest), "enospc" (pause QEMU only if the
673host disk is full; report the error to the guest otherwise).
674The default setting is @option{werror=enospc} and @option{rerror=report}.
675@item readonly
676Open drive @option{file} as read-only. Guest write attempts will fail.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000677@item copy-on-read=@var{copy-on-read}
678@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
679file sectors into the image file.
Peter Lieven465bee12014-05-18 00:58:19 +0200680@item detect-zeroes=@var{detect-zeroes}
681@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
682conversion of plain zero writes by the OS to driver specific optimized
683zero write commands. You may even choose "unmap" if @var{discard} is set
684to "unmap" to allow a zero write to be converted to an UNMAP operation.
Stefan Hajnoczi01f9cfa2017-03-01 11:50:24 +0000685@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
686Specify bandwidth throttling limits in bytes per second, either for all request
687types or for reads or writes only. Small values can lead to timeouts or hangs
688inside the guest. A safe minimum for disks is 2 MB/s.
689@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
690Specify bursts in bytes per second, either for all request types or for reads
691or writes only. Bursts allow the guest I/O to spike above the limit
692temporarily.
693@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
694Specify request rate limits in requests per second, either for all request
695types or for reads or writes only.
696@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
697Specify bursts in requests per second, either for all request types or for reads
698or writes only. Bursts allow the guest I/O to spike above the limit
699temporarily.
700@item iops_size=@var{is}
701Let every @var{is} bytes of a request count as a new request for iops
702throttling purposes. Use this option to prevent guests from circumventing iops
703limits by sending fewer but larger requests.
704@item group=@var{g}
705Join a throttling quota group with given name @var{g}. All drives that are
706members of the same group are accounted for together. Use this option to
707prevent guests from circumventing throttling limits by using many small disks
708instead of a single larger disk.
blueswir15824d652009-03-28 06:44:27 +0000709@end table
710
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100711By default, the @option{cache=writeback} mode is used. It will report data
712writes as completed as soon as the data is present in the host page cache.
713This is safe as long as your guest OS makes sure to correctly flush disk caches
714where needed. If your guest OS does not handle volatile disk write caches
715correctly and your host crashes or loses power, then the guest may experience
716data corruption.
blueswir15824d652009-03-28 06:44:27 +0000717
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100718For such guests, you should consider using @option{cache=writethrough}. This
719means that the host page cache will be used to read and write data, but write
720notification will be sent to the guest only after QEMU has made sure to flush
721each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +0000722
Aurelien Jarnoc304d312009-05-03 23:29:14 +0200723The host page cache can be avoided entirely with @option{cache=none}. This will
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100724attempt to do disk IO directly to the guest's memory. QEMU may still perform
725an internal copy of the data. Note that this is considered a writeback mode and
726the guest OS must handle the disk write cache correctly in order to avoid data
727corruption on host crashes.
blueswir15824d652009-03-28 06:44:27 +0000728
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100729The host page cache can be avoided while only sending write notifications to
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100730the guest when the data has been flushed to the disk using
731@option{cache=directsync}.
blueswir15824d652009-03-28 06:44:27 +0000732
Alexander Graf016f5cf2010-05-26 17:51:49 +0200733In case you don't care about data integrity over host failures, use
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100734@option{cache=unsafe}. This option tells QEMU that it never needs to write any
735data to the disk but can instead keep things in cache. If anything goes wrong,
Stefan Weile7d81002011-12-10 00:19:46 +0100736like your host losing power, the disk storage getting disconnected accidentally,
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100737etc. your image will most probably be rendered unusable. When using
Alexander Grafc3177282010-05-26 21:04:32 +0200738the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +0200739
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000740Copy-on-read avoids accessing the same backing file sectors repeatedly and is
741useful when the backing file is over a slow network. By default copy-on-read
742is off.
743
blueswir15824d652009-03-28 06:44:27 +0000744Instead of @option{-cdrom} you can use:
745@example
Stefan Weil3804da92012-05-11 22:21:50 +0200746qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000747@end example
748
749Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
750use:
751@example
Stefan Weil3804da92012-05-11 22:21:50 +0200752qemu-system-i386 -drive file=file,index=0,media=disk
753qemu-system-i386 -drive file=file,index=1,media=disk
754qemu-system-i386 -drive file=file,index=2,media=disk
755qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +0000756@end example
757
Corey Bryant587ed6b2012-10-18 15:19:34 -0400758You can open an image using pre-opened file descriptors from an fd set:
759@example
760qemu-system-i386
761-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
762-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
763-drive file=/dev/fdset/2,index=0,media=disk
764@end example
765
blueswir15824d652009-03-28 06:44:27 +0000766You can connect a CDROM to the slave of ide0:
767@example
Stefan Weil3804da92012-05-11 22:21:50 +0200768qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000769@end example
770
771If you don't specify the "file=" argument, you define an empty drive:
772@example
Stefan Weil3804da92012-05-11 22:21:50 +0200773qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000774@end example
775
blueswir15824d652009-03-28 06:44:27 +0000776Instead of @option{-fda}, @option{-fdb}, you can use:
777@example
Stefan Weil3804da92012-05-11 22:21:50 +0200778qemu-system-i386 -drive file=file,index=0,if=floppy
779qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +0000780@end example
781
782By default, @var{interface} is "ide" and @var{index} is automatically
783incremented:
784@example
Stefan Weil3804da92012-05-11 22:21:50 +0200785qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +0000786@end example
787is interpreted like:
788@example
Stefan Weil3804da92012-05-11 22:21:50 +0200789qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +0000790@end example
791ETEXI
792
793DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +0000794 "-mtdblock file use 'file' as on-board Flash memory image\n",
795 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000796STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200797@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100798@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +0200799Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +0000800ETEXI
801
802DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +0000803 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000804STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200805@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100806@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +0200807Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +0000808ETEXI
809
810DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +0000811 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000812STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200813@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100814@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +0200815Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +0000816ETEXI
817
blueswir15824d652009-03-28 06:44:27 +0000818DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +0000819 "-snapshot write to temporary files instead of disk image files\n",
820 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000821STEXI
822@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +0100823@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +0000824Write to temporary files instead of disk image files. In this case,
825the raw disk image you use is not written back. You can however force
826the write back by pressing @key{C-a s} (@pxref{disk_images}).
827ETEXI
828
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100829DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
830 "-hdachs c,h,s[,t]\n" \
831 " force hard disk 0 physical geometry and the optional BIOS\n" \
832 " translation (t=none or lba) (usually QEMU can guess them)\n",
Blue Swirlad960902010-03-29 19:23:52 +0000833 QEMU_ARCH_ALL)
Marcelo Tosattic9027602010-03-01 20:25:08 -0300834STEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100835@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
836@findex -hdachs
837Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
838@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
839translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
Thomas Huthaab9e872017-04-27 07:20:54 +0200840all those parameters. This option is deprecated, please use
841@code{-device ide-hd,cyls=c,heads=h,secs=s,...} instead.
Markus Armbrusterc70a01e2013-02-13 19:49:40 +0100842ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530843
844DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530845 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
Pradeep Jagadeeshb8bbdb82017-02-28 10:31:46 +0100846 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n"
847 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
848 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
849 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
850 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
851 " [[,throttling.iops-size=is]]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530852 QEMU_ARCH_ALL)
853
854STEXI
855
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530856@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}]
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530857@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530858Define a new file system device. Valid options are:
859@table @option
860@item @var{fsdriver}
861This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530862Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530863@item id=@var{id}
864Specifies identifier for this device
865@item path=@var{path}
866Specifies the export path for the file system device. Files under
867this path will be available to the 9p client on the guest.
868@item security_model=@var{security_model}
869Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530870Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530871In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200872credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530873to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530874attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530875file attributes. For "mapped-file" these attributes are stored in the
876hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530877interact with other unix tools. "none" security model is same as
878passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530879set file attributes like ownership. Security model is mandatory
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530880only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530881security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530882@item writeout=@var{writeout}
883This is an optional argument. The only supported value is "immediate".
884This means that host page cache will be used to read and write data but
885write notification will be sent to the guest only when the data has been
886reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +0530887@item readonly
888Enables exporting 9p share as a readonly mount for guests. By default
889read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530890@item socket=@var{socket}
891Enables proxy filesystem driver to use passed socket file for communicating
892with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530893@item sock_fd=@var{sock_fd}
894Enables proxy filesystem driver to use passed socket descriptor for
895communicating with virtfs-proxy-helper. Usually a helper like libvirt
896will create socketpair and pass one of the fds as sock_fd
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530897@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530898
899-fsdev option is used along with -device driver "virtio-9p-pci".
900@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
901Options for virtio-9p-pci driver are:
902@table @option
903@item fsdev=@var{id}
904Specifies the id value specified along with -fsdev option
905@item mount_tag=@var{mount_tag}
906Specifies the tag name to be used by the guest to mount this export point
907@end table
908
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530909ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530910
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530911DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530912 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
Chris Webb3baa0a62011-11-24 17:05:18 +0000913 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530914 QEMU_ARCH_ALL)
915
916STEXI
917
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530918@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}]
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530919@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530920
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530921The general form of a Virtual File system pass-through options are:
922@table @option
923@item @var{fsdriver}
924This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530925Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530926@item id=@var{id}
927Specifies identifier for this device
928@item path=@var{path}
929Specifies the export path for the file system device. Files under
930this path will be available to the 9p client on the guest.
931@item security_model=@var{security_model}
932Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530933Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530934In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200935credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530936to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530937attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530938file attributes. For "mapped-file" these attributes are stored in the
939hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530940interact with other unix tools. "none" security model is same as
941passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530942set file attributes like ownership. Security model is mandatory only
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530943for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530944model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530945@item writeout=@var{writeout}
946This is an optional argument. The only supported value is "immediate".
947This means that host page cache will be used to read and write data but
948write notification will be sent to the guest only when the data has been
949reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +0530950@item readonly
951Enables exporting 9p share as a readonly mount for guests. By default
952read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530953@item socket=@var{socket}
954Enables proxy filesystem driver to use passed socket file for
955communicating with virtfs-proxy-helper. Usually a helper like libvirt
956will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530957@item sock_fd
958Enables proxy filesystem driver to use passed 'sock_fd' as the socket
959descriptor for interfacing with virtfs-proxy-helper
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530960@end table
961ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530962
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +0530963DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
964 "-virtfs_synth Create synthetic file system image\n",
965 QEMU_ARCH_ALL)
966STEXI
967@item -virtfs_synth
968@findex -virtfs_synth
969Create synthetic file system image
970ETEXI
971
blueswir15824d652009-03-28 06:44:27 +0000972STEXI
973@end table
974ETEXI
blueswir15824d652009-03-28 06:44:27 +0000975DEFHEADING()
976
Paolo Bonzini43f187a2017-01-04 13:50:37 +0100977DEFHEADING(USB options)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100978STEXI
979@table @option
980ETEXI
981
982DEF("usb", 0, QEMU_OPTION_usb,
983 "-usb enable the USB driver (will be the default soon)\n",
984 QEMU_ARCH_ALL)
985STEXI
986@item -usb
987@findex -usb
988Enable the USB driver (will be the default soon)
989ETEXI
990
991DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
992 "-usbdevice name add the host or guest USB device 'name'\n",
993 QEMU_ARCH_ALL)
994STEXI
995
996@item -usbdevice @var{devname}
997@findex -usbdevice
998Add the USB device @var{devname}. @xref{usb_devices}.
999
1000@table @option
1001
1002@item mouse
1003Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1004
1005@item tablet
1006Pointer device that uses absolute coordinates (like a touchscreen). This
1007means QEMU is able to report the mouse position without having to grab the
1008mouse. Also overrides the PS/2 mouse emulation when activated.
1009
1010@item disk:[format=@var{format}]:@var{file}
1011Mass storage device based on file. The optional @var{format} argument
Michael Tokarevd33c8a72016-05-18 15:47:53 +03001012will be used rather than detecting the format. Can be used to specify
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001013@code{format=raw} to avoid interpreting an untrusted format header.
1014
1015@item host:@var{bus}.@var{addr}
1016Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
1017
1018@item host:@var{vendor_id}:@var{product_id}
1019Pass through the host device identified by @var{vendor_id}:@var{product_id}
1020(Linux only).
1021
1022@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
1023Serial converter to host character device @var{dev}, see @code{-serial} for the
1024available devices.
1025
1026@item braille
1027Braille device. This will use BrlAPI to display the braille output on a real
1028or fake device.
1029
1030@item net:@var{options}
1031Network adapter that supports CDC ethernet and RNDIS protocols.
1032
1033@end table
1034ETEXI
1035
1036STEXI
1037@end table
1038ETEXI
1039DEFHEADING()
1040
Paolo Bonzini43f187a2017-01-04 13:50:37 +01001041DEFHEADING(Display options)
blueswir15824d652009-03-28 06:44:27 +00001042STEXI
1043@table @option
1044ETEXI
1045
Jes Sorensen1472a952011-03-16 13:33:31 +01001046DEF("display", HAS_ARG, QEMU_OPTION_display,
1047 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Samuel Thibault87eb2ba2017-01-15 21:30:14 +01001048 " [,window_close=on|off][,gl=on|off]\n"
Robert Hof04ec5a2016-07-26 18:17:11 +08001049 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1050 "-display vnc=<display>[,<optargs>]\n"
1051 "-display curses\n"
1052 "-display none"
1053 " select display type\n"
1054 "The default display is equivalent to\n"
1055#if defined(CONFIG_GTK)
1056 "\t\"-display gtk\"\n"
1057#elif defined(CONFIG_SDL)
1058 "\t\"-display sdl\"\n"
1059#elif defined(CONFIG_COCOA)
1060 "\t\"-display cocoa\"\n"
1061#elif defined(CONFIG_VNC)
1062 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1063#else
1064 "\t\"-display none\"\n"
1065#endif
1066 , QEMU_ARCH_ALL)
Jes Sorensen1472a952011-03-16 13:33:31 +01001067STEXI
1068@item -display @var{type}
1069@findex -display
1070Select type of display to use. This option is a replacement for the
1071old style -sdl/-curses/... options. Valid values for @var{type} are
1072@table @option
1073@item sdl
1074Display video output via SDL (usually in a separate graphics
1075window; see the SDL documentation for other possibilities).
1076@item curses
1077Display video output via curses. For graphics device models which
1078support a text mode, QEMU can display this output using a
1079curses/ncurses interface. Nothing is displayed when the graphics
1080device is in graphical mode or if the graphics device does not support
1081a text mode. Generally only the VGA device models support text mode.
Jes Sorensen4171d322011-03-16 13:33:32 +01001082@item none
1083Do not display video output. The guest will still see an emulated
1084graphics card, but its output will not be displayed to the QEMU
1085user. This option differs from the -nographic option in that it
1086only affects what is done with video output; -nographic also changes
1087the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +01001088@item gtk
1089Display video output in a GTK window. This interface provides drop-down
1090menus and other UI elements to configure and control the VM during
1091runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +01001092@item vnc
1093Start a VNC server on display <arg>
Jes Sorensen1472a952011-03-16 13:33:31 +01001094@end table
1095ETEXI
1096
blueswir15824d652009-03-28 06:44:27 +00001097DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +00001098 "-nographic disable graphical output and redirect serial I/Os to console\n",
1099 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001100STEXI
1101@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +01001102@findex -nographic
Colin Lorddc0a3e42016-08-12 15:30:48 -04001103Normally, if QEMU is compiled with graphical window support, it displays
1104output such as guest graphics, guest console, and the QEMU monitor in a
1105window. With this option, you can totally disable graphical output so
1106that QEMU is a simple command line application. The emulated serial port
1107is redirected on the console and muxed with the monitor (unless
1108redirected elsewhere explicitly). Therefore, you can still use QEMU to
1109debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1110switching between the console and monitor.
blueswir15824d652009-03-28 06:44:27 +00001111ETEXI
1112
blueswir15824d652009-03-28 06:44:27 +00001113DEF("curses", 0, QEMU_OPTION_curses,
Robert Hof04ec5a2016-07-26 18:17:11 +08001114 "-curses shorthand for -display curses\n",
Blue Swirlad960902010-03-29 19:23:52 +00001115 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001116STEXI
1117@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001118@findex -curses
Colin Lorddc0a3e42016-08-12 15:30:48 -04001119Normally, if QEMU is compiled with graphical window support, it displays
1120output such as guest graphics, guest console, and the QEMU monitor in a
1121window. With this option, QEMU can display the VGA output when in text
1122mode using a curses/ncurses interface. Nothing is displayed in graphical
1123mode.
blueswir15824d652009-03-28 06:44:27 +00001124ETEXI
1125
blueswir15824d652009-03-28 06:44:27 +00001126DEF("no-frame", 0, QEMU_OPTION_no_frame,
Blue Swirlad960902010-03-29 19:23:52 +00001127 "-no-frame open SDL window without a frame and window decorations\n",
1128 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001129STEXI
1130@item -no-frame
Stefan Weil6616b2a2010-02-05 23:52:05 +01001131@findex -no-frame
blueswir15824d652009-03-28 06:44:27 +00001132Do not use decorations for SDL windows and start them using the whole
1133available screen space. This makes the using QEMU in a dedicated desktop
1134workspace more convenient.
1135ETEXI
1136
blueswir15824d652009-03-28 06:44:27 +00001137DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001138 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1139 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001140STEXI
1141@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001142@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001143Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1144affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +00001145ETEXI
1146
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001147DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001148 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1149 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001150STEXI
1151@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001152@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001153Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1154affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001155ETEXI
1156
blueswir15824d652009-03-28 06:44:27 +00001157DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +00001158 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001159STEXI
1160@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +01001161@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +00001162Disable SDL window close capability.
1163ETEXI
1164
blueswir15824d652009-03-28 06:44:27 +00001165DEF("sdl", 0, QEMU_OPTION_sdl,
Robert Hof04ec5a2016-07-26 18:17:11 +08001166 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001167STEXI
1168@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +01001169@findex -sdl
blueswir15824d652009-03-28 06:44:27 +00001170Enable SDL.
1171ETEXI
1172
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001173DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +03001174 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1175 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1176 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
Marc-André Lureaufe4831b2015-01-13 17:57:51 +01001177 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001178 " [,tls-ciphers=<list>]\n"
1179 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1180 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1181 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1182 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1183 " [,jpeg-wan-compression=[auto|never|always]]\n"
1184 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1185 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +02001186 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1187 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Marc-André Lureau7b525502017-02-12 15:21:18 +04001188 " [,gl=[on|off]][,rendernode=<file>]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001189 " enable spice\n"
1190 " at least one of {port, tls-port} is mandatory\n",
1191 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001192STEXI
1193@item -spice @var{option}[,@var{option}[,...]]
1194@findex -spice
1195Enable the spice remote desktop protocol. Valid options are
1196
1197@table @option
1198
1199@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001200Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001201
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001202@item addr=<addr>
1203Set the IP address spice is listening on. Default is any address.
1204
1205@item ipv4
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001206@itemx ipv6
1207@itemx unix
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001208Force using the specified IP version.
1209
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001210@item password=<secret>
1211Set the password you need to authenticate.
1212
Marc-André Lureau48b3ed02011-05-17 10:40:33 +02001213@item sasl
1214Require that the client use SASL to authenticate with the spice.
1215The exact choice of authentication method used is controlled from the
1216system / user's SASL configuration file for the 'qemu' service. This
1217is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1218unprivileged user, an environment variable SASL_CONF_PATH can be used
1219to make it search alternate locations for the service config.
1220While some SASL auth methods can also provide data encryption (eg GSSAPI),
1221it is recommended that SASL always be combined with the 'tls' and
1222'x509' settings to enable use of SSL and server certificates. This
1223ensures a data encryption preventing compromise of authentication
1224credentials.
1225
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001226@item disable-ticketing
1227Allow client connects without authentication.
1228
Hans de Goeded4970b02011-03-27 16:43:54 +02001229@item disable-copy-paste
1230Disable copy paste between the client and the guest.
1231
Hans de Goede5ad24e52013-06-08 15:37:27 +02001232@item disable-agent-file-xfer
1233Disable spice-vdagent based file-xfer between the client and the guest.
1234
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001235@item tls-port=<nr>
1236Set the TCP port spice is listening on for encrypted channels.
1237
1238@item x509-dir=<dir>
1239Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1240
1241@item x509-key-file=<file>
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001242@itemx x509-key-password=<file>
1243@itemx x509-cert-file=<file>
1244@itemx x509-cacert-file=<file>
1245@itemx x509-dh-key-file=<file>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001246The x509 file names can also be configured individually.
1247
1248@item tls-ciphers=<list>
1249Specify which ciphers to use.
1250
Alon Levyd70d6b32011-12-20 13:05:18 +02001251@item tls-channel=[main|display|cursor|inputs|record|playback]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001252@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001253Force specific channel to be used with or without TLS encryption. The
1254options can be specified multiple times to configure multiple
1255channels. The special name "default" can be used to set the default
1256mode. For channels which are not explicitly forced into one mode the
1257spice client is allowed to pick tls/plaintext as he pleases.
1258
Yonit Halperin9f04e092010-07-14 13:26:34 +03001259@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1260Configure image compression (lossless).
1261Default is auto_glz.
1262
1263@item jpeg-wan-compression=[auto|never|always]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001264@itemx zlib-glz-wan-compression=[auto|never|always]
Yonit Halperin9f04e092010-07-14 13:26:34 +03001265Configure wan image compression (lossy for slow links).
1266Default is auto.
1267
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001268@item streaming-video=[off|all|filter]
Li Zhijian93ca5192016-08-01 12:06:59 +08001269Configure video stream detection. Default is off.
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001270
1271@item agent-mouse=[on|off]
1272Enable/disable passing mouse events via vdagent. Default is on.
1273
1274@item playback-compression=[on|off]
1275Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1276
Yonit Halperin8c957052012-08-21 11:51:59 +03001277@item seamless-migration=[on|off]
1278Enable/disable spice seamless migration. Default is off.
1279
Gerd Hoffmann474114b2015-10-13 15:39:34 +02001280@item gl=[on|off]
1281Enable/disable OpenGL context. Default is off.
1282
Marc-André Lureau7b525502017-02-12 15:21:18 +04001283@item rendernode=<file>
1284DRM render node for OpenGL rendering. If not specified, it will pick
1285the first available. (Since 2.9)
1286
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001287@end table
1288ETEXI
1289
blueswir15824d652009-03-28 06:44:27 +00001290DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001291 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1292 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001293STEXI
1294@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001295@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001296Rotate graphical output 90 deg left (only PXA LCD).
1297ETEXI
1298
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001299DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1300 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1301 QEMU_ARCH_ALL)
1302STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001303@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001304@findex -rotate
1305Rotate graphical output some deg left (only PXA LCD).
1306ETEXI
1307
blueswir15824d652009-03-28 06:44:27 +00001308DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001309 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001310 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001311STEXI
malce4558dc2012-08-27 18:33:21 +04001312@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001313@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001314Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001315@table @option
blueswir15824d652009-03-28 06:44:27 +00001316@item cirrus
1317Cirrus Logic GD5446 Video card. All Windows versions starting from
1318Windows 95 should recognize and use this graphic card. For optimal
1319performances, use 16 bit color depth in the guest and the host OS.
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001320(This card was the default before QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001321@item std
1322Standard VGA card with Bochs VBE extensions. If your guest OS
1323supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1324to use high resolution modes (>= 1280x1024x16) then you should use
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001325this option. (This card is the default since QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001326@item vmware
1327VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1328recent XFree86/XOrg server or Windows guest with a driver for this
1329card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001330@item qxl
1331QXL paravirtual graphic card. It is VGA compatible (including VESA
13322.0 VBE support). Works best with qxl guest drivers installed though.
1333Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001334@item tcx
1335(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1336sun4m machines and offers both 8-bit and 24-bit colour depths at a
1337fixed resolution of 1024x768.
1338@item cg3
1339(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1340for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1341resolutions aimed at people wishing to run older Solaris versions.
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001342@item virtio
1343Virtio VGA card.
blueswir15824d652009-03-28 06:44:27 +00001344@item none
1345Disable VGA card.
1346@end table
1347ETEXI
1348
1349DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001350 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001351STEXI
1352@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001353@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001354Start in full screen.
1355ETEXI
1356
blueswir15824d652009-03-28 06:44:27 +00001357DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001358 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1359 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001360STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001361@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001362@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001363Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001364ETEXI
1365
1366DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Robert Hof04ec5a2016-07-26 18:17:11 +08001367 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001368STEXI
1369@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001370@findex -vnc
Colin Lorddc0a3e42016-08-12 15:30:48 -04001371Normally, if QEMU is compiled with graphical window support, it displays
1372output such as guest graphics, guest console, and the QEMU monitor in a
1373window. With this option, you can have QEMU listen on VNC display
1374@var{display} and redirect the VGA display over the VNC session. It is
1375very useful to enable the usb tablet device when using this option
1376(option @option{-usbdevice tablet}). When using the VNC display, you
1377must use the @option{-k} parameter to set the keyboard layout if you are
1378not using en-us. Valid syntax for the @var{display} is
blueswir15824d652009-03-28 06:44:27 +00001379
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001380@table @option
blueswir15824d652009-03-28 06:44:27 +00001381
Robert Ho99a9a522016-05-31 15:03:09 +08001382@item to=@var{L}
1383
1384With this option, QEMU will try next available VNC @var{display}s, until the
1385number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1386available, e.g. port 5900+@var{display} is already used by another
1387application. By default, to=0.
1388
blueswir15824d652009-03-28 06:44:27 +00001389@item @var{host}:@var{d}
1390
1391TCP connections will only be allowed from @var{host} on display @var{d}.
1392By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1393be omitted in which case the server will accept connections from any host.
1394
Kevin Wolf4e257e52009-10-09 10:58:36 +02001395@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001396
1397Connections will be allowed over UNIX domain sockets where @var{path} is the
1398location of a unix socket to listen for connections on.
1399
1400@item none
1401
1402VNC is initialized but not started. The monitor @code{change} command
1403can be used to later start the VNC server.
1404
1405@end table
1406
1407Following the @var{display} value there may be one or more @var{option} flags
1408separated by commas. Valid options are
1409
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001410@table @option
blueswir15824d652009-03-28 06:44:27 +00001411
1412@item reverse
1413
1414Connect to a listening VNC client via a ``reverse'' connection. The
1415client is specified by the @var{display}. For reverse network
1416connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1417is a TCP port number, not a display number.
1418
Tim Hardeck7536ee42013-01-21 11:04:44 +01001419@item websocket
1420
1421Opens an additional TCP listening port dedicated to VNC Websocket connections.
Daniel P. Berrange275e0d62017-02-03 12:06:45 +00001422If a bare @var{websocket} option is given, the Websocket port is
14235700+@var{display}. An alternative port can be specified with the
1424syntax @code{websocket}=@var{port}.
1425
1426If @var{host} is specified connections will only be allowed from this host.
1427It is possible to control the websocket listen address independently, using
1428the syntax @code{websocket}=@var{host}:@var{port}.
1429
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001430If no TLS credentials are provided, the websocket connection runs in
1431unencrypted mode. If TLS credentials are provided, the websocket connection
1432requires encrypted client connections.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001433
blueswir15824d652009-03-28 06:44:27 +00001434@item password
1435
1436Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001437
1438The password must be set separately using the @code{set_password} command in
1439the @ref{pcsys_monitor}. The syntax to change your password is:
1440@code{set_password <protocol> <password>} where <protocol> could be either
1441"vnc" or "spice".
1442
1443If you would like to change <protocol> password expiration, you should use
1444@code{expire_password <protocol> <expiration-time>} where expiration time could
1445be one of the following options: now, never, +seconds or UNIX time of
1446expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1447to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1448date and time).
1449
1450You can also use keywords "now" or "never" for the expiration time to
1451allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001452
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001453@item tls-creds=@var{ID}
1454
1455Provides the ID of a set of TLS credentials to use to secure the
1456VNC server. They will apply to both the normal VNC server socket
1457and the websocket socket (if enabled). Setting TLS credentials
1458will cause the VNC server socket to enable the VeNCrypt auth
1459mechanism. The credentials should have been previously created
1460using the @option{-object tls-creds} argument.
1461
1462The @option{tls-creds} parameter obsoletes the @option{tls},
1463@option{x509}, and @option{x509verify} options, and as such
1464it is not permitted to set both new and old type options at
1465the same time.
1466
blueswir15824d652009-03-28 06:44:27 +00001467@item tls
1468
1469Require that client use TLS when communicating with the VNC server. This
1470uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1471attack. It is recommended that this option be combined with either the
Kevin Wolf4e257e52009-10-09 10:58:36 +02001472@option{x509} or @option{x509verify} options.
blueswir15824d652009-03-28 06:44:27 +00001473
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001474This option is now deprecated in favor of using the @option{tls-creds}
1475argument.
1476
blueswir15824d652009-03-28 06:44:27 +00001477@item x509=@var{/path/to/certificate/dir}
1478
1479Valid if @option{tls} is specified. Require that x509 credentials are used
1480for negotiating the TLS session. The server will send its x509 certificate
1481to the client. It is recommended that a password be set on the VNC server
1482to provide authentication of the client when this is used. The path following
1483this option specifies where the x509 certificates are to be loaded from.
1484See the @ref{vnc_security} section for details on generating certificates.
1485
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001486This option is now deprecated in favour of using the @option{tls-creds}
1487argument.
1488
blueswir15824d652009-03-28 06:44:27 +00001489@item x509verify=@var{/path/to/certificate/dir}
1490
1491Valid if @option{tls} is specified. Require that x509 credentials are used
1492for negotiating the TLS session. The server will send its x509 certificate
1493to the client, and request that the client send its own x509 certificate.
1494The server will validate the client's certificate against the CA certificate,
1495and reject clients when validation fails. If the certificate authority is
1496trusted, this is a sufficient authentication mechanism. You may still wish
1497to set a password on the VNC server as a second authentication layer. The
1498path following this option specifies where the x509 certificates are to
1499be loaded from. See the @ref{vnc_security} section for details on generating
1500certificates.
1501
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001502This option is now deprecated in favour of using the @option{tls-creds}
1503argument.
1504
blueswir15824d652009-03-28 06:44:27 +00001505@item sasl
1506
1507Require that the client use SASL to authenticate with the VNC server.
1508The exact choice of authentication method used is controlled from the
1509system / user's SASL configuration file for the 'qemu' service. This
1510is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1511unprivileged user, an environment variable SASL_CONF_PATH can be used
1512to make it search alternate locations for the service config.
1513While some SASL auth methods can also provide data encryption (eg GSSAPI),
1514it is recommended that SASL always be combined with the 'tls' and
1515'x509' settings to enable use of SSL and server certificates. This
1516ensures a data encryption preventing compromise of authentication
1517credentials. See the @ref{vnc_security} section for details on using
1518SASL authentication.
1519
1520@item acl
1521
1522Turn on access control lists for checking of the x509 client certificate
1523and SASL party. For x509 certs, the ACL check is made against the
1524certificate's distinguished name. This is something that looks like
1525@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1526made against the username, which depending on the SASL plugin, may
1527include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1528When the @option{acl} flag is set, the initial access list will be
1529empty, with a @code{deny} policy. Thus no one will be allowed to
1530use the VNC server until the ACLs have been loaded. This can be
1531achieved using the @code{acl} monitor command.
1532
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001533@item lossy
1534
1535Enable lossy compression methods (gradient, JPEG, ...). If this
1536option is set, VNC client may receive lossy framebuffer updates
1537depending on its encoding settings. Enabling this option can save
1538a lot of bandwidth at the expense of quality.
1539
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001540@item non-adaptive
1541
1542Disable adaptive encodings. Adaptive encodings are enabled by default.
1543An adaptive encoding will try to detect frequently updated screen regions,
1544and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001545This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001546adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001547like Tight.
1548
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001549@item share=[allow-exclusive|force-shared|ignore]
1550
1551Set display sharing policy. 'allow-exclusive' allows clients to ask
1552for exclusive access. As suggested by the rfb spec this is
1553implemented by dropping other connections. Connecting multiple
1554clients in parallel requires all clients asking for a shared session
1555(vncviewer: -shared switch). This is the default. 'force-shared'
1556disables exclusive client access. Useful for shared desktop sessions,
1557where you don't want someone forgetting specify -shared disconnect
1558everybody else. 'ignore' completely ignores the shared flag and
1559allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001560spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001561
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001562@item key-delay-ms
1563
1564Set keyboard delay, for key down and key up events, in milliseconds.
1565Default is 1. Keyboards are low-bandwidth devices, so this slowdown
1566can help the device and guest to keep up and not lose events in case
1567events are arriving in bulk. Possible causes for the latter are flaky
1568network connections, or scripts for automated testing.
1569
blueswir15824d652009-03-28 06:44:27 +00001570@end table
1571ETEXI
1572
1573STEXI
1574@end table
1575ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001576ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001577
Paolo Bonzini43f187a2017-01-04 13:50:37 +01001578ARCHHEADING(i386 target only, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001579STEXI
1580@table @option
1581ETEXI
1582
blueswir15824d652009-03-28 06:44:27 +00001583DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001584 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1585 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001586STEXI
1587@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001588@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001589Use it when installing Windows 2000 to avoid a disk full bug. After
1590Windows 2000 is installed, you no longer need this option (this option
1591slows down the IDE transfers).
1592ETEXI
1593
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02001594HXCOMM Deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00001595DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001596
blueswir15824d652009-03-28 06:44:27 +00001597DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001598 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1599 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001600STEXI
1601@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001602@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001603Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001604be needed to boot from old floppy disks.
1605ETEXI
1606
blueswir15824d652009-03-28 06:44:27 +00001607DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Shannon Zhaof5d8c8c2015-05-29 11:28:54 +01001608 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
blueswir15824d652009-03-28 06:44:27 +00001609STEXI
1610@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001611@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001612Disable ACPI (Advanced Configuration and Power Interface) support. Use
1613it if your guest OS complains about ACPI problems (PC target machine
1614only).
1615ETEXI
1616
blueswir15824d652009-03-28 06:44:27 +00001617DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001618 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001619STEXI
1620@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001621@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001622Disable HPET support.
1623ETEXI
1624
blueswir15824d652009-03-28 06:44:27 +00001625DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001626 "-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"
Blue Swirlad960902010-03-29 19:23:52 +00001627 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001628STEXI
1629@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}]...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001630@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001631Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001632For file=, take whole ACPI table from the specified files, including all
1633ACPI headers (possible overridden by other options).
1634For data=, only data
1635portion of the table is used, all header information is specified in the
1636command line.
Laszlo Ersekae123742016-01-18 15:12:13 +01001637If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1638fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1639to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1640spec.
blueswir15824d652009-03-28 06:44:27 +00001641ETEXI
1642
aliguorib6f6e3d2009-04-17 18:59:56 +00001643DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1644 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001645 " load SMBIOS entry from binary file\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001646 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1647 " [,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001648 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00001649 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1650 " [,uuid=uuid][,sku=str][,family=str]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001651 " specify SMBIOS type 1 fields\n"
1652 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1653 " [,asset=str][,location=str]\n"
1654 " specify SMBIOS type 2 fields\n"
1655 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1656 " [,sku=str]\n"
1657 " specify SMBIOS type 3 fields\n"
1658 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1659 " [,asset=str][,part=str]\n"
1660 " specify SMBIOS type 4 fields\n"
1661 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001662 " [,asset=str][,part=str][,speed=%d]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001663 " specify SMBIOS type 17 fields\n",
Wei Huangc30e1562015-09-07 10:39:29 +01001664 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
aliguorib6f6e3d2009-04-17 18:59:56 +00001665STEXI
1666@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001667@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00001668Load SMBIOS entry from binary file.
1669
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001670@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
aliguorib6f6e3d2009-04-17 18:59:56 +00001671Specify SMBIOS type 0 fields
1672
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001673@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}]
aliguorib6f6e3d2009-04-17 18:59:56 +00001674Specify SMBIOS type 1 fields
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001675
1676@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}]
1677Specify SMBIOS type 2 fields
1678
1679@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1680Specify SMBIOS type 3 fields
1681
1682@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1683Specify SMBIOS type 4 fields
1684
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001685@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}]
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001686Specify SMBIOS type 17 fields
aliguorib6f6e3d2009-04-17 18:59:56 +00001687ETEXI
1688
blueswir15824d652009-03-28 06:44:27 +00001689STEXI
1690@end table
1691ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001692DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00001693
Paolo Bonzini43f187a2017-01-04 13:50:37 +01001694DEFHEADING(Network options)
blueswir15824d652009-03-28 06:44:27 +00001695STEXI
1696@table @option
1697ETEXI
1698
Jan Kiszkaad196a92009-06-24 14:42:28 +02001699HXCOMM Legacy slirp options (now moved to -net user):
1700#ifdef CONFIG_SLIRP
Blue Swirlad960902010-03-29 19:23:52 +00001701DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1702DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1703DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001704#ifndef _WIN32
Blue Swirlad960902010-03-29 19:23:52 +00001705DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001706#endif
1707#endif
1708
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001709DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
blueswir15824d652009-03-28 06:44:27 +00001710#ifdef CONFIG_SLIRP
Samuel Thibault0b11c032016-03-20 12:29:54 +01001711 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1712 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1713 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001714 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n"
Klaus Stengel63d29602012-10-27 19:53:39 +02001715 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001716#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001717 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001718#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001719 " configure a user mode network backend with ID 'str',\n"
1720 " its DHCP server and optional services\n"
blueswir15824d652009-03-28 06:44:27 +00001721#endif
1722#ifdef _WIN32
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001723 "-netdev tap,id=str,ifname=name\n"
1724 " configure a host TAP network backend with ID 'str'\n"
blueswir15824d652009-03-28 06:44:27 +00001725#else
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001726 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001727 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001728 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001729 " [,poll-us=n]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001730 " configure a host TAP network backend with ID 'str'\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001731 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001732 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1733 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1734 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001735 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001736 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1737 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00001738 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001739 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001740 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02001741 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001742 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1743 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001744 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02001745 " (only has effect for virtio guests which use MSIX)\n"
1746 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001747 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001748 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08001749 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001750 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
1751 " spent on busy polling for vhost net\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001752 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1753 " configure a host TAP network backend with ID 'str' that is\n"
1754 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1755 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01001756#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001757#ifdef __linux__
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001758 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1759 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1760 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1761 " [,rxcookie=rxcookie][,offset=offset]\n"
1762 " configure a network backend with ID 'str' connected to\n"
1763 " an Ethernet over L2TPv3 pseudowire.\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001764 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04001765 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001766 " VM to a router and even VM to Host. It is a nearly-universal\n"
1767 " standard (RFC3391). Note - this implementation uses static\n"
1768 " pre-configured tunnels (same as the Linux kernel).\n"
1769 " use 'src=' to specify source address\n"
1770 " use 'dst=' to specify destination address\n"
1771 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08001772 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001773 " use 'dstport=' to specify destination udp port\n"
1774 " use 'ipv6=on' to force v6\n"
1775 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1776 " well as a weak security measure\n"
1777 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1778 " use 'txcookie=0x012345678' to specify a txcookie\n"
1779 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1780 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1781 " use 'pincounter=on' to work around broken counter handling in peer\n"
1782 " use 'offset=X' to add an extra offset between header and data\n"
1783#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001784 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1785 " configure a network backend to connect to another network\n"
1786 " using a socket connection\n"
1787 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1788 " configure a network backend to connect to a multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08001789 " use 'localaddr=addr' to specify the host address to send packets from\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001790 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1791 " configure a network backend to connect to another network\n"
1792 " using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00001793#ifdef CONFIG_VDE
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001794 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1795 " configure a network backend to connect to port 'n' of a vde switch\n"
1796 " running on host and listening for incoming connections on 'socketpath'.\n"
blueswir15824d652009-03-28 06:44:27 +00001797 " Use group 'groupname' and mode 'octalmode' to change default\n"
1798 " ownership and permissions for communication port.\n"
1799#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001800#ifdef CONFIG_NETMAP
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001801 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
Vincenzo Maffione58952132013-11-06 11:44:06 +01001802 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1803 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1804 " netmap device, defaults to '/dev/netmap')\n"
1805#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001806 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1807 " configure a vhost-user network, backed by a chardev 'dev'\n"
1808 "-netdev hubport,id=str,hubid=n\n"
1809 " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL)
1810DEF("net", HAS_ARG, QEMU_OPTION_net,
1811 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1812 " old way to create a new NIC and connect it to VLAN 'n'\n"
1813 " (use the '-device devtype,netdev=str' option if possible instead)\n"
aliguoribb9ea792009-04-21 19:56:28 +00001814 "-net dump[,vlan=n][,file=f][,len=n]\n"
1815 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001816 "-net none use it alone to have zero network devices. If no -net option\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001817 " is provided, the default is '-net nic -net user'\n"
1818 "-net ["
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001819#ifdef CONFIG_SLIRP
1820 "user|"
1821#endif
1822 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001823 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001824#ifdef CONFIG_VDE
1825 "vde|"
1826#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001827#ifdef CONFIG_NETMAP
1828 "netmap|"
1829#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001830 "socket][,vlan=n][,option][,option][,...]\n"
1831 " old way to initialize a host network interface\n"
1832 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001833STEXI
Blue Swirl609c1da2010-03-18 18:41:49 +00001834@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001835@findex -net
blueswir15824d652009-03-28 06:44:27 +00001836Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
Anthony Liguori0d6b0b12009-08-14 11:20:47 -05001837= 0 is the default). The NIC is an e1000 by default on the PC
Markus Armbruster5607c382009-06-18 15:14:08 +02001838target. Optionally, the MAC address can be changed to @var{mac}, the
1839device address set to @var{addr} (PCI cards only),
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001840and a @var{name} can be assigned for use in monitor commands.
1841Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1842that the card should have; this option currently only affects virtio cards; set
1843@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
Stefan Weil071c9392012-04-07 09:23:36 +02001844NIC is created. QEMU can emulate several different models of network card.
blueswir15824d652009-03-28 06:44:27 +00001845Valid values for @var{type} are
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001846@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
blueswir15824d652009-03-28 06:44:27 +00001847@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1848@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
Peter Maydell585f6032012-10-04 16:22:01 +01001849Not all devices are supported on all targets. Use @code{-net nic,model=help}
blueswir15824d652009-03-28 06:44:27 +00001850for a list of available devices for your target.
1851
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001852@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001853@findex -netdev
Jan Kiszkaad196a92009-06-24 14:42:28 +02001854@item -net user[,@var{option}][,@var{option}][,...]
blueswir15824d652009-03-28 06:44:27 +00001855Use the user mode network stack which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02001856privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00001857
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001858@table @option
Jan Kiszkaad196a92009-06-24 14:42:28 +02001859@item vlan=@var{n}
1860Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1861
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001862@item id=@var{id}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001863@itemx name=@var{name}
Jan Kiszkaad196a92009-06-24 14:42:28 +02001864Assign symbolic name for use in monitor commands.
1865
Samuel Thibault0b11c032016-03-20 12:29:54 +01001866@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
1867be enabled. If neither is specified both protocols are enabled.
1868
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001869@item net=@var{addr}[/@var{mask}]
1870Set IP network address the guest will see. Optionally specify the netmask,
1871either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000187210.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001873
1874@item host=@var{addr}
1875Specify the guest-visible address of the host. Default is the 2nd IP in the
1876guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001877
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001878@item ipv6-net=@var{addr}[/@var{int}]
1879Set IPv6 network address the guest will see (default is fec0::/64). The
1880network prefix is given in the usual hexadecimal IPv6 address
1881notation. The prefix size is optional, and is given as the number of
1882valid top-most bits (default is 64).
Yann Bordenave7aac5312016-03-15 10:31:22 +01001883
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001884@item ipv6-host=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01001885Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
1886the guest network, i.e. xxxx::2.
1887
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02001888@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10001889If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02001890able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10001891to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001892
1893@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02001894Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001895
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001896@item dhcpstart=@var{addr}
1897Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10001898is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001899
1900@item dns=@var{addr}
1901Specify the guest-visible address of the virtual nameserver. The address must
1902be different from the host address. Default is the 3rd IP in the guest network,
1903i.e. x.x.x.3.
1904
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001905@item ipv6-dns=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01001906Specify the guest-visible address of the IPv6 virtual nameserver. The address
1907must be different from the host address. Default is the 3rd IP in the guest
1908network, i.e. xxxx::3.
1909
Klaus Stengel63d29602012-10-27 19:53:39 +02001910@item dnssearch=@var{domain}
1911Provides an entry for the domain-search list sent by the built-in
1912DHCP server. More than one domain suffix can be transmitted by specifying
1913this option multiple times. If supported, this will cause the guest to
1914automatically try to append the given domain suffix(es) in case a domain name
1915can not be resolved.
1916
1917Example:
1918@example
1919qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1920@end example
1921
Jan Kiszkaad196a92009-06-24 14:42:28 +02001922@item tftp=@var{dir}
1923When using the user mode network stack, activate a built-in TFTP
1924server. The files in @var{dir} will be exposed as the root of a TFTP server.
1925The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001926@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02001927
1928@item bootfile=@var{file}
1929When using the user mode network stack, broadcast @var{file} as the BOOTP
1930filename. In conjunction with @option{tftp}, this can be used to network boot
1931a guest from a local directory.
1932
1933Example (using pxelinux):
1934@example
Stefan Weil3804da92012-05-11 22:21:50 +02001935qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02001936@end example
1937
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001938@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001939When using the user mode network stack, activate a built-in SMB
1940server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001941transparently. The IP address of the SMB server can be set to @var{addr}. By
1942default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001943
1944In the guest Windows OS, the line:
1945@example
194610.0.2.4 smbserver
1947@end example
1948must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1949or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1950
1951Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1952
Brade2d88302011-09-02 16:53:28 -04001953Note that a SAMBA server must be installed on the host OS.
1954QEMU was tested successfully with smbd versions from Red Hat 9,
1955Fedora Core 3 and OpenSUSE 11.x.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001956
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001957@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001958Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1959the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1960@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001961given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1962be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001963used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001964
1965For example, to redirect host X11 connection from screen 1 to guest
1966screen 0, use the following:
1967
1968@example
1969# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02001970qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001971# this host xterm should open in the guest X11 server
1972xterm -display :1
1973@end example
1974
1975To redirect telnet connections from host port 5555 to telnet port on
1976the guest, use the following:
1977
1978@example
1979# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02001980qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001981telnet localhost 5555
1982@end example
1983
1984Then when you use on the host @code{telnet localhost 5555}, you
1985connect to the guest telnet server.
1986
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001987@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001988@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001989Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02001990to the character device @var{dev} or to a program executed by @var{cmd:command}
1991which gets spawned for each connection. This option can be given multiple times.
1992
Stefan Weil43ffe612012-07-20 23:26:02 +02001993You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02001994lifetime, like in the following example:
1995
1996@example
1997# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1998# the guest accesses it
1999qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
2000@end example
2001
2002Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02002003so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02002004
2005@example
2006# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2007# and connect the TCP stream to its stdin/stdout
2008qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2009@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02002010
2011@end table
2012
2013Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
2014processed and applied to -net user. Mixing them with the new configuration
2015syntax gives undefined results. Their use for new applications is discouraged
2016as they will be removed from future versions.
blueswir15824d652009-03-28 06:44:27 +00002017
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002018@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2019@itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002020Connect the host TAP network interface @var{name} to VLAN @var{n}.
2021
2022Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00002023@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002024automatically provides one. The default network configure script is
2025@file{/etc/qemu-ifup} and the default network deconfigure script is
2026@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2027to disable script execution.
2028
2029If running QEMU as an unprivileged user, use the network helper
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002030@var{helper} to configure the TAP interface and attach it to the bridge.
2031The default network helper executable is @file{/path/to/qemu-bridge-helper}
2032and the default bridge device is @file{br0}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002033
2034@option{fd}=@var{h} can be used to specify the handle of an already
2035opened host TAP interface.
2036
2037Examples:
blueswir15824d652009-03-28 06:44:27 +00002038
2039@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002040#launch a QEMU instance with the default network script
Stefan Weil3804da92012-05-11 22:21:50 +02002041qemu-system-i386 linux.img -net nic -net tap
blueswir15824d652009-03-28 06:44:27 +00002042@end example
2043
blueswir15824d652009-03-28 06:44:27 +00002044@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002045#launch a QEMU instance with two NICs, each one connected
2046#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02002047qemu-system-i386 linux.img \
2048 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
2049 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
blueswir15824d652009-03-28 06:44:27 +00002050@end example
2051
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002052@example
2053#launch a QEMU instance with the default network helper to
2054#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02002055qemu-system-i386 linux.img \
Amos Kong420508f2013-10-23 04:49:28 +08002056 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002057@end example
2058
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002059@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002060@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002061Connect a host TAP network interface to a host bridge device.
2062
2063Use the network helper @var{helper} to configure the TAP interface and
2064attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08002065@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002066device is @file{br0}.
2067
2068Examples:
2069
2070@example
2071#launch a QEMU instance with the default network helper to
2072#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02002073qemu-system-i386 linux.img -net bridge -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002074@end example
2075
2076@example
2077#launch a QEMU instance with the default network helper to
2078#connect a TAP device to bridge qemubr0
Stefan Weil3804da92012-05-11 22:21:50 +02002079qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002080@end example
2081
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002082@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002083@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
blueswir15824d652009-03-28 06:44:27 +00002084
2085Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
2086machine using a TCP socket connection. If @option{listen} is
2087specified, QEMU waits for incoming connections on @var{port}
2088(@var{host} is optional). @option{connect} is used to connect to
2089another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2090specifies an already opened TCP socket.
2091
2092Example:
2093@example
2094# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002095qemu-system-i386 linux.img \
2096 -net nic,macaddr=52:54:00:12:34:56 \
2097 -net socket,listen=:1234
blueswir15824d652009-03-28 06:44:27 +00002098# connect the VLAN 0 of this instance to the VLAN 0
2099# of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02002100qemu-system-i386 linux.img \
2101 -net nic,macaddr=52:54:00:12:34:57 \
2102 -net socket,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002103@end example
2104
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002105@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002106@itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
blueswir15824d652009-03-28 06:44:27 +00002107
2108Create a VLAN @var{n} shared with another QEMU virtual
2109machines using a UDP multicast socket, effectively making a bus for
2110every QEMU with same multicast address @var{maddr} and @var{port}.
2111NOTES:
2112@enumerate
2113@item
2114Several QEMU can be running on different hosts and share same bus (assuming
2115correct multicast setup for these hosts).
2116@item
2117mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2118@url{http://user-mode-linux.sf.net}.
2119@item
2120Use @option{fd=h} to specify an already opened UDP multicast socket.
2121@end enumerate
2122
2123Example:
2124@example
2125# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002126qemu-system-i386 linux.img \
2127 -net nic,macaddr=52:54:00:12:34:56 \
2128 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002129# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002130qemu-system-i386 linux.img \
2131 -net nic,macaddr=52:54:00:12:34:57 \
2132 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002133# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002134qemu-system-i386 linux.img \
2135 -net nic,macaddr=52:54:00:12:34:58 \
2136 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002137@end example
2138
2139Example (User Mode Linux compat.):
2140@example
2141# launch QEMU instance (note mcast address selected
2142# is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02002143qemu-system-i386 linux.img \
2144 -net nic,macaddr=52:54:00:12:34:56 \
2145 -net socket,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00002146# launch UML
2147/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2148@end example
2149
Mike Ryan3a75e742010-12-01 11:16:47 -08002150Example (send packets from host's 1.2.3.4):
2151@example
Stefan Weil3804da92012-05-11 22:21:50 +02002152qemu-system-i386 linux.img \
2153 -net nic,macaddr=52:54:00:12:34:56 \
2154 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08002155@end example
2156
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002157@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}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002158@itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002159Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
2160protocol to transport Ethernet (and other Layer 2) data frames between
2161two systems. It is present in routers, firewalls and the Linux kernel
2162(from version 3.3 onwards).
2163
2164This transport allows a VM to communicate to another VM, router or firewall directly.
2165
2166@item src=@var{srcaddr}
2167 source address (mandatory)
2168@item dst=@var{dstaddr}
2169 destination address (mandatory)
2170@item udp
2171 select udp encapsulation (default is ip).
2172@item srcport=@var{srcport}
2173 source udp port.
2174@item dstport=@var{dstport}
2175 destination udp port.
2176@item ipv6
2177 force v6, otherwise defaults to v4.
2178@item rxcookie=@var{rxcookie}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002179@itemx txcookie=@var{txcookie}
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002180 Cookies are a weak form of security in the l2tpv3 specification.
2181Their function is mostly to prevent misconfiguration. By default they are 32
2182bit.
2183@item cookie64
2184 Set cookie size to 64 bit instead of the default 32
2185@item counter=off
2186 Force a 'cut-down' L2TPv3 with no counter as in
2187draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2188@item pincounter=on
2189 Work around broken counter handling in peer. This may also help on
2190networks which have packet reorder.
2191@item offset=@var{offset}
2192 Add an extra offset between header and data
2193
2194For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2195on the remote Linux host 1.2.3.4:
2196@example
2197# Setup tunnel on linux host using raw ip as encapsulation
2198# on 1.2.3.4
2199ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2200 encap udp udp_sport 16384 udp_dport 16384
2201ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2202 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2203ifconfig vmtunnel0 mtu 1500
2204ifconfig vmtunnel0 up
2205brctl addif br-lan vmtunnel0
2206
2207
2208# on 4.3.2.1
2209# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2210
2211qemu-system-i386 linux.img -net nic -net l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2212
2213
2214@end example
2215
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002216@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002217@itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
blueswir15824d652009-03-28 06:44:27 +00002218Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2219listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2220and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02002221communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00002222with vde support enabled.
2223
2224Example:
2225@example
2226# launch vde switch
2227vde_switch -F -sock /tmp/myswitch
2228# launch QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002229qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00002230@end example
2231
Stefan Hajnoczi40e8c262013-02-26 11:07:16 +01002232@item -netdev hubport,id=@var{id},hubid=@var{hubid}
2233
2234Create a hub port on QEMU "vlan" @var{hubid}.
2235
2236The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
2237netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2238required hub automatically.
2239
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002240@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002241
2242Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2243be a unix domain socket backed one. The vhost-user uses a specifically defined
2244protocol to pass vhost ioctl replacement messages to an application on the other
2245end of the socket. On non-MSIX guests, the feature can be forced with
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002246@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2247be created for multiqueue vhost-user.
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002248
2249Example:
2250@example
2251qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2252 -numa node,memdev=mem \
Vincenzo Maffione79cad2f2017-02-20 17:45:09 +01002253 -chardev socket,id=chr0,path=/path/to/socket \
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002254 -netdev type=vhost-user,id=net0,chardev=chr0 \
2255 -device virtio-net-pci,netdev=net0
2256@end example
2257
aliguoribb9ea792009-04-21 19:56:28 +00002258@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2259Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2260At most @var{len} bytes (64k by default) per packet are stored. The file format is
2261libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
Thomas Huthd3e0c032015-10-13 12:40:02 +02002262Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
aliguoribb9ea792009-04-21 19:56:28 +00002263
blueswir15824d652009-03-28 06:44:27 +00002264@item -net none
2265Indicate that no network devices should be configured. It is used to
2266override the default configuration (@option{-net nic -net user}) which
2267is activated if no @option{-net} options are provided.
blueswir15824d652009-03-28 06:44:27 +00002268ETEXI
2269
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002270STEXI
2271@end table
2272ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002273DEFHEADING()
2274
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002275DEFHEADING(Character device options)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002276STEXI
2277
2278The general form of a character device option is:
2279@table @option
2280ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002281
2282DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Lin Ma517b3d42016-08-17 01:13:52 +08002283 "-chardev help\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002284 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05002285 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002286 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002287 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002288 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2289 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002290 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02002291 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002292 " [,logfile=PATH][,logappend=on|off]\n"
2293 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002294 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002295 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2296 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2297 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2298 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002299#ifdef _WIN32
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002300 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2301 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002302#else
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002303 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2304 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002305#endif
2306#ifdef CONFIG_BRLAPI
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002307 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002308#endif
2309#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2310 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002311 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2312 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002313#endif
2314#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002315 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2316 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002317#endif
Alon Levycbcc6332011-01-19 10:49:50 +02002318#if defined(CONFIG_SPICE)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002319 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2320 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02002321#endif
Blue Swirlad960902010-03-29 19:23:52 +00002322 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00002323)
2324
2325STEXI
Jan Kiszka97331282010-04-06 16:55:54 +02002326@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002327@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00002328Backend is one of:
2329@option{null},
2330@option{socket},
2331@option{udp},
2332@option{msmouse},
2333@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02002334@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00002335@option{file},
2336@option{pipe},
2337@option{console},
2338@option{serial},
2339@option{pty},
2340@option{stdio},
2341@option{braille},
2342@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002343@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02002344@option{parport},
2345@option{spicevmc}.
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002346@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002347The specific backend will determine the applicable options.
2348
Lin Ma517b3d42016-08-17 01:13:52 +08002349Use "-chardev help" to print all available chardev backend types.
2350
Matthew Booth7273a2d2009-10-30 13:41:12 +00002351All devices must have an id, which can be any string up to 127 characters long.
2352It is used to uniquely identify this device in other command line directives.
2353
Jan Kiszka97331282010-04-06 16:55:54 +02002354A character device may be used in multiplexing mode by multiple front-ends.
Peter Maydella40db1b2016-02-16 17:28:58 +00002355Specify @option{mux=on} to enable this mode.
2356A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2357backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2358If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2359create a multiplexer with your specified ID, and you can then configure multiple
2360front ends to use that chardev ID for their input/output. Up to four different
2361front ends can be connected to a single multiplexed chardev. (Without
2362multiplexing enabled, a chardev can only be used by a single front end.)
2363For instance you could use this to allow a single stdio chardev to be used by
2364two serial ports and the QEMU monitor:
2365
2366@example
2367-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002368-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002369-serial chardev:char0 \
2370-serial chardev:char0
2371@end example
2372
2373You can have more than one multiplexer in a system configuration; for instance
2374you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2375multiplexed between the QEMU monitor and a parallel port:
2376
2377@example
2378-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002379-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002380-parallel chardev:char0 \
2381-chardev tcp,...,mux=on,id=char1 \
2382-serial chardev:char1 \
2383-serial chardev:char1
2384@end example
2385
2386When you're using a multiplexed character device, some escape sequences are
2387interpreted in the input. @xref{mux_keys, Keys in the character backend
2388multiplexer}.
2389
2390Note that some other command line options may implicitly create multiplexed
2391character backends; for instance @option{-serial mon:stdio} creates a
2392multiplexed stdio backend connected to the serial port and the QEMU monitor,
2393and @option{-nographic} also multiplexes the console and the monitor to
2394stdio.
2395
2396There is currently no support for multiplexing in the other direction
2397(where a single QEMU front end takes input and output from multiple chardevs).
Jan Kiszka97331282010-04-06 16:55:54 +02002398
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002399Every backend supports the @option{logfile} option, which supplies the path
2400to a file to record all data transmitted via the backend. The @option{logappend}
2401option controls whether the log file will be truncated or appended to when
2402opened.
2403
2404Further options to each backend are described below.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002405
2406@item -chardev null ,id=@var{id}
2407A void device. This device will not emit any data, and will drop any data it
2408receives. The null backend does not take any options.
2409
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002410@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002411
2412Create a two-way stream socket, which can be either a TCP or a unix socket. A
2413unix socket will be created if @option{path} is specified. Behaviour is
2414undefined if TCP options are specified for a unix socket.
2415
2416@option{server} specifies that the socket shall be a listening socket.
2417
2418@option{nowait} specifies that QEMU should not block waiting for a client to
2419connect to a listening socket.
2420
2421@option{telnet} specifies that traffic on the socket should interpret telnet
2422escape sequences.
2423
Corey Minyard5dd1f022014-10-02 11:17:37 -05002424@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2425the remote end goes away. qemu will delay this many seconds and then attempt
2426to reconnect. Zero disables reconnecting, and is the default.
2427
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002428@option{tls-creds} requests enablement of the TLS protocol for encryption,
2429and specifies the id of the TLS credentials to use for the handshake. The
2430credentials must be previously created with the @option{-object tls-creds}
2431argument.
2432
Matthew Booth7273a2d2009-10-30 13:41:12 +00002433TCP and unix socket options are given below:
2434
2435@table @option
2436
Aurelien Jarno8d533562010-03-27 11:52:05 +01002437@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002438
2439@option{host} for a listening socket specifies the local address to be bound.
2440For a connecting socket species the remote host to connect to. @option{host} is
2441optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2442
2443@option{port} for a listening socket specifies the local port to be bound. For a
2444connecting socket specifies the port on the remote host to connect to.
2445@option{port} can be given as either a port number or a service name.
2446@option{port} is required.
2447
2448@option{to} is only relevant to listening sockets. If it is specified, and
2449@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2450to and including @option{to} until it succeeds. @option{to} must be specified
2451as a port number.
2452
2453@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2454If neither is specified the socket may use either protocol.
2455
2456@option{nodelay} disables the Nagle algorithm.
2457
2458@item unix options: path=@var{path}
2459
2460@option{path} specifies the local path of the unix socket. @option{path} is
2461required.
2462
2463@end table
2464
2465@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2466
2467Sends all traffic from the guest to a remote host over UDP.
2468
2469@option{host} specifies the remote host to connect to. If not specified it
2470defaults to @code{localhost}.
2471
2472@option{port} specifies the port on the remote host to connect to. @option{port}
2473is required.
2474
2475@option{localaddr} specifies the local address to bind to. If not specified it
2476defaults to @code{0.0.0.0}.
2477
2478@option{localport} specifies the local port to bind to. If not specified any
2479available local port will be used.
2480
2481@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2482If neither is specified the device may use either protocol.
2483
2484@item -chardev msmouse ,id=@var{id}
2485
2486Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2487take any options.
2488
2489@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2490
2491Connect to a QEMU text console. @option{vc} may optionally be given a specific
2492size.
2493
2494@option{width} and @option{height} specify the width and height respectively of
2495the console, in pixels.
2496
2497@option{cols} and @option{rows} specify that the console be sized to fit a text
2498console with the given dimensions.
2499
Markus Armbruster4f573782013-07-26 16:44:32 +02002500@item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002501
Markus Armbruster3949e592013-02-06 21:27:24 +01002502Create a ring buffer with fixed size @option{size}.
Stefan Hajnoczie69f7d22016-09-19 11:56:26 +01002503@var{size} must be a power of two and defaults to @code{64K}.
Lei Li51767e72013-01-25 00:03:19 +08002504
Matthew Booth7273a2d2009-10-30 13:41:12 +00002505@item -chardev file ,id=@var{id} ,path=@var{path}
2506
2507Log all traffic received from the guest to a file.
2508
2509@option{path} specifies the path of the file to be opened. This file will be
2510created if it does not already exist, and overwritten if it does. @option{path}
2511is required.
2512
2513@item -chardev pipe ,id=@var{id} ,path=@var{path}
2514
2515Create a two-way connection to the guest. The behaviour differs slightly between
2516Windows hosts and other hosts:
2517
2518On Windows, a single duplex pipe will be created at
2519@file{\\.pipe\@option{path}}.
2520
2521On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2522@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2523received by the guest. Data written by the guest can be read from
2524@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2525be present.
2526
2527@option{path} forms part of the pipe path as described above. @option{path} is
2528required.
2529
2530@item -chardev console ,id=@var{id}
2531
2532Send traffic from the guest to QEMU's standard output. @option{console} does not
2533take any options.
2534
2535@option{console} is only available on Windows hosts.
2536
2537@item -chardev serial ,id=@var{id} ,path=@option{path}
2538
2539Send traffic from the guest to a serial device on the host.
2540
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002541On Unix hosts serial will actually accept any tty device,
2542not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002543
2544@option{path} specifies the name of the serial device to open.
2545
2546@item -chardev pty ,id=@var{id}
2547
2548Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2549not take any options.
2550
2551@option{pty} is not available on Windows hosts.
2552
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002553@item -chardev stdio ,id=@var{id} [,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002554Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002555
2556@option{signal} controls if signals are enabled on the terminal, that includes
2557exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2558default, use @option{signal=off} to disable it.
2559
Matthew Booth7273a2d2009-10-30 13:41:12 +00002560@item -chardev braille ,id=@var{id}
2561
2562Connect to a local BrlAPI server. @option{braille} does not take any options.
2563
2564@item -chardev tty ,id=@var{id} ,path=@var{path}
2565
Matthew Booth7273a2d2009-10-30 13:41:12 +00002566@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002567DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002568
2569@option{path} specifies the path to the tty. @option{path} is required.
2570
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002571@item -chardev parallel ,id=@var{id} ,path=@var{path}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002572@itemx -chardev parport ,id=@var{id} ,path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002573
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002574@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002575
2576Connect to a local parallel port.
2577
2578@option{path} specifies the path to the parallel port device. @option{path} is
2579required.
2580
Alon Levycbcc6332011-01-19 10:49:50 +02002581@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2582
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002583@option{spicevmc} is only available when spice support is built in.
2584
Alon Levycbcc6332011-01-19 10:49:50 +02002585@option{debug} debug level for spicevmc
2586
2587@option{name} name of spice channel to connect to
2588
2589Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002590
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002591@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2592
2593@option{spiceport} is only available when spice support is built in.
2594
2595@option{debug} debug level for spicevmc
2596
2597@option{name} name of spice port to connect to
2598
2599Connect to a spice port, allowing a Spice client to handle the traffic
2600identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002601ETEXI
2602
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002603STEXI
2604@end table
2605ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002606DEFHEADING()
2607
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002608DEFHEADING(Device URL Syntax)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002609STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002610
2611In addition to using normal file images for the emulated storage devices,
2612QEMU can also use networked resources such as iSCSI devices. These are
2613specified using a special URL syntax.
2614
2615@table @option
2616@item iSCSI
2617iSCSI support allows QEMU to access iSCSI resources directly and use as
2618images for the guest storage. Both disk and cdrom images are supported.
2619
2620Syntax for specifying iSCSI LUNs is
2621``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2622
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002623By default qemu will use the iSCSI initiator-name
2624'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2625line or a configuration file.
2626
Peter Lieven5dd7a532015-06-16 13:45:07 +02002627Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2628stalled requests and force a reestablishment of the session. The timeout
Peter Lieven90497362015-06-26 12:18:01 +02002629is specified in seconds. The default is 0 which means no timeout. Libiscsi
26301.15.0 or greater is required for this feature.
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002631
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002632Example (without authentication):
2633@example
Stefan Weil3804da92012-05-11 22:21:50 +02002634qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2635 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2636 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002637@end example
2638
2639Example (CHAP username/password via URL):
2640@example
Stefan Weil3804da92012-05-11 22:21:50 +02002641qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002642@end example
2643
2644Example (CHAP username/password via environment variables):
2645@example
2646LIBISCSI_CHAP_USERNAME="user" \
2647LIBISCSI_CHAP_PASSWORD="password" \
Stefan Weil3804da92012-05-11 22:21:50 +02002648qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002649@end example
2650
2651iSCSI support is an optional feature of QEMU and only available when
2652compiled and linked against libiscsi.
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11002653ETEXI
2654DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2655 "-iscsi [user=user][,password=password]\n"
2656 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
Paolo Bonzini2fe37982013-12-06 16:08:05 +01002657 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
Peter Lieven5dd7a532015-06-16 13:45:07 +02002658 " [,timeout=timeout]\n"
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11002659 " iSCSI session parameters\n", QEMU_ARCH_ALL)
2660STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002661
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002662iSCSI parameters such as username and password can also be specified via
2663a configuration file. See qemu-doc for more information and examples.
2664
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002665@item NBD
2666QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2667as Unix Domain Sockets.
2668
2669Syntax for specifying a NBD device using TCP
2670``nbd:<server-ip>:<port>[:exportname=<export>]''
2671
2672Syntax for specifying a NBD device using Unix Domain Sockets
2673``nbd:unix:<domain-socket>[:exportname=<export>]''
2674
2675
2676Example for TCP
2677@example
Stefan Weil3804da92012-05-11 22:21:50 +02002678qemu-system-i386 --drive file=nbd:192.0.2.1:30000
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002679@end example
2680
2681Example for Unix Domain Sockets
2682@example
Stefan Weil3804da92012-05-11 22:21:50 +02002683qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002684@end example
2685
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01002686@item SSH
2687QEMU supports SSH (Secure Shell) access to remote disks.
2688
2689Examples:
2690@example
2691qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2692qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2693@end example
2694
2695Currently authentication must be done using ssh-agent. Other
2696authentication methods may be supported in future.
2697
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002698@item Sheepdog
2699Sheepdog is a distributed storage system for QEMU.
2700QEMU supports using either local sheepdog devices or remote networked
2701devices.
2702
2703Syntax for specifying a sheepdog device
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002704@example
MORITA Kazutaka1b8bbb42013-02-22 12:39:53 +09002705sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002706@end example
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002707
2708Example
2709@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002710qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002711@end example
2712
Thomas Huth6135c5e2017-02-09 13:10:18 +01002713See also @url{https://sheepdog.github.io/sheepdog/}.
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002714
Bharata B Rao8809e282012-10-24 17:17:53 +05302715@item GlusterFS
Stefan Weil736a83f2016-11-19 20:22:07 +01002716GlusterFS is a user space distributed file system.
Bharata B Rao8809e282012-10-24 17:17:53 +05302717QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2718TCP, Unix Domain Sockets and RDMA transport protocols.
2719
2720Syntax for specifying a VM disk image on GlusterFS volume is
2721@example
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05302722
2723URI:
2724gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
2725
2726JSON:
2727'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
2728@ "server":[@{"type":"tcp","host":"...","port":"..."@},
2729@ @{"type":"unix","socket":"..."@}]@}@}'
Bharata B Rao8809e282012-10-24 17:17:53 +05302730@end example
2731
2732
2733Example
2734@example
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05302735URI:
2736qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
2737@ file.debug=9,file.logfile=/var/log/qemu-gluster.log
2738
2739JSON:
2740qemu-system-x86_64 'json:@{"driver":"qcow2",
2741@ "file":@{"driver":"gluster",
2742@ "volume":"testvol","path":"a.img",
2743@ "debug":9,"logfile":"/var/log/qemu-gluster.log",
2744@ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
2745@ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
2746qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
2747@ file.debug=9,file.logfile=/var/log/qemu-gluster.log,
2748@ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
2749@ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
Bharata B Rao8809e282012-10-24 17:17:53 +05302750@end example
2751
2752See also @url{http://www.gluster.org}.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002753
Max Reitz23dce382016-11-02 18:55:37 +01002754@item HTTP/HTTPS/FTP/FTPS
2755QEMU supports read-only access to files accessed over http(s) and ftp(s).
Matthew Booth0a86cb72014-05-14 19:28:43 -04002756
2757Syntax using a single filename:
2758@example
2759<protocol>://[<username>[:<password>]@@]<host>/<path>
2760@end example
2761
2762where:
2763@table @option
2764@item protocol
Max Reitz23dce382016-11-02 18:55:37 +01002765'http', 'https', 'ftp', or 'ftps'.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002766
2767@item username
2768Optional username for authentication to the remote server.
2769
2770@item password
2771Optional password for authentication to the remote server.
2772
2773@item host
2774Address of the remote server.
2775
2776@item path
2777Path on the remote server, including any query string.
2778@end table
2779
2780The following options are also supported:
2781@table @option
2782@item url
2783The full URL when passing options to the driver explicitly.
2784
2785@item readahead
2786The amount of data to read ahead with each range request to the remote server.
2787This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2788does not have a suffix, it will be assumed to be in bytes. The value must be a
2789multiple of 512 bytes. It defaults to 256k.
2790
2791@item sslverify
2792Whether to verify the remote server's certificate when connecting over SSL. It
2793can have the value 'on' or 'off'. It defaults to 'on'.
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002794
Richard W.M. Jonesa94f83d2014-08-29 16:03:12 +01002795@item cookie
2796Send this cookie (it can also be a list of cookies separated by ';') with
2797each outgoing request. Only supported when using protocols such as HTTP
2798which support cookies, otherwise ignored.
2799
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002800@item timeout
2801Set the timeout in seconds of the CURL connection. This timeout is the time
2802that CURL waits for a response from the remote server to get the size of the
2803image to be downloaded. If not set, the default timeout of 5 seconds is used.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002804@end table
2805
2806Note that when passing options to qemu explicitly, @option{driver} is the value
2807of <protocol>.
2808
2809Example: boot from a remote Fedora 20 live ISO image
2810@example
2811qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
2812
2813qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
2814@end example
2815
2816Example: boot from a remote Fedora 20 cloud image using a local overlay for
2817writes, copy-on-read, and a readahead of 64k
2818@example
2819qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
2820
2821qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
2822@end example
2823
2824Example: boot from an image stored on a VMware vSphere server with a self-signed
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002825certificate using a local overlay for writes, a readahead of 64k and a timeout
2826of 10 seconds.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002827@example
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002828qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
Matthew Booth0a86cb72014-05-14 19:28:43 -04002829
2830qemu-system-x86_64 -drive file=/tmp/test.qcow2
2831@end example
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002832ETEXI
2833
2834STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002835@end table
2836ETEXI
2837
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002838DEFHEADING(Bluetooth(R) options)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002839STEXI
2840@table @option
2841ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002842
blueswir15824d652009-03-28 06:44:27 +00002843DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00002844 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2845 "-bt hci,host[:id]\n" \
2846 " use host's HCI with the given name\n" \
2847 "-bt hci[,vlan=n]\n" \
2848 " emulate a standard HCI in virtual scatternet 'n'\n" \
2849 "-bt vhci[,vlan=n]\n" \
2850 " add host computer to virtual scatternet 'n' using VHCI\n" \
2851 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002852 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2853 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002854STEXI
blueswir15824d652009-03-28 06:44:27 +00002855@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002856@findex -bt
blueswir15824d652009-03-28 06:44:27 +00002857Defines the function of the corresponding Bluetooth HCI. -bt options
2858are matched with the HCIs present in the chosen machine type. For
2859example when emulating a machine with only one HCI built into it, only
2860the first @code{-bt hci[...]} option is valid and defines the HCI's
2861logic. The Transport Layer is decided by the machine type. Currently
2862the machines @code{n800} and @code{n810} have one HCI and all other
2863machines have none.
2864
2865@anchor{bt-hcis}
2866The following three types are recognized:
2867
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002868@table @option
blueswir15824d652009-03-28 06:44:27 +00002869@item -bt hci,null
2870(default) The corresponding Bluetooth HCI assumes no internal logic
2871and will not respond to any HCI commands or emit events.
2872
2873@item -bt hci,host[:@var{id}]
2874(@code{bluez} only) The corresponding HCI passes commands / events
2875to / from the physical HCI identified by the name @var{id} (default:
2876@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2877capable systems like Linux.
2878
2879@item -bt hci[,vlan=@var{n}]
2880Add a virtual, standard HCI that will participate in the Bluetooth
2881scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2882VLANs, devices inside a bluetooth network @var{n} can only communicate
2883with other devices in the same network (scatternet).
2884@end table
2885
2886@item -bt vhci[,vlan=@var{n}]
2887(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2888to the host bluetooth stack instead of to the emulated target. This
2889allows the host and target machines to participate in a common scatternet
2890and communicate. Requires the Linux @code{vhci} driver installed. Can
2891be used as following:
2892
2893@example
Stefan Weil3804da92012-05-11 22:21:50 +02002894qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00002895@end example
2896
2897@item -bt device:@var{dev}[,vlan=@var{n}]
2898Emulate a bluetooth device @var{dev} and place it in network @var{n}
2899(default @code{0}). QEMU can only emulate one type of bluetooth devices
2900currently:
2901
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002902@table @option
blueswir15824d652009-03-28 06:44:27 +00002903@item keyboard
2904Virtual wireless keyboard implementing the HIDP bluetooth profile.
2905@end table
blueswir15824d652009-03-28 06:44:27 +00002906ETEXI
2907
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002908STEXI
2909@end table
2910ETEXI
blueswir15824d652009-03-28 06:44:27 +00002911DEFHEADING()
2912
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002913#ifdef CONFIG_TPM
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002914DEFHEADING(TPM device options)
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002915
2916DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05002917 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2918 " use path to provide path to a character device; default is /dev/tpm0\n"
2919 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
2920 " not provided it will be searched for in /sys/class/misc/tpm?/device\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002921 QEMU_ARCH_ALL)
2922STEXI
2923
2924The general form of a TPM device option is:
2925@table @option
2926
2927@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2928@findex -tpmdev
2929Backend type must be:
Stefan Berger4549a8b2013-02-27 12:47:53 -05002930@option{passthrough}.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002931
2932The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04002933The @code{-tpmdev} option creates the TPM backend and requires a
2934@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002935
2936Options to each backend are described below.
2937
2938Use 'help' to print all available TPM backend types.
2939@example
2940qemu -tpmdev help
2941@end example
2942
Stefan Berger92dcc232013-02-27 12:47:54 -05002943@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05002944
2945(Linux-host only) Enable access to the host's TPM using the passthrough
2946driver.
2947
2948@option{path} specifies the path to the host's TPM device, i.e., on
2949a Linux host this would be @code{/dev/tpm0}.
2950@option{path} is optional and by default @code{/dev/tpm0} is used.
2951
Stefan Berger92dcc232013-02-27 12:47:54 -05002952@option{cancel-path} specifies the path to the host TPM device's sysfs
2953entry allowing for cancellation of an ongoing TPM command.
2954@option{cancel-path} is optional and by default QEMU will search for the
2955sysfs entry to use.
2956
Stefan Berger4549a8b2013-02-27 12:47:53 -05002957Some notes about using the host's TPM with the passthrough driver:
2958
2959The TPM device accessed by the passthrough driver must not be
2960used by any other application on the host.
2961
2962Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2963the VM's firmware (BIOS/UEFI) will not be able to initialize the
2964TPM again and may therefore not show a TPM-specific menu that would
2965otherwise allow the user to configure the TPM, e.g., allow the user to
2966enable/disable or activate/deactivate the TPM.
2967Further, if TPM ownership is released from within a VM then the host's TPM
2968will get disabled and deactivated. To enable and activate the
2969TPM again afterwards, the host has to be rebooted and the user is
2970required to enter the firmware's menu to enable and activate the TPM.
2971If the TPM is left disabled and/or deactivated most TPM commands will fail.
2972
2973To create a passthrough TPM use the following two options:
2974@example
2975-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2976@end example
2977Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2978@code{tpmdev=tpm0} in the device option.
2979
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002980@end table
2981
2982ETEXI
2983
2984DEFHEADING()
2985
2986#endif
2987
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002988DEFHEADING(Linux/Multiboot boot specific)
blueswir15824d652009-03-28 06:44:27 +00002989STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02002990
2991When using these options, you can use a given Linux or Multiboot
2992kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00002993for easier testing of various kernels.
2994
2995@table @option
2996ETEXI
2997
2998DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00002999 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003000STEXI
3001@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003002@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02003003Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3004or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00003005ETEXI
3006
3007DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00003008 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003009STEXI
3010@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003011@findex -append
blueswir15824d652009-03-28 06:44:27 +00003012Use @var{cmdline} as kernel command line
3013ETEXI
3014
3015DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00003016 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003017STEXI
3018@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003019@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00003020Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02003021
3022@item -initrd "@var{file1} arg=foo,@var{file2}"
3023
3024This syntax is only available with multiboot.
3025
3026Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3027first module.
blueswir15824d652009-03-28 06:44:27 +00003028ETEXI
3029
Grant Likely412beee2012-03-02 11:56:38 +00003030DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10003031 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00003032STEXI
3033@item -dtb @var{file}
3034@findex -dtb
3035Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3036on boot.
3037ETEXI
3038
blueswir15824d652009-03-28 06:44:27 +00003039STEXI
3040@end table
3041ETEXI
blueswir15824d652009-03-28 06:44:27 +00003042DEFHEADING()
3043
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003044DEFHEADING(Debug/Expert options)
blueswir15824d652009-03-28 06:44:27 +00003045STEXI
3046@table @option
3047ETEXI
3048
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003049DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3050 "-fw_cfg [name=]<name>,file=<file>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003051 " add named fw_cfg entry with contents from file\n"
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003052 "-fw_cfg [name=]<name>,string=<str>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003053 " add named fw_cfg entry with contents from string\n",
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003054 QEMU_ARCH_ALL)
3055STEXI
Markus Armbruster63d31452016-04-18 18:29:50 +02003056
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003057@item -fw_cfg [name=]@var{name},file=@var{file}
3058@findex -fw_cfg
Markus Armbruster63d31452016-04-18 18:29:50 +02003059Add named fw_cfg entry with contents from file @var{file}.
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003060
3061@item -fw_cfg [name=]@var{name},string=@var{str}
Markus Armbruster63d31452016-04-18 18:29:50 +02003062Add named fw_cfg entry with contents from string @var{str}.
3063
3064The terminating NUL character of the contents of @var{str} will not be
3065included as part of the fw_cfg item data. To insert contents with
3066embedded NUL characters, you have to use the @var{file} parameter.
3067
3068The fw_cfg entries are passed by QEMU through to the guest.
3069
3070Example:
3071@example
3072 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3073@end example
3074creates an fw_cfg entry named opt/com.mycompany/blob with contents
3075from ./my_blob.bin.
3076
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003077ETEXI
3078
blueswir15824d652009-03-28 06:44:27 +00003079DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00003080 "-serial dev redirect the serial port to char device 'dev'\n",
3081 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003082STEXI
3083@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003084@findex -serial
blueswir15824d652009-03-28 06:44:27 +00003085Redirect the virtual serial port to host character device
3086@var{dev}. The default device is @code{vc} in graphical mode and
3087@code{stdio} in non graphical mode.
3088
3089This option can be used several times to simulate up to 4 serial
3090ports.
3091
3092Use @code{-serial none} to disable all serial ports.
3093
3094Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003095@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02003096@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00003097Virtual console. Optionally, a width and height can be given in pixel with
3098@example
3099vc:800x600
3100@end example
3101It is also possible to specify width or height in characters:
3102@example
3103vc:80Cx24C
3104@end example
3105@item pty
3106[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3107@item none
3108No device is allocated.
3109@item null
3110void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01003111@item chardev:@var{id}
3112Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00003113@item /dev/XXX
3114[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3115parameters are set according to the emulated ones.
3116@item /dev/parport@var{N}
3117[Linux only, parallel port only] Use host parallel port
3118@var{N}. Currently SPP and EPP parallel port features can be used.
3119@item file:@var{filename}
3120Write output to @var{filename}. No character can be read.
3121@item stdio
3122[Unix only] standard input/output
3123@item pipe:@var{filename}
3124name pipe @var{filename}
3125@item COM@var{n}
3126[Windows only] Use host serial port @var{n}
3127@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3128This implements UDP Net Console.
3129When @var{remote_host} or @var{src_ip} are not specified
3130they default to @code{0.0.0.0}.
3131When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00003132
3133If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003134@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3135@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00003136will appear in the netconsole session.
3137
3138If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003139and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00003140source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003141udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00003142version of netcat which can listen to a TCP port and send and receive
3143characters via udp. If you have a patched version of netcat which
3144activates telnet remote echo and single char transfer, then you can
Marc-André Lureaubd1caa32016-12-22 18:56:38 +04003145use the following options to set up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003146telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00003147@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02003148@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00003149-serial udp::4555@@:4556
3150@item netcat options:
3151-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3152@item telnet options:
3153localhost 5555
3154@end table
3155
Corey Minyard5dd1f022014-10-02 11:17:37 -05003156@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003157The TCP Net Console has two modes of operation. It can send the serial
3158I/O to a location or wait for a connection from a location. By default
3159the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3160the @var{server} option QEMU will wait for a client socket application
3161to connect to the port before continuing, unless the @code{nowait}
3162option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05003163algorithm. The @code{reconnect} option only applies if @var{noserver} is
3164set, if the connection goes down it will attempt to reconnect at the
3165given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00003166one TCP connection at a time is accepted. You can use @code{telnet} to
3167connect to the corresponding character device.
3168@table @code
3169@item Example to send tcp console to 192.168.0.2 port 4444
3170-serial tcp:192.168.0.2:4444
3171@item Example to listen and wait on port 4444 for connection
3172-serial tcp::4444,server
3173@item Example to not wait and listen on ip 192.168.0.100 port 4444
3174-serial tcp:192.168.0.100:4444,server,nowait
3175@end table
3176
3177@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3178The telnet protocol is used instead of raw tcp sockets. The options
3179work the same as if you had specified @code{-serial tcp}. The
3180difference is that the port acts like a telnet server or client using
3181telnet option negotiation. This will also allow you to send the
3182MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3183sequence. Typically in unix telnet you do it with Control-] and then
3184type "send break" followed by pressing the enter key.
3185
Corey Minyard5dd1f022014-10-02 11:17:37 -05003186@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003187A unix domain socket is used instead of a tcp socket. The option works the
3188same as if you had specified @code{-serial tcp} except the unix domain socket
3189@var{path} is used for connections.
3190
3191@item mon:@var{dev_string}
3192This is a special option to allow the monitor to be multiplexed onto
3193another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04003194@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00003195@var{dev_string} should be any one of the serial devices specified
3196above. An example to multiplex the monitor onto a telnet server
3197listening on port 4444 would be:
3198@table @code
3199@item -serial mon:telnet::4444,server,nowait
3200@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04003201When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3202QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00003203
3204@item braille
3205Braille device. This will use BrlAPI to display the braille output on a real
3206or fake device.
3207
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02003208@item msmouse
3209Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00003210@end table
3211ETEXI
3212
3213DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00003214 "-parallel dev redirect the parallel port to char device 'dev'\n",
3215 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003216STEXI
3217@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003218@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00003219Redirect the virtual parallel port to host device @var{dev} (same
3220devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3221be used to use hardware devices connected on the corresponding host
3222parallel port.
3223
3224This option can be used several times to simulate up to 3 parallel
3225ports.
3226
3227Use @code{-parallel none} to disable all parallel ports.
3228ETEXI
3229
3230DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00003231 "-monitor dev redirect the monitor to char device 'dev'\n",
3232 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003233STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01003234@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003235@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00003236Redirect the monitor to host device @var{dev} (same devices as the
3237serial port).
3238The default device is @code{vc} in graphical mode and @code{stdio} in
3239non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04003240Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00003241ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01003242DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00003243 "-qmp dev like -monitor but opens in 'control' mode\n",
3244 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003245STEXI
3246@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003247@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01003248Like -monitor but opens in 'control' mode.
3249ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01003250DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3251 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3252 QEMU_ARCH_ALL)
3253STEXI
3254@item -qmp-pretty @var{dev}
3255@findex -qmp-pretty
3256Like -qmp but uses pretty JSON formatting.
3257ETEXI
blueswir15824d652009-03-28 06:44:27 +00003258
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003259DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04003260 "-mon [chardev=]name[,mode=readline|control]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003261STEXI
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04003262@item -mon [chardev=]name[,mode=readline|control]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003263@findex -mon
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003264Setup monitor on chardev @var{name}.
3265ETEXI
3266
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003267DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00003268 "-debugcon dev redirect the debug console to char device 'dev'\n",
3269 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003270STEXI
3271@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003272@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003273Redirect the debug console to host device @var{dev} (same devices as the
3274serial port). The debug console is an I/O port which is typically port
32750xe9; writing to that I/O port sends output to this device.
3276The default device is @code{vc} in graphical mode and @code{stdio} in
3277non graphical mode.
3278ETEXI
3279
blueswir15824d652009-03-28 06:44:27 +00003280DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00003281 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003282STEXI
3283@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003284@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00003285Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3286from a script.
3287ETEXI
3288
aurel321b530a62009-04-05 20:08:59 +00003289DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00003290 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00003291STEXI
3292@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01003293@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00003294Run the emulation in single step mode.
3295ETEXI
3296
blueswir15824d652009-03-28 06:44:27 +00003297DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00003298 "-S freeze CPU at startup (use 'c' to start execution)\n",
3299 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003300STEXI
3301@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01003302@findex -S
blueswir15824d652009-03-28 06:44:27 +00003303Do not start CPU at startup (you must type 'c' in the monitor).
3304ETEXI
3305
Satoru Moriya888a6bc2013-04-19 16:42:06 +02003306DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3307 "-realtime [mlock=on|off]\n"
3308 " run qemu with realtime features\n"
3309 " mlock=on|off controls mlock support (default: on)\n",
3310 QEMU_ARCH_ALL)
3311STEXI
3312@item -realtime mlock=on|off
3313@findex -realtime
3314Run qemu with realtime features.
3315mlocking qemu and guest memory can be enabled via @option{mlock=on}
3316(enabled by default).
3317ETEXI
3318
aliguori59030a82009-04-05 18:43:41 +00003319DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00003320 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003321STEXI
aliguori59030a82009-04-05 18:43:41 +00003322@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003323@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00003324Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3325connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003326stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00003327within gdb and establish the connection via a pipe:
3328@example
Stefan Weil3804da92012-05-11 22:21:50 +02003329(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00003330@end example
blueswir15824d652009-03-28 06:44:27 +00003331ETEXI
3332
aliguori59030a82009-04-05 18:43:41 +00003333DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00003334 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3335 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003336STEXI
aliguori59030a82009-04-05 18:43:41 +00003337@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01003338@findex -s
aliguori59030a82009-04-05 18:43:41 +00003339Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3340(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00003341ETEXI
3342
3343DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00003344 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00003345 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003346STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00003347@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003348@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00003349Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00003350ETEXI
3351
Matthew Fernandezc235d732011-06-07 16:32:40 +00003352DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00003353 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00003354 QEMU_ARCH_ALL)
3355STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02003356@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00003357@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00003358Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00003359ETEXI
3360
Alex Bennée35145522016-03-15 14:30:20 +00003361DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3362 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3363 QEMU_ARCH_ALL)
3364STEXI
3365@item -dfilter @var{range1}[,...]
3366@findex -dfilter
3367Filter debug output to that relevant to a range of target addresses. The filter
3368spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3369@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3370addresses and sizes required. For example:
3371@example
3372 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3373@end example
3374Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3375the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3376block starting at 0xffffffc00005f000.
3377ETEXI
3378
blueswir15824d652009-03-28 06:44:27 +00003379DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00003380 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3381 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003382STEXI
3383@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003384@findex -L
blueswir15824d652009-03-28 06:44:27 +00003385Set the directory for the BIOS, VGA BIOS and keymaps.
Richard W.M. Jones37146e72016-05-16 17:34:35 +01003386
3387To list all the data directories, use @code{-L help}.
blueswir15824d652009-03-28 06:44:27 +00003388ETEXI
3389
3390DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00003391 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003392STEXI
3393@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003394@findex -bios
blueswir15824d652009-03-28 06:44:27 +00003395Set the filename for the BIOS.
3396ETEXI
3397
blueswir15824d652009-03-28 06:44:27 +00003398DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00003399 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003400STEXI
3401@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01003402@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00003403Enable KVM full virtualization support. This option is only available
3404if KVM support is enabled when compiling.
3405ETEXI
3406
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003407DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3408 "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386)
3409STEXI
3410@item -enable-hax
3411@findex -enable-hax
3412Enable HAX (Hardware-based Acceleration eXecution) support. This option
3413is only available if HAX support is enabled when compiling. HAX is only
3414applicable to MAC and Windows platform, and thus does not conflict with
3415KVM.
3416ETEXI
3417
aliguorie37630c2009-04-22 15:19:10 +00003418DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00003419 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003420DEF("xen-create", 0, QEMU_OPTION_xen_create,
3421 "-xen-create create domain using xen hypercalls, bypassing xend\n"
Blue Swirlad960902010-03-29 19:23:52 +00003422 " warning: should not be used when xend is in use\n",
3423 QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003424DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3425 "-xen-attach attach to existing xen domain\n"
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003426 " xend will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003427 QEMU_ARCH_ALL)
Paul Durrant1c599472017-03-22 09:39:15 +00003428DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3429 "-xen-domid-restrict restrict set of available xen operations\n"
3430 " to specified domain id. (Does not affect\n"
3431 " xenpv machine type).\n",
3432 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003433STEXI
3434@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003435@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003436Specify xen guest domain @var{id} (XEN only).
3437@item -xen-create
Stefan Weil6616b2a2010-02-05 23:52:05 +01003438@findex -xen-create
Stefan Weil95d5f082010-01-20 22:25:27 +01003439Create domain using xen hypercalls, bypassing xend.
3440Warning: should not be used when xend is in use (XEN only).
3441@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003442@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003443Attach to existing xen domain.
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003444xend will use this when starting QEMU (XEN only).
Paul Durrant1c599472017-03-22 09:39:15 +00003445@findex -xen-domid-restrict
3446Restrict set of available xen operations to specified domain id (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003447ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003448
blueswir15824d652009-03-28 06:44:27 +00003449DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003450 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003451STEXI
3452@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003453@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003454Exit instead of rebooting.
3455ETEXI
3456
3457DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003458 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003459STEXI
3460@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003461@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003462Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3463This allows for instance switching to monitor to commit changes to the
3464disk image.
3465ETEXI
3466
3467DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3468 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003469 " start right away with a saved state (loadvm in monitor)\n",
3470 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003471STEXI
3472@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003473@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003474Start right away with a saved state (@code{loadvm} in monitor)
3475ETEXI
3476
3477#ifndef _WIN32
3478DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003479 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003480#endif
3481STEXI
3482@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003483@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003484Daemonize the QEMU process after initialization. QEMU will not detach from
3485standard IO until it is ready to receive connections on any of its devices.
3486This option is a useful way for external programs to launch QEMU without having
3487to cope with initialization race conditions.
3488ETEXI
3489
3490DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003491 "-option-rom rom load a file, rom, into the option ROM space\n",
3492 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003493STEXI
3494@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003495@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003496Load the contents of @var{file} as an option ROM.
3497This option is useful to load things like EtherBoot.
3498ETEXI
3499
Markus Armbrustere2180522014-10-06 16:19:07 +02003500HXCOMM Silently ignored for compatibility
3501DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003502
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003503HXCOMM Options deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00003504DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3505DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003506
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003507DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Paolo Bonzini78808142012-03-30 10:31:21 +00003508 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003509 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3510 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003511
blueswir15824d652009-03-28 06:44:27 +00003512STEXI
3513
Jan Kiszka68752042009-09-15 13:36:04 +02003514@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003515@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003516Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3517UTC or local time, respectively. @code{localtime} is required for correct date in
3518MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3519format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3520
Michael Tokarev9d85d552014-04-07 13:34:58 +04003521By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003522RTC as accurate reference clock inside the guest, specifically if the host
3523time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003524If you want to isolate the guest time from the host, you can set @option{clock}
3525to @code{rt} instead. To even prevent it from progressing during suspension,
3526you can set it to @code{vm}.
Jan Kiszka68752042009-09-15 13:36:04 +02003527
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003528Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3529specifically with Windows' ACPI HAL. This option will try to figure out how
3530many timer interrupts were not processed by the Windows guest and will
3531re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003532ETEXI
3533
3534DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003535 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003536 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003537 " instruction, enable aligning the host and virtual clocks\n" \
3538 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003539STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003540@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003541@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003542Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003543instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003544then the virtual cpu speed will be automatically adjusted to keep virtual
3545time within a few seconds of real time.
3546
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003547When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003548speed unless @option{sleep=on|off} is specified.
3549With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003550instantly whenever the virtual cpu goes to sleep mode and will not advance
3551if no timer is enabled. This behavior give deterministic execution times from
3552the guest point of view.
3553
blueswir15824d652009-03-28 06:44:27 +00003554Note that while this option can give deterministic behavior, it does not
3555provide cycle accurate emulation. Modern CPUs contain superscalar out of
3556order cores with complex cache hierarchies. The number of instructions
3557executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003558
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003559@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003560to synchronise the host clock and the virtual clock. The goal is to
3561have a guest running at the real frequency imposed by the shift option.
3562Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003563@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003564to inform about the delay.
3565Currently this option does not work when @option{shift} is @code{auto}.
3566Note: The sync algorithm will work for those shift values for which
3567the guest clock runs ahead of the host clock. Typically this happens
3568when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003569
3570When @option{rr} option is specified deterministic record/replay is enabled.
3571Replay log is written into @var{filename} file in record mode and
3572read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003573
3574Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3575at the start of execution recording. In replay mode this option is used
3576to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003577ETEXI
3578
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003579DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003580 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003581 " enable virtual hardware watchdog [default=none]\n",
3582 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003583STEXI
3584@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003585@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003586Create a virtual hardware watchdog device. Once enabled (by a guest
3587action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003588the guest or else the guest will be restarted. Choose a model for
3589which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003590
Xu Wangd7933ef2015-06-11 17:32:05 +02003591The @var{model} is the model of hardware watchdog to emulate. Use
3592@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003593watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003594
3595The following models may be available:
3596@table @option
3597@item ib700
3598iBASE 700 is a very simple ISA watchdog with a single timer.
3599@item i6300esb
3600Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3601dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003602@item diag288
3603A virtual watchdog for s390x backed by the diagnose 288 hypercall
3604(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003605@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003606ETEXI
3607
3608DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3609 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003610 " action when watchdog fires [default=reset]\n",
3611 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003612STEXI
3613@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003614@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003615
3616The @var{action} controls what QEMU will do when the watchdog timer
3617expires.
3618The default is
3619@code{reset} (forcefully reset the guest).
3620Other possible actions are:
3621@code{shutdown} (attempt to gracefully shutdown the guest),
3622@code{poweroff} (forcefully poweroff the guest),
3623@code{pause} (pause the guest),
3624@code{debug} (print a debug message and continue), or
3625@code{none} (do nothing).
3626
3627Note that the @code{shutdown} action requires that the guest responds
3628to ACPI signals, which it may not be able to do in the sort of
3629situations where the watchdog would have expired, and thus
3630@code{-watchdog-action shutdown} is not recommended for production use.
3631
3632Examples:
3633
3634@table @code
3635@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003636@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003637@end table
3638ETEXI
3639
blueswir15824d652009-03-28 06:44:27 +00003640DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003641 "-echr chr set terminal escape character instead of ctrl-a\n",
3642 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003643STEXI
3644
Kevin Wolf4e257e52009-10-09 10:58:36 +02003645@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003646@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003647Change the escape character used for switching to the monitor when using
3648monitor and serial sharing. The default is @code{0x01} when using the
3649@code{-nographic} option. @code{0x01} is equal to pressing
3650@code{Control-a}. You can select a different character from the ascii
3651control keys where 1 through 26 map to Control-a through Control-z. For
3652instance you could use the either of the following to change the escape
3653character to Control-t.
3654@table @code
3655@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003656@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003657@end table
3658ETEXI
3659
3660DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3661 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003662 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003663STEXI
3664@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003665@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003666Set virtio console.
Amit Shah98b19252010-01-20 00:36:52 +05303667
3668This option is maintained for backward compatibility.
3669
3670Please use @code{-device virtconsole} for the new way of invocation.
blueswir15824d652009-03-28 06:44:27 +00003671ETEXI
3672
3673DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003674 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003675STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003676@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003677@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003678Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003679ETEXI
3680
3681DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003682 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003683STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003684@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003685@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003686Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003687ETEXI
3688
3689DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003690 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3691 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3692 "-incoming unix:socketpath\n" \
3693 " prepare for incoming migration, listen on\n" \
3694 " specified protocol and socket address\n" \
3695 "-incoming fd:fd\n" \
3696 "-incoming exec:cmdline\n" \
3697 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003698 " or from given external command\n" \
3699 "-incoming defer\n" \
3700 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003701 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003702STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003703@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003704@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003705@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003706Prepare for incoming migration, listen on a given tcp port.
3707
3708@item -incoming unix:@var{socketpath}
3709Prepare for incoming migration, listen on a given unix socket.
3710
3711@item -incoming fd:@var{fd}
3712Accept incoming migration from a given filedescriptor.
3713
3714@item -incoming exec:@var{cmdline}
3715Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003716
3717@item -incoming defer
3718Wait for the URI to be specified via migrate_incoming. The monitor can
3719be used to change settings (such as migration parameters) prior to issuing
3720the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003721ETEXI
3722
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303723DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3724 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3725STEXI
3726@item -only-migratable
3727@findex -only-migratable
3728Only allow migratable devices. Devices will not be allowed to enter an
3729unmigratable state.
3730ETEXI
3731
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003732DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003733 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003734STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003735@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003736@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003737Don't create default devices. Normally, QEMU sets the default devices like serial
3738port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3739CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3740default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003741ETEXI
3742
blueswir15824d652009-03-28 06:44:27 +00003743#ifndef _WIN32
3744DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003745 "-chroot dir chroot to dir just before starting the VM\n",
3746 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003747#endif
3748STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003749@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003750@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003751Immediately before starting guest execution, chroot to the specified
3752directory. Especially useful in combination with -runas.
3753ETEXI
3754
3755#ifndef _WIN32
3756DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Blue Swirlad960902010-03-29 19:23:52 +00003757 "-runas user change to user id user just before starting the VM\n",
3758 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003759#endif
3760STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003761@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003762@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003763Immediately before starting guest execution, drop root privileges, switching
3764to the specified user.
3765ETEXI
3766
blueswir15824d652009-03-28 06:44:27 +00003767DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3768 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003769 " set OpenBIOS nvram variables\n",
3770 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003771STEXI
3772@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003773@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003774Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3775ETEXI
blueswir15824d652009-03-28 06:44:27 +00003776DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003777 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003778 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3779 QEMU_ARCH_MIPS)
Stefan Weil95d5f082010-01-20 22:25:27 +01003780STEXI
3781@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003782@findex -semihosting
Leon Alrae3b3c1692015-06-19 11:08:43 +01003783Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003784ETEXI
3785DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003786 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3787 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003788QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3789QEMU_ARCH_MIPS)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003790STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003791@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003792@findex -semihosting-config
Leon Alrae3b3c1692015-06-19 11:08:43 +01003793Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003794@table @option
3795@item target=@code{native|gdb|auto}
3796Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3797or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3798during debug sessions and @code{native} otherwise.
3799@item arg=@var{str1},arg=@var{str2},...
3800Allows the user to pass input arguments, and can be used multiple times to build
3801up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3802command line is still supported for backward compatibility. If both the
3803@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3804specified, the former is passed to semihosting as it always takes precedence.
3805@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003806ETEXI
blueswir15824d652009-03-28 06:44:27 +00003807DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003808 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003809STEXI
3810@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003811@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003812Old param mode (ARM only).
3813ETEXI
3814
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003815DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
3816 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
3817 QEMU_ARCH_ALL)
3818STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01003819@item -sandbox @var{arg}
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003820@findex -sandbox
3821Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3822disable it. The default is 'off'.
3823ETEXI
3824
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003825DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003826 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003827STEXI
3828@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003829@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003830Read device configuration from @var{file}. This approach is useful when you want to spawn
3831QEMU process with many command line options but you don't want to exceed the command line
3832character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003833ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003834DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3835 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003836 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003837STEXI
3838@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003839@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003840Write device configuration to @var{file}. The @var{file} can be either filename to save
3841command line and device configuration into file or dash @code{-}) character to print the
3842output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003843ETEXI
Anthony Liguori292444c2010-01-21 10:57:58 -06003844DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3845 "-nodefconfig\n"
Blue Swirlad960902010-03-29 19:23:52 +00003846 " do not load default config files at startup\n",
3847 QEMU_ARCH_ALL)
Anthony Liguori292444c2010-01-21 10:57:58 -06003848STEXI
3849@item -nodefconfig
Stefan Weil6616b2a2010-02-05 23:52:05 +01003850@findex -nodefconfig
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003851Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3852The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3853ETEXI
3854DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3855 "-no-user-config\n"
3856 " do not load user-provided config files at startup\n",
3857 QEMU_ARCH_ALL)
3858STEXI
3859@item -no-user-config
3860@findex -no-user-config
3861The @code{-no-user-config} option makes QEMU not load any of the user-provided
3862config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
3863files from @var{datadir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003864ETEXI
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003865DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03003866 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
Lluís23d15e82011-08-31 20:31:31 +02003867 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003868 QEMU_ARCH_ALL)
3869STEXI
Lluís23d15e82011-08-31 20:31:31 +02003870HXCOMM This line is not accurate, as some sub-options are backend-specific but
3871HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03003872@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003873@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03003874@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003875ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003876
Markus Armbruster31e70d62013-02-13 19:49:37 +01003877HXCOMM Internal use
3878DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3879DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003880
Paul Moore0f669982012-08-03 14:39:21 -04003881#ifdef __linux__
3882DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3883 "-enable-fips enable FIPS 140-2 compliance\n",
3884 QEMU_ARCH_ALL)
3885#endif
3886STEXI
3887@item -enable-fips
3888@findex -enable-fips
3889Enable FIPS 140-2 compliance mode.
3890ETEXI
3891
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003892HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003893DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003894
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003895HXCOMM Deprecated by kvm-pit driver properties
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003896DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003897 "", QEMU_ARCH_I386)
3898
Jan Kiszka4086bde2012-10-05 14:51:41 -03003899HXCOMM Deprecated (ignored)
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003900DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
Jan Kiszka4086bde2012-10-05 14:51:41 -03003901
Jan Kiszkae43d5942012-10-05 14:51:40 -03003902HXCOMM Deprecated by -machine kernel_irqchip=on|off property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003903DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
Jan Kiszkae43d5942012-10-05 14:51:40 -03003904
Jan Kiszka88eed342012-10-05 14:51:44 -03003905HXCOMM Deprecated (ignored)
3906DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
3907
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003908DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3909 "-msg timestamp[=on|off]\n"
3910 " change the format of messages\n"
3911 " on|off controls leading timestamps (default:on)\n",
3912 QEMU_ARCH_ALL)
3913STEXI
3914@item -msg timestamp[=on|off]
3915@findex -msg
3916prepend a timestamp to each log message.(default:on)
3917ETEXI
3918
Amit Shahabfd9ce2014-06-20 18:56:08 +05303919DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3920 "-dump-vmstate <file>\n"
3921 " Output vmstate information in JSON format to file.\n"
3922 " Use the scripts/vmstate-static-checker.py file to\n"
3923 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02003924 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05303925 QEMU_ARCH_ALL)
3926STEXI
3927@item -dump-vmstate @var{file}
3928@findex -dump-vmstate
3929Dump json-encoded vmstate information for current machine type to file
3930in @var{file}
3931ETEXI
3932
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003933STEXI
3934@end table
3935ETEXI
3936DEFHEADING()
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003937DEFHEADING(Generic object creation)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003938STEXI
3939@table @option
3940ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003941
3942DEF("object", HAS_ARG, QEMU_OPTION_object,
3943 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3944 " create a new object of type TYPENAME setting properties\n"
3945 " in the order they are specified. Note that the 'id'\n"
3946 " property must be set. These objects are placed in the\n"
3947 " '/objects' path.\n",
3948 QEMU_ARCH_ALL)
3949STEXI
3950@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3951@findex -object
3952Create a new object of type @var{typename} setting properties
3953in the order they are specified. Note that the 'id'
3954property must be set. These objects are placed in the
3955'/objects' path.
3956
3957@table @option
3958
3959@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off}
3960
3961Creates a memory file backend object, which can be used to back
3962the guest RAM with huge pages. The @option{id} parameter is a
3963unique ID that will be used to reference this memory region
3964when configuring the @option{-numa} argument. The @option{size}
3965option provides the size of the memory region, and accepts
3966common suffixes, eg @option{500M}. The @option{mem-path} provides
3967the path to either a shared memory or huge page filesystem mount.
3968The @option{share} boolean option determines whether the memory
3969region is marked as private to QEMU, or shared. The latter allows
3970a co-operating external process to access the QEMU memory region.
3971
3972@item -object rng-random,id=@var{id},filename=@var{/dev/random}
3973
3974Creates a random number generator backend which obtains entropy from
3975a device on the host. The @option{id} parameter is a unique ID that
3976will be used to reference this entropy backend from the @option{virtio-rng}
3977device. The @option{filename} parameter specifies which file to obtain
3978entropy from and if omitted defaults to @option{/dev/random}.
3979
3980@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
3981
3982Creates a random number generator backend which obtains entropy from
3983an external daemon running on the host. The @option{id} parameter is
3984a unique ID that will be used to reference this entropy backend from
3985the @option{virtio-rng} device. The @option{chardev} parameter is
3986the unique ID of a character device backend that provides the connection
3987to the RNG daemon.
3988
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00003989@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
3990
3991Creates a TLS anonymous credentials object, which can be used to provide
3992TLS support on network backends. The @option{id} parameter is a unique
3993ID which network backends will use to access the credentials. The
3994@option{endpoint} is either @option{server} or @option{client} depending
3995on whether the QEMU network backend that uses the credentials will be
3996acting as a client or as a server. If @option{verify-peer} is enabled
3997(the default) then once the handshake is completed, the peer credentials
3998will be verified, though this is a no-op for anonymous credentials.
3999
4000The @var{dir} parameter tells QEMU where to find the credential
4001files. For server endpoints, this directory may contain a file
4002@var{dh-params.pem} providing diffie-hellman parameters to use
4003for the TLS server. If the file is missing, QEMU will generate
4004a set of DH parameters at startup. This is a computationally
4005expensive operation that consumes random pool entropy, so it is
4006recommended that a persistent set of parameters be generated
4007upfront and saved.
4008
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004009@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off},passwordid=@var{id}
Daniel P. Berrange85bcbc72015-03-13 17:39:26 +00004010
4011Creates a TLS anonymous credentials object, which can be used to provide
4012TLS support on network backends. The @option{id} parameter is a unique
4013ID which network backends will use to access the credentials. The
4014@option{endpoint} is either @option{server} or @option{client} depending
4015on whether the QEMU network backend that uses the credentials will be
4016acting as a client or as a server. If @option{verify-peer} is enabled
4017(the default) then once the handshake is completed, the peer credentials
4018will be verified. With x509 certificates, this implies that the clients
4019must be provided with valid client certificates too.
4020
4021The @var{dir} parameter tells QEMU where to find the credential
4022files. For server endpoints, this directory may contain a file
4023@var{dh-params.pem} providing diffie-hellman parameters to use
4024for the TLS server. If the file is missing, QEMU will generate
4025a set of DH parameters at startup. This is a computationally
4026expensive operation that consumes random pool entropy, so it is
4027recommended that a persistent set of parameters be generated
4028upfront and saved.
4029
4030For x509 certificate credentials the directory will contain further files
4031providing the x509 certificates. The certificates must be stored
4032in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4033@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4034@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4035
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004036For the @var{server-key.pem} and @var{client-key.pem} files which
4037contain sensitive private keys, it is possible to use an encrypted
4038version by providing the @var{passwordid} parameter. This provides
4039the ID of a previously created @code{secret} object containing the
4040password for decryption.
4041
zhanghailiang338d3f42016-03-01 13:37:02 +08004042@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004043
4044Interval @var{t} can't be 0, this filter batches the packet delivery: all
4045packets arriving in a given interval on netdev @var{netdevid} are delayed
4046until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08004047@option{status} is optional that indicate whether the netfilter is
4048on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004049
4050queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4051
4052@option{all}: the filter is attached both to the receive and the transmit
4053 queue of the netdev (default).
4054
4055@option{rx}: the filter is attached to the receive queue of the netdev,
4056 where it will receive packets sent to the netdev.
4057
4058@option{tx}: the filter is attached to the transmit queue of the netdev,
4059 where it will receive packets sent by the netdev.
4060
Zhang Chenf6d3afb2016-03-15 15:41:33 +08004061@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
4062
4063filter-mirror on netdev @var{netdevid},mirror net packet to chardev
4064@var{chardevid}
4065
Zhang Chend46f75b2016-03-17 16:16:26 +08004066@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},
4067outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
4068
4069filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
4070@var{chardevid},and redirect indev's packet to filter.
4071Create a filter-redirector we need to differ outdev id from indev id, id can not
4072be the same. we can just use indev or outdev, but at least one of indev or outdev
4073need to be specified.
4074
Zhang Chen61fcc162017-05-17 10:09:40 +08004075@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid}[,queue=@var{all|rx|tx}]
Zhang Chene6eee8a2016-09-27 10:22:32 +08004076
4077Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4078secondary from primary to keep secondary tcp connection,and rewrite
4079tcp packet to primary from secondary make tcp packet can be handled by
4080client.
4081
4082usage:
4083colo secondary:
4084-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4085-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4086-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4087
Changlong Xiec551cd52016-10-11 13:28:32 +08004088@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004089
4090Dump the network traffic on netdev @var{dev} to the file specified by
4091@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4092The file format is libpcap, so it can be analyzed with tools such as tcpdump
4093or Wireshark.
4094
Zhang Chen7dce4e62016-09-27 10:22:26 +08004095@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},
4096outdev=@var{chardevid}
4097
4098Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4099secondary packet. If the packets are same, we will output primary
4100packet to outdev@var{chardevid}, else we will notify colo-frame
4101do checkpoint and send primary packet to outdev@var{chardevid}.
4102
4103we must use it with the help of filter-mirror and filter-redirector.
4104
4105@example
4106
4107primary:
4108-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4109-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4110-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4111-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4112-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4113-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4114-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4115-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4116-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4117-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4118-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4119-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4120
4121secondary:
4122-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4123-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4124-chardev socket,id=red0,host=3.3.3.3,port=9003
4125-chardev socket,id=red1,host=3.3.3.3,port=9004
4126-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4127-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4128
4129@end example
4130
4131If you want to know the detail of above command line, you can read
4132the colo-compare git log.
4133
Gonglei1653a5f2016-10-28 16:33:23 +08004134@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4135
4136Creates a cryptodev backend which executes crypto opreation from
4137the QEMU cipher APIS. The @var{id} parameter is
4138a unique ID that will be used to reference this cryptodev backend from
4139the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4140which specify the queue number of cryptodev backend, the default of
4141@var{queues} is 1.
4142
4143@example
4144
4145 # qemu-system-x86_64 \
4146 [...] \
4147 -object cryptodev-backend-builtin,id=cryptodev0 \
4148 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4149 [...]
4150@end example
4151
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004152@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4153@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4154
4155Defines a secret to store a password, encryption key, or some other sensitive
4156data. The sensitive data can either be passed directly via the @var{data}
4157parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4158parameter is insecure unless the sensitive data is encrypted.
4159
4160The sensitive data can be provided in raw format (the default), or base64.
4161When encoded as JSON, the raw format only supports valid UTF-8 characters,
4162so base64 is recommended for sending binary data. QEMU will convert from
4163which ever format is provided to the format it needs internally. eg, an
4164RBD password can be provided in raw format, even though it will be base64
4165encoded when passed onto the RBD sever.
4166
4167For added protection, it is possible to encrypt the data associated with
4168a secret using the AES-256-CBC cipher. Use of encryption is indicated
4169by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4170parameter provides the ID of a previously defined secret that contains
4171the AES-256 decryption key. This key should be 32-bytes long and be
4172base64 encoded. The @var{iv} parameter provides the random initialization
4173vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004174base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004175
4176The simplest (insecure) usage is to provide the secret inline
4177
4178@example
4179
4180 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4181
4182@end example
4183
4184The simplest secure usage is to provide the secret via a file
4185
4186 # echo -n "letmein" > mypasswd.txt
4187 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4188
4189For greater security, AES-256-CBC should be used. To illustrate usage,
4190consider the openssl command line tool which can encrypt the data. Note
4191that when encrypting, the plaintext must be padded to the cipher block
4192size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4193
4194First a master key needs to be created in base64 encoding:
4195
4196@example
4197 # openssl rand -base64 32 > key.b64
4198 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4199@end example
4200
4201Each secret to be encrypted needs to have a random initialization vector
4202generated. These do not need to be kept secret
4203
4204@example
4205 # openssl rand -base64 16 > iv.b64
4206 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4207@end example
4208
4209The secret to be defined can now be encrypted, in this case we're
4210telling openssl to base64 encode the result, but it could be left
4211as raw bytes if desired.
4212
4213@example
4214 # SECRET=$(echo -n "letmein" |
4215 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4216@end example
4217
4218When launching QEMU, create a master secret pointing to @code{key.b64}
4219and specify that to be used to decrypt the user password. Pass the
4220contents of @code{iv.b64} to the second secret
4221
4222@example
4223 # $QEMU \
4224 -object secret,id=secmaster0,format=base64,file=key.b64 \
4225 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4226 data=$SECRET,iv=$(<iv.b64)
4227@end example
4228
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004229@end table
4230
4231ETEXI
4232
4233
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004234HXCOMM This is the last statement. Insert new options before this line!
4235STEXI
4236@end table
4237ETEXI