blob: 99af8edf5f30f1eb6f5037396381425148c276e2 [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"
Jan Kiszka6a48ffa2011-10-15 13:43:48 +020034 " supported accelerators are kvm, xen, 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,
55kvm, xen, or tcg can be available. By default, tcg is used. If there is more
56than one accelerator specified, the next one is used if the previous one fails
57to 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"
100 " select accelerator ('-accel help for list')\n"
101 " thread=single|multi (enable multi-threaded TCG)", QEMU_ARCH_ALL)
102STEXI
103@item -accel @var{name}[,prop=@var{value}[,...]]
104@findex -accel
105This is used to enable an accelerator. Depending on the target architecture,
106kvm, xen, or tcg can be available. By default, tcg is used. If there is more
107than one accelerator specified, the next one is used if the previous one fails
108to initialize.
109@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"
142 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
aliguori268a3622009-04-21 22:30:27 +0000143STEXI
Eduardo Habkoste0ee9fd2017-01-23 16:06:31 -0200144@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
145@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100146@findex -numa
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200147Define a NUMA node and assign RAM and VCPUs to it.
Paolo Bonzini7febe362014-05-14 17:43:17 +0800148
Eduardo Habkost4b9a5dd2017-01-23 16:06:32 -0200149@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
150@samp{cpus} option represent a contiguous range of CPU indexes
151(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
152set of VCPUs can be represented by providing multiple @samp{cpus}
153options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
154split between them.
155
156For example, the following option assigns VCPUs 0, 1, 2 and 5 to
157a NUMA node:
158@example
159-numa node,cpus=0-2,cpus=5
160@end example
161
162@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
163assigns RAM from a given memory backend device to a node. If
164@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
165split equally between them.
166
167@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
168if one node uses @samp{memdev}, all of them have to use it.
169
170Note that the -@option{numa} option doesn't allocate any of the
171specified resources, it just assigns existing resources to NUMA
172nodes. This means that one still has to use the @option{-m},
173@option{-smp} options to allocate RAM and VCPUs respectively.
174
aliguori268a3622009-04-21 22:30:27 +0000175ETEXI
176
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100177DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
178 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
179 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
180STEXI
181@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
182@findex -add-fd
183
184Add a file descriptor to an fd set. Valid options are:
185
186@table @option
187@item fd=@var{fd}
188This option defines the file descriptor of which a duplicate is added to fd set.
189The file descriptor cannot be stdin, stdout, or stderr.
190@item set=@var{set}
191This option defines the ID of the fd set to add the file descriptor to.
192@item opaque=@var{opaque}
193This option defines a free-form string that can be used to describe @var{fd}.
194@end table
195
196You can open an image using pre-opened file descriptors from an fd set:
197@example
198qemu-system-i386
199-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
200-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
201-drive file=/dev/fdset/2,index=0,media=disk
202@end example
203ETEXI
204
205DEF("set", HAS_ARG, QEMU_OPTION_set,
206 "-set group.id.arg=value\n"
207 " set <arg> parameter for item <id> of type <group>\n"
208 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
209STEXI
210@item -set @var{group}.@var{id}.@var{arg}=@var{value}
211@findex -set
Michael Tokareve1f3b972016-10-16 17:21:37 +0300212Set parameter @var{arg} for item @var{id} of type @var{group}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100213ETEXI
214
215DEF("global", HAS_ARG, QEMU_OPTION_global,
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200216 "-global driver.property=value\n"
217 "-global driver=driver,property=property,value=value\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100218 " set a global default for a driver property\n",
219 QEMU_ARCH_ALL)
220STEXI
221@item -global @var{driver}.@var{prop}=@var{value}
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200222@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100223@findex -global
224Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
225
226@example
227qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
228@end example
229
230In particular, you can use this to set driver properties for devices which are
231created automatically by the machine model. To create a device which is not
232created automatically and set properties on it, use -@option{device}.
Paolo Bonzini3751d7c2015-04-09 14:16:19 +0200233
Markus Armbrusterae08fd52015-06-15 14:35:58 +0200234-global @var{driver}.@var{prop}=@var{value} is shorthand for -global
235driver=@var{driver},property=@var{prop},value=@var{value}. The
236longhand syntax works even when @var{driver} contains a dot.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100237ETEXI
238
239DEF("boot", HAS_ARG, QEMU_OPTION_boot,
240 "-boot [order=drives][,once=drives][,menu=on|off]\n"
Amos Kongc8a6ae82013-03-19 14:23:27 +0800241 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100242 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
243 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
244 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
245 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
246 QEMU_ARCH_ALL)
247STEXI
Amos Kongc8a6ae82013-03-19 14:23:27 +0800248@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 +0100249@findex -boot
250Specify boot order @var{drives} as a string of drive letters. Valid
Gongleid274e072015-07-03 17:50:57 +0800251drive letters depend on the target architecture. The x86 PC uses: a, b
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100252(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
253from network adapter 1-4), hard disk boot is the default. To apply a
254particular boot order only on the first startup, specify it via
Thomas Huthc0d9f7d2017-02-28 18:40:01 +0100255@option{once}. Note that the @option{order} or @option{once} parameter
256should not be used together with the @option{bootindex} property of
257devices, since the firmware implementations normally do not support both
258at the same time.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100259
260Interactive boot menus/prompts can be enabled via @option{menu=on} as far
261as firmware/BIOS supports them. The default is non-interactive boot.
262
263A splash picture could be passed to bios, enabling user to show it as logo,
264when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
265supports them. Currently Seabios for X86 system support it.
266limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
267format(true color). The resolution should be supported by the SVGA mode, so
268the recommended is 320x240, 640x480, 800x640.
269
270A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
271when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
272reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
273system support it.
274
Amos Kongc8a6ae82013-03-19 14:23:27 +0800275Do strict boot via @option{strict=on} as far as firmware/BIOS
276supports it. This only effects when boot priority is changed by
277bootindex options. The default is non-strict boot.
278
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100279@example
280# try to boot from network first, then from hard disk
281qemu-system-i386 -boot order=nc
282# boot from CD-ROM first, switch back to default order after reboot
283qemu-system-i386 -boot once=d
284# boot with a splash picture for 5 seconds.
285qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
286@end example
287
288Note: The legacy format '-boot @var{drives}' is still supported but its
289use is discouraged as it may be removed from future versions.
290ETEXI
291
292DEF("m", HAS_ARG, QEMU_OPTION_m,
Michael Tokarev89f3ea22016-11-10 17:51:32 +0300293 "-m [size=]megs[,slots=n,maxmem=size]\n"
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100294 " configure guest RAM\n"
Alexander Graf0daba1f2015-06-05 11:05:03 +0200295 " size: initial amount of guest memory\n"
Igor Mammedovc270fb92014-06-02 15:25:02 +0200296 " slots: number of hotplug slots (default: none)\n"
Matthew Rosatob6fe0122014-08-28 11:25:33 -0400297 " maxmem: maximum amount of guest memory (default: none)\n"
298 "NOTE: Some architectures might enforce a specific granularity\n",
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100299 QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100300STEXI
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500301@item -m [size=]@var{megs}[,slots=n,maxmem=size]
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100302@findex -m
Luiz Capitulino9fcc0792015-02-26 14:35:45 -0500303Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
304Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
305megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
306could be used to set amount of hotpluggable memory slots and maximum amount of
307memory. Note that @var{maxmem} must be aligned to the page size.
308
309For example, the following command-line sets the guest startup RAM size to
3101GB, creates 3 slots to hotplug additional memory and sets the maximum
311memory the guest can reach to 4GB:
312
313@example
314qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
315@end example
316
317If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
318be enabled and the guest startup RAM will never increase.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100319ETEXI
320
321DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
322 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
323STEXI
324@item -mem-path @var{path}
325@findex -mem-path
326Allocate guest RAM from a temporarily created file in @var{path}.
327ETEXI
328
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100329DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
330 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
331 QEMU_ARCH_ALL)
332STEXI
333@item -mem-prealloc
334@findex -mem-prealloc
335Preallocate memory when using -mem-path.
336ETEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100337
338DEF("k", HAS_ARG, QEMU_OPTION_k,
339 "-k language use keyboard layout (for example 'fr' for French)\n",
340 QEMU_ARCH_ALL)
341STEXI
342@item -k @var{language}
343@findex -k
344Use keyboard layout @var{language} (for example @code{fr} for
345French). This option is only needed where it is not easy to get raw PC
Samuel Thibault32945472016-06-22 17:48:31 +0200346keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100347display). You don't normally need to use it on PC/Linux or PC/Windows
348hosts.
349
350The available layouts are:
351@example
352ar de-ch es fo fr-ca hu ja mk no pt-br sv
353da en-gb et fr fr-ch is lt nl pl ru th
354de en-us fi fr-be hr it lv nl-be pt sl tr
355@end example
356
357The default is @code{en-us}.
358ETEXI
359
360
361DEF("audio-help", 0, QEMU_OPTION_audio_help,
362 "-audio-help print list of audio drivers and their options\n",
363 QEMU_ARCH_ALL)
364STEXI
365@item -audio-help
366@findex -audio-help
367Will show the audio subsystem help: list of drivers, tunable
368parameters.
369ETEXI
370
371DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
372 "-soundhw c1,... enable audio support\n"
373 " and only specified sound cards (comma separated list)\n"
374 " use '-soundhw help' to get the list of supported cards\n"
375 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
376STEXI
377@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
378@findex -soundhw
379Enable audio and selected sound hardware. Use 'help' to print all
380available sound hardware.
381
382@example
383qemu-system-i386 -soundhw sb16,adlib disk.img
384qemu-system-i386 -soundhw es1370 disk.img
385qemu-system-i386 -soundhw ac97 disk.img
386qemu-system-i386 -soundhw hda disk.img
387qemu-system-i386 -soundhw all disk.img
388qemu-system-i386 -soundhw help
389@end example
390
391Note that Linux's i810_audio OSS kernel (for AC97) module might
392require manually specifying clocking.
393
394@example
395modprobe i810_audio clocking=48000
396@end example
397ETEXI
398
399DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
400 "-balloon none disable balloon device\n"
401 "-balloon virtio[,addr=str]\n"
402 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
403STEXI
404@item -balloon none
405@findex -balloon
406Disable balloon device.
407@item -balloon virtio[,addr=@var{addr}]
408Enable virtio balloon device (default), optionally with PCI address
409@var{addr}.
410ETEXI
411
412DEF("device", HAS_ARG, QEMU_OPTION_device,
413 "-device driver[,prop[=value][,...]]\n"
414 " add device (based on driver)\n"
415 " prop=value,... sets driver properties\n"
416 " use '-device help' to print all possible drivers\n"
417 " use '-device driver,help' to print all possible properties\n",
418 QEMU_ARCH_ALL)
419STEXI
420@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
421@findex -device
422Add device @var{driver}. @var{prop}=@var{value} sets driver
423properties. Valid properties depend on the driver. To get help on
424possible drivers and properties, use @code{-device help} and
425@code{-device @var{driver},help}.
Corey Minyardf8490452015-12-17 12:50:10 -0600426
427Some drivers are:
428@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}]
429
430Add an IPMI BMC. This is a simulation of a hardware management
431interface processor that normally sits on a system. It provides
432a watchdog and the ability to reset and power control the system.
433You need to connect this to an IPMI interface to make it useful
434
435The IPMI slave address to use for the BMC. The default is 0x20.
436This address is the BMC's address on the I2C network of management
437controllers. If you don't know what this means, it is safe to ignore
438it.
439
440@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
441
442Add a connection to an external IPMI BMC simulator. Instead of
443locally emulating the BMC like the above item, instead connect
444to an external entity that provides the IPMI services.
445
446A connection is made to an external BMC simulator. If you do this, it
447is strongly recommended that you use the "reconnect=" chardev option
448to reconnect to the simulator if the connection is lost. Note that if
449this is not used carefully, it can be a security issue, as the
450interface has the ability to send resets, NMIs, and power off the VM.
451It's best if QEMU makes a connection to an external simulator running
452on a secure port on localhost, so neither the simulator nor QEMU is
453exposed to any outside network.
454
455See the "lanserv/README.vm" file in the OpenIPMI library for more
456details on the external interface.
457
458@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
459
460Add a KCS IPMI interafce on the ISA bus. This also adds a
461corresponding ACPI and SMBIOS entries, if appropriate.
462
463@table @option
464@item bmc=@var{id}
465The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
466@item ioport=@var{val}
467Define the I/O address of the interface. The default is 0xca0 for KCS.
468@item irq=@var{val}
469Define the interrupt to use. The default is 5. To disable interrupts,
470set this to 0.
471@end table
472
473@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
474
475Like the KCS interface, but defines a BT interface. The default port is
4760xe4 and the default interrupt is 5.
477
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100478ETEXI
479
480DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000481 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100482 " set the name of the guest\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000483 " string1 sets the window title and string2 the process name (on Linux)\n"
484 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
485 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100486 QEMU_ARCH_ALL)
487STEXI
488@item -name @var{name}
489@findex -name
490Sets the @var{name} of the guest.
491This name will be displayed in the SDL window caption.
492The @var{name} will also be used for the VNC server.
493Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000494Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100495ETEXI
496
497DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
498 "-uuid %08x-%04x-%04x-%04x-%012x\n"
499 " specify machine UUID\n", QEMU_ARCH_ALL)
500STEXI
501@item -uuid @var{uuid}
502@findex -uuid
503Set system UUID.
504ETEXI
505
506STEXI
507@end table
508ETEXI
509DEFHEADING()
510
Paolo Bonzini43f187a2017-01-04 13:50:37 +0100511DEFHEADING(Block device options)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100512STEXI
513@table @option
514ETEXI
515
blueswir15824d652009-03-28 06:44:27 +0000516DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000517 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
518DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000519STEXI
520@item -fda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200521@itemx -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100522@findex -fda
523@findex -fdb
Markus Armbruster92a539d2015-03-17 17:02:20 +0100524Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
blueswir15824d652009-03-28 06:44:27 +0000525ETEXI
526
527DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000528 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
529DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000530DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000531 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
532DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000533STEXI
534@item -hda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200535@itemx -hdb @var{file}
536@itemx -hdc @var{file}
537@itemx -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100538@findex -hda
539@findex -hdb
540@findex -hdc
541@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000542Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
543ETEXI
544
545DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000546 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
547 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000548STEXI
549@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100550@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000551Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
552@option{-cdrom} at the same time). You can use the host CD-ROM by
553using @file{/dev/cdrom} as filename (@pxref{host_drives}).
554ETEXI
555
Markus Armbruster42e5f392017-02-28 22:27:07 +0100556DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
557 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
558 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
559 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
560 " [,driver specific parameters...]\n"
561 " configure a block backend\n", QEMU_ARCH_ALL)
562
blueswir15824d652009-03-28 06:44:27 +0000563DEF("drive", HAS_ARG, QEMU_OPTION_drive,
564 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
565 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100566 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +0200567 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
568 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000569 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +0200570 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +0200571 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
572 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
573 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
574 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +0200575 " [[,iops_size=is]]\n"
Alberto Garcia76f4afb2015-06-08 18:17:44 +0200576 " [[,group=g]]\n"
Blue Swirlad960902010-03-29 19:23:52 +0000577 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000578STEXI
579@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100580@findex -drive
blueswir15824d652009-03-28 06:44:27 +0000581
582Define a new drive. Valid options are:
583
Kevin Wolfb3f046c2009-10-09 10:58:35 +0200584@table @option
blueswir15824d652009-03-28 06:44:27 +0000585@item file=@var{file}
586This option defines which disk image (@pxref{disk_images}) to use with
587this drive. If the filename contains comma, you must double it
588(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +1100589
590Special files such as iSCSI devices can be specified using protocol
591specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +0000592@item if=@var{interface}
593This option defines on which type on interface the drive is connected.
594Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
595@item bus=@var{bus},unit=@var{unit}
596These options define where is connected the drive by defining the bus number and
597the unit id.
598@item index=@var{index}
599This option defines where is connected the drive by using an index in the list
600of available connectors of a given interface type.
601@item media=@var{media}
602This option defines the type of the media: disk or cdrom.
603@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
604These options have the same definition as they have in @option{-hdachs}.
605@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +0400606@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
607(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +0000608@item cache=@var{cache}
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100609@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 +0200610@item aio=@var{aio}
611@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 +0100612@item discard=@var{discard}
613@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 +0000614@item format=@var{format}
615Specify which disk @var{format} will be used rather than detecting
Michael Tokarevd33c8a72016-05-18 15:47:53 +0300616the format. Can be used to specify format=raw to avoid interpreting
blueswir15824d652009-03-28 06:44:27 +0000617an untrusted format header.
618@item serial=@var{serial}
619This option specifies the serial number to assign to the device.
Markus Armbrusterc2cc47a2009-06-18 15:14:10 +0200620@item addr=@var{addr}
621Specify the controller's PCI address (if=virtio only).
Luiz Capitulinoae73e592011-07-12 17:35:08 -0300622@item werror=@var{action},rerror=@var{action}
623Specify which @var{action} to take on write and read errors. Valid actions are:
624"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
625"report" (report the error to the guest), "enospc" (pause QEMU only if the
626host disk is full; report the error to the guest otherwise).
627The default setting is @option{werror=enospc} and @option{rerror=report}.
628@item readonly
629Open drive @option{file} as read-only. Guest write attempts will fail.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000630@item copy-on-read=@var{copy-on-read}
631@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
632file sectors into the image file.
Peter Lieven465bee12014-05-18 00:58:19 +0200633@item detect-zeroes=@var{detect-zeroes}
634@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
635conversion of plain zero writes by the OS to driver specific optimized
636zero write commands. You may even choose "unmap" if @var{discard} is set
637to "unmap" to allow a zero write to be converted to an UNMAP operation.
blueswir15824d652009-03-28 06:44:27 +0000638@end table
639
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100640By default, the @option{cache=writeback} mode is used. It will report data
641writes as completed as soon as the data is present in the host page cache.
642This is safe as long as your guest OS makes sure to correctly flush disk caches
643where needed. If your guest OS does not handle volatile disk write caches
644correctly and your host crashes or loses power, then the guest may experience
645data corruption.
blueswir15824d652009-03-28 06:44:27 +0000646
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100647For such guests, you should consider using @option{cache=writethrough}. This
648means that the host page cache will be used to read and write data, but write
649notification will be sent to the guest only after QEMU has made sure to flush
650each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +0000651
Aurelien Jarnoc304d312009-05-03 23:29:14 +0200652The host page cache can be avoided entirely with @option{cache=none}. This will
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100653attempt to do disk IO directly to the guest's memory. QEMU may still perform
654an internal copy of the data. Note that this is considered a writeback mode and
655the guest OS must handle the disk write cache correctly in order to avoid data
656corruption on host crashes.
blueswir15824d652009-03-28 06:44:27 +0000657
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100658The host page cache can be avoided while only sending write notifications to
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100659the guest when the data has been flushed to the disk using
660@option{cache=directsync}.
blueswir15824d652009-03-28 06:44:27 +0000661
Alexander Graf016f5cf2010-05-26 17:51:49 +0200662In case you don't care about data integrity over host failures, use
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100663@option{cache=unsafe}. This option tells QEMU that it never needs to write any
664data to the disk but can instead keep things in cache. If anything goes wrong,
Stefan Weile7d81002011-12-10 00:19:46 +0100665like your host losing power, the disk storage getting disconnected accidentally,
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100666etc. your image will most probably be rendered unusable. When using
Alexander Grafc3177282010-05-26 21:04:32 +0200667the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +0200668
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000669Copy-on-read avoids accessing the same backing file sectors repeatedly and is
670useful when the backing file is over a slow network. By default copy-on-read
671is off.
672
blueswir15824d652009-03-28 06:44:27 +0000673Instead of @option{-cdrom} you can use:
674@example
Stefan Weil3804da92012-05-11 22:21:50 +0200675qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000676@end example
677
678Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
679use:
680@example
Stefan Weil3804da92012-05-11 22:21:50 +0200681qemu-system-i386 -drive file=file,index=0,media=disk
682qemu-system-i386 -drive file=file,index=1,media=disk
683qemu-system-i386 -drive file=file,index=2,media=disk
684qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +0000685@end example
686
Corey Bryant587ed6b2012-10-18 15:19:34 -0400687You can open an image using pre-opened file descriptors from an fd set:
688@example
689qemu-system-i386
690-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
691-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
692-drive file=/dev/fdset/2,index=0,media=disk
693@end example
694
blueswir15824d652009-03-28 06:44:27 +0000695You can connect a CDROM to the slave of ide0:
696@example
Stefan Weil3804da92012-05-11 22:21:50 +0200697qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000698@end example
699
700If you don't specify the "file=" argument, you define an empty drive:
701@example
Stefan Weil3804da92012-05-11 22:21:50 +0200702qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000703@end example
704
blueswir15824d652009-03-28 06:44:27 +0000705Instead of @option{-fda}, @option{-fdb}, you can use:
706@example
Stefan Weil3804da92012-05-11 22:21:50 +0200707qemu-system-i386 -drive file=file,index=0,if=floppy
708qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +0000709@end example
710
711By default, @var{interface} is "ide" and @var{index} is automatically
712incremented:
713@example
Stefan Weil3804da92012-05-11 22:21:50 +0200714qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +0000715@end example
716is interpreted like:
717@example
Stefan Weil3804da92012-05-11 22:21:50 +0200718qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +0000719@end example
720ETEXI
721
722DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +0000723 "-mtdblock file use 'file' as on-board Flash memory image\n",
724 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000725STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200726@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100727@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +0200728Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +0000729ETEXI
730
731DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +0000732 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000733STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200734@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100735@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +0200736Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +0000737ETEXI
738
739DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +0000740 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000741STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200742@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100743@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +0200744Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +0000745ETEXI
746
blueswir15824d652009-03-28 06:44:27 +0000747DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +0000748 "-snapshot write to temporary files instead of disk image files\n",
749 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000750STEXI
751@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +0100752@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +0000753Write to temporary files instead of disk image files. In this case,
754the raw disk image you use is not written back. You can however force
755the write back by pressing @key{C-a s} (@pxref{disk_images}).
756ETEXI
757
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100758DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
759 "-hdachs c,h,s[,t]\n" \
760 " force hard disk 0 physical geometry and the optional BIOS\n" \
761 " translation (t=none or lba) (usually QEMU can guess them)\n",
Blue Swirlad960902010-03-29 19:23:52 +0000762 QEMU_ARCH_ALL)
Marcelo Tosattic9027602010-03-01 20:25:08 -0300763STEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100764@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
765@findex -hdachs
766Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
767@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
768translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
769all those parameters. This option is useful for old MS-DOS disk
770images.
Markus Armbrusterc70a01e2013-02-13 19:49:40 +0100771ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530772
773DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530774 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
Pradeep Jagadeeshb8bbdb82017-02-28 10:31:46 +0100775 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n"
776 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
777 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
778 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
779 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
780 " [[,throttling.iops-size=is]]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530781 QEMU_ARCH_ALL)
782
783STEXI
784
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530785@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 +0530786@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530787Define a new file system device. Valid options are:
788@table @option
789@item @var{fsdriver}
790This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530791Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530792@item id=@var{id}
793Specifies identifier for this device
794@item path=@var{path}
795Specifies the export path for the file system device. Files under
796this path will be available to the 9p client on the guest.
797@item security_model=@var{security_model}
798Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530799Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530800In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200801credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530802to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530803attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530804file attributes. For "mapped-file" these attributes are stored in the
805hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530806interact with other unix tools. "none" security model is same as
807passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530808set file attributes like ownership. Security model is mandatory
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530809only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530810security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530811@item writeout=@var{writeout}
812This is an optional argument. The only supported value is "immediate".
813This means that host page cache will be used to read and write data but
814write notification will be sent to the guest only when the data has been
815reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +0530816@item readonly
817Enables exporting 9p share as a readonly mount for guests. By default
818read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530819@item socket=@var{socket}
820Enables proxy filesystem driver to use passed socket file for communicating
821with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530822@item sock_fd=@var{sock_fd}
823Enables proxy filesystem driver to use passed socket descriptor for
824communicating with virtfs-proxy-helper. Usually a helper like libvirt
825will create socketpair and pass one of the fds as sock_fd
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530826@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530827
828-fsdev option is used along with -device driver "virtio-9p-pci".
829@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
830Options for virtio-9p-pci driver are:
831@table @option
832@item fsdev=@var{id}
833Specifies the id value specified along with -fsdev option
834@item mount_tag=@var{mount_tag}
835Specifies the tag name to be used by the guest to mount this export point
836@end table
837
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530838ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530839
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530840DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530841 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530842 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530843 QEMU_ARCH_ALL)
844
845STEXI
846
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530847@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 +0530848@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530849
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530850The general form of a Virtual File system pass-through options are:
851@table @option
852@item @var{fsdriver}
853This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530854Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530855@item id=@var{id}
856Specifies identifier for this device
857@item path=@var{path}
858Specifies the export path for the file system device. Files under
859this path will be available to the 9p client on the guest.
860@item security_model=@var{security_model}
861Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530862Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530863In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200864credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530865to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530866attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530867file attributes. For "mapped-file" these attributes are stored in the
868hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530869interact with other unix tools. "none" security model is same as
870passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530871set file attributes like ownership. Security model is mandatory only
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530872for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530873model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530874@item writeout=@var{writeout}
875This is an optional argument. The only supported value is "immediate".
876This means that host page cache will be used to read and write data but
877write notification will be sent to the guest only when the data has been
878reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +0530879@item readonly
880Enables exporting 9p share as a readonly mount for guests. By default
881read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530882@item socket=@var{socket}
883Enables proxy filesystem driver to use passed socket file for
884communicating with virtfs-proxy-helper. Usually a helper like libvirt
885will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530886@item sock_fd
887Enables proxy filesystem driver to use passed 'sock_fd' as the socket
888descriptor for interfacing with virtfs-proxy-helper
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530889@end table
890ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530891
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +0530892DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
893 "-virtfs_synth Create synthetic file system image\n",
894 QEMU_ARCH_ALL)
895STEXI
896@item -virtfs_synth
897@findex -virtfs_synth
898Create synthetic file system image
899ETEXI
900
blueswir15824d652009-03-28 06:44:27 +0000901STEXI
902@end table
903ETEXI
blueswir15824d652009-03-28 06:44:27 +0000904DEFHEADING()
905
Paolo Bonzini43f187a2017-01-04 13:50:37 +0100906DEFHEADING(USB options)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100907STEXI
908@table @option
909ETEXI
910
911DEF("usb", 0, QEMU_OPTION_usb,
912 "-usb enable the USB driver (will be the default soon)\n",
913 QEMU_ARCH_ALL)
914STEXI
915@item -usb
916@findex -usb
917Enable the USB driver (will be the default soon)
918ETEXI
919
920DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
921 "-usbdevice name add the host or guest USB device 'name'\n",
922 QEMU_ARCH_ALL)
923STEXI
924
925@item -usbdevice @var{devname}
926@findex -usbdevice
927Add the USB device @var{devname}. @xref{usb_devices}.
928
929@table @option
930
931@item mouse
932Virtual Mouse. This will override the PS/2 mouse emulation when activated.
933
934@item tablet
935Pointer device that uses absolute coordinates (like a touchscreen). This
936means QEMU is able to report the mouse position without having to grab the
937mouse. Also overrides the PS/2 mouse emulation when activated.
938
939@item disk:[format=@var{format}]:@var{file}
940Mass storage device based on file. The optional @var{format} argument
Michael Tokarevd33c8a72016-05-18 15:47:53 +0300941will be used rather than detecting the format. Can be used to specify
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100942@code{format=raw} to avoid interpreting an untrusted format header.
943
944@item host:@var{bus}.@var{addr}
945Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
946
947@item host:@var{vendor_id}:@var{product_id}
948Pass through the host device identified by @var{vendor_id}:@var{product_id}
949(Linux only).
950
951@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
952Serial converter to host character device @var{dev}, see @code{-serial} for the
953available devices.
954
955@item braille
956Braille device. This will use BrlAPI to display the braille output on a real
957or fake device.
958
959@item net:@var{options}
960Network adapter that supports CDC ethernet and RNDIS protocols.
961
962@end table
963ETEXI
964
965STEXI
966@end table
967ETEXI
968DEFHEADING()
969
Paolo Bonzini43f187a2017-01-04 13:50:37 +0100970DEFHEADING(Display options)
blueswir15824d652009-03-28 06:44:27 +0000971STEXI
972@table @option
973ETEXI
974
Jes Sorensen1472a952011-03-16 13:33:31 +0100975DEF("display", HAS_ARG, QEMU_OPTION_display,
976 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Samuel Thibault87eb2ba2017-01-15 21:30:14 +0100977 " [,window_close=on|off][,gl=on|off]\n"
Robert Hof04ec5a2016-07-26 18:17:11 +0800978 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
979 "-display vnc=<display>[,<optargs>]\n"
980 "-display curses\n"
981 "-display none"
982 " select display type\n"
983 "The default display is equivalent to\n"
984#if defined(CONFIG_GTK)
985 "\t\"-display gtk\"\n"
986#elif defined(CONFIG_SDL)
987 "\t\"-display sdl\"\n"
988#elif defined(CONFIG_COCOA)
989 "\t\"-display cocoa\"\n"
990#elif defined(CONFIG_VNC)
991 "\t\"-vnc localhost:0,to=99,id=default\"\n"
992#else
993 "\t\"-display none\"\n"
994#endif
995 , QEMU_ARCH_ALL)
Jes Sorensen1472a952011-03-16 13:33:31 +0100996STEXI
997@item -display @var{type}
998@findex -display
999Select type of display to use. This option is a replacement for the
1000old style -sdl/-curses/... options. Valid values for @var{type} are
1001@table @option
1002@item sdl
1003Display video output via SDL (usually in a separate graphics
1004window; see the SDL documentation for other possibilities).
1005@item curses
1006Display video output via curses. For graphics device models which
1007support a text mode, QEMU can display this output using a
1008curses/ncurses interface. Nothing is displayed when the graphics
1009device is in graphical mode or if the graphics device does not support
1010a text mode. Generally only the VGA device models support text mode.
Jes Sorensen4171d322011-03-16 13:33:32 +01001011@item none
1012Do not display video output. The guest will still see an emulated
1013graphics card, but its output will not be displayed to the QEMU
1014user. This option differs from the -nographic option in that it
1015only affects what is done with video output; -nographic also changes
1016the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +01001017@item gtk
1018Display video output in a GTK window. This interface provides drop-down
1019menus and other UI elements to configure and control the VM during
1020runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +01001021@item vnc
1022Start a VNC server on display <arg>
Jes Sorensen1472a952011-03-16 13:33:31 +01001023@end table
1024ETEXI
1025
blueswir15824d652009-03-28 06:44:27 +00001026DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +00001027 "-nographic disable graphical output and redirect serial I/Os to console\n",
1028 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001029STEXI
1030@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +01001031@findex -nographic
Colin Lorddc0a3e42016-08-12 15:30:48 -04001032Normally, if QEMU is compiled with graphical window support, it displays
1033output such as guest graphics, guest console, and the QEMU monitor in a
1034window. With this option, you can totally disable graphical output so
1035that QEMU is a simple command line application. The emulated serial port
1036is redirected on the console and muxed with the monitor (unless
1037redirected elsewhere explicitly). Therefore, you can still use QEMU to
1038debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1039switching between the console and monitor.
blueswir15824d652009-03-28 06:44:27 +00001040ETEXI
1041
blueswir15824d652009-03-28 06:44:27 +00001042DEF("curses", 0, QEMU_OPTION_curses,
Robert Hof04ec5a2016-07-26 18:17:11 +08001043 "-curses shorthand for -display curses\n",
Blue Swirlad960902010-03-29 19:23:52 +00001044 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001045STEXI
1046@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001047@findex -curses
Colin Lorddc0a3e42016-08-12 15:30:48 -04001048Normally, if QEMU is compiled with graphical window support, it displays
1049output such as guest graphics, guest console, and the QEMU monitor in a
1050window. With this option, QEMU can display the VGA output when in text
1051mode using a curses/ncurses interface. Nothing is displayed in graphical
1052mode.
blueswir15824d652009-03-28 06:44:27 +00001053ETEXI
1054
blueswir15824d652009-03-28 06:44:27 +00001055DEF("no-frame", 0, QEMU_OPTION_no_frame,
Blue Swirlad960902010-03-29 19:23:52 +00001056 "-no-frame open SDL window without a frame and window decorations\n",
1057 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001058STEXI
1059@item -no-frame
Stefan Weil6616b2a2010-02-05 23:52:05 +01001060@findex -no-frame
blueswir15824d652009-03-28 06:44:27 +00001061Do not use decorations for SDL windows and start them using the whole
1062available screen space. This makes the using QEMU in a dedicated desktop
1063workspace more convenient.
1064ETEXI
1065
blueswir15824d652009-03-28 06:44:27 +00001066DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001067 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1068 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001069STEXI
1070@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001071@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001072Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1073affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +00001074ETEXI
1075
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001076DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001077 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1078 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001079STEXI
1080@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001081@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001082Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1083affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001084ETEXI
1085
blueswir15824d652009-03-28 06:44:27 +00001086DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +00001087 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001088STEXI
1089@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +01001090@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +00001091Disable SDL window close capability.
1092ETEXI
1093
blueswir15824d652009-03-28 06:44:27 +00001094DEF("sdl", 0, QEMU_OPTION_sdl,
Robert Hof04ec5a2016-07-26 18:17:11 +08001095 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001096STEXI
1097@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +01001098@findex -sdl
blueswir15824d652009-03-28 06:44:27 +00001099Enable SDL.
1100ETEXI
1101
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001102DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +03001103 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1104 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1105 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
Marc-André Lureaufe4831b2015-01-13 17:57:51 +01001106 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001107 " [,tls-ciphers=<list>]\n"
1108 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1109 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1110 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1111 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1112 " [,jpeg-wan-compression=[auto|never|always]]\n"
1113 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1114 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +02001115 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1116 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Marc-André Lureau7b525502017-02-12 15:21:18 +04001117 " [,gl=[on|off]][,rendernode=<file>]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001118 " enable spice\n"
1119 " at least one of {port, tls-port} is mandatory\n",
1120 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001121STEXI
1122@item -spice @var{option}[,@var{option}[,...]]
1123@findex -spice
1124Enable the spice remote desktop protocol. Valid options are
1125
1126@table @option
1127
1128@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001129Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001130
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001131@item addr=<addr>
1132Set the IP address spice is listening on. Default is any address.
1133
1134@item ipv4
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001135@itemx ipv6
1136@itemx unix
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001137Force using the specified IP version.
1138
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001139@item password=<secret>
1140Set the password you need to authenticate.
1141
Marc-André Lureau48b3ed02011-05-17 10:40:33 +02001142@item sasl
1143Require that the client use SASL to authenticate with the spice.
1144The exact choice of authentication method used is controlled from the
1145system / user's SASL configuration file for the 'qemu' service. This
1146is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1147unprivileged user, an environment variable SASL_CONF_PATH can be used
1148to make it search alternate locations for the service config.
1149While some SASL auth methods can also provide data encryption (eg GSSAPI),
1150it is recommended that SASL always be combined with the 'tls' and
1151'x509' settings to enable use of SSL and server certificates. This
1152ensures a data encryption preventing compromise of authentication
1153credentials.
1154
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001155@item disable-ticketing
1156Allow client connects without authentication.
1157
Hans de Goeded4970b02011-03-27 16:43:54 +02001158@item disable-copy-paste
1159Disable copy paste between the client and the guest.
1160
Hans de Goede5ad24e52013-06-08 15:37:27 +02001161@item disable-agent-file-xfer
1162Disable spice-vdagent based file-xfer between the client and the guest.
1163
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001164@item tls-port=<nr>
1165Set the TCP port spice is listening on for encrypted channels.
1166
1167@item x509-dir=<dir>
1168Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1169
1170@item x509-key-file=<file>
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001171@itemx x509-key-password=<file>
1172@itemx x509-cert-file=<file>
1173@itemx x509-cacert-file=<file>
1174@itemx x509-dh-key-file=<file>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001175The x509 file names can also be configured individually.
1176
1177@item tls-ciphers=<list>
1178Specify which ciphers to use.
1179
Alon Levyd70d6b32011-12-20 13:05:18 +02001180@item tls-channel=[main|display|cursor|inputs|record|playback]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001181@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001182Force specific channel to be used with or without TLS encryption. The
1183options can be specified multiple times to configure multiple
1184channels. The special name "default" can be used to set the default
1185mode. For channels which are not explicitly forced into one mode the
1186spice client is allowed to pick tls/plaintext as he pleases.
1187
Yonit Halperin9f04e092010-07-14 13:26:34 +03001188@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1189Configure image compression (lossless).
1190Default is auto_glz.
1191
1192@item jpeg-wan-compression=[auto|never|always]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001193@itemx zlib-glz-wan-compression=[auto|never|always]
Yonit Halperin9f04e092010-07-14 13:26:34 +03001194Configure wan image compression (lossy for slow links).
1195Default is auto.
1196
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001197@item streaming-video=[off|all|filter]
Li Zhijian93ca5192016-08-01 12:06:59 +08001198Configure video stream detection. Default is off.
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001199
1200@item agent-mouse=[on|off]
1201Enable/disable passing mouse events via vdagent. Default is on.
1202
1203@item playback-compression=[on|off]
1204Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1205
Yonit Halperin8c957052012-08-21 11:51:59 +03001206@item seamless-migration=[on|off]
1207Enable/disable spice seamless migration. Default is off.
1208
Gerd Hoffmann474114b2015-10-13 15:39:34 +02001209@item gl=[on|off]
1210Enable/disable OpenGL context. Default is off.
1211
Marc-André Lureau7b525502017-02-12 15:21:18 +04001212@item rendernode=<file>
1213DRM render node for OpenGL rendering. If not specified, it will pick
1214the first available. (Since 2.9)
1215
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001216@end table
1217ETEXI
1218
blueswir15824d652009-03-28 06:44:27 +00001219DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001220 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1221 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001222STEXI
1223@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001224@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001225Rotate graphical output 90 deg left (only PXA LCD).
1226ETEXI
1227
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001228DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1229 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1230 QEMU_ARCH_ALL)
1231STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001232@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001233@findex -rotate
1234Rotate graphical output some deg left (only PXA LCD).
1235ETEXI
1236
blueswir15824d652009-03-28 06:44:27 +00001237DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001238 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001239 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001240STEXI
malce4558dc2012-08-27 18:33:21 +04001241@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001242@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001243Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001244@table @option
blueswir15824d652009-03-28 06:44:27 +00001245@item cirrus
1246Cirrus Logic GD5446 Video card. All Windows versions starting from
1247Windows 95 should recognize and use this graphic card. For optimal
1248performances, use 16 bit color depth in the guest and the host OS.
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001249(This card was the default before QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001250@item std
1251Standard VGA card with Bochs VBE extensions. If your guest OS
1252supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1253to use high resolution modes (>= 1280x1024x16) then you should use
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001254this option. (This card is the default since QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001255@item vmware
1256VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1257recent XFree86/XOrg server or Windows guest with a driver for this
1258card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001259@item qxl
1260QXL paravirtual graphic card. It is VGA compatible (including VESA
12612.0 VBE support). Works best with qxl guest drivers installed though.
1262Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001263@item tcx
1264(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1265sun4m machines and offers both 8-bit and 24-bit colour depths at a
1266fixed resolution of 1024x768.
1267@item cg3
1268(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1269for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1270resolutions aimed at people wishing to run older Solaris versions.
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001271@item virtio
1272Virtio VGA card.
blueswir15824d652009-03-28 06:44:27 +00001273@item none
1274Disable VGA card.
1275@end table
1276ETEXI
1277
1278DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001279 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001280STEXI
1281@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001282@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001283Start in full screen.
1284ETEXI
1285
blueswir15824d652009-03-28 06:44:27 +00001286DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001287 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1288 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001289STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001290@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001291@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001292Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001293ETEXI
1294
1295DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Robert Hof04ec5a2016-07-26 18:17:11 +08001296 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001297STEXI
1298@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001299@findex -vnc
Colin Lorddc0a3e42016-08-12 15:30:48 -04001300Normally, if QEMU is compiled with graphical window support, it displays
1301output such as guest graphics, guest console, and the QEMU monitor in a
1302window. With this option, you can have QEMU listen on VNC display
1303@var{display} and redirect the VGA display over the VNC session. It is
1304very useful to enable the usb tablet device when using this option
1305(option @option{-usbdevice tablet}). When using the VNC display, you
1306must use the @option{-k} parameter to set the keyboard layout if you are
1307not using en-us. Valid syntax for the @var{display} is
blueswir15824d652009-03-28 06:44:27 +00001308
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001309@table @option
blueswir15824d652009-03-28 06:44:27 +00001310
Robert Ho99a9a522016-05-31 15:03:09 +08001311@item to=@var{L}
1312
1313With this option, QEMU will try next available VNC @var{display}s, until the
1314number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1315available, e.g. port 5900+@var{display} is already used by another
1316application. By default, to=0.
1317
blueswir15824d652009-03-28 06:44:27 +00001318@item @var{host}:@var{d}
1319
1320TCP connections will only be allowed from @var{host} on display @var{d}.
1321By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1322be omitted in which case the server will accept connections from any host.
1323
Kevin Wolf4e257e52009-10-09 10:58:36 +02001324@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001325
1326Connections will be allowed over UNIX domain sockets where @var{path} is the
1327location of a unix socket to listen for connections on.
1328
1329@item none
1330
1331VNC is initialized but not started. The monitor @code{change} command
1332can be used to later start the VNC server.
1333
1334@end table
1335
1336Following the @var{display} value there may be one or more @var{option} flags
1337separated by commas. Valid options are
1338
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001339@table @option
blueswir15824d652009-03-28 06:44:27 +00001340
1341@item reverse
1342
1343Connect to a listening VNC client via a ``reverse'' connection. The
1344client is specified by the @var{display}. For reverse network
1345connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1346is a TCP port number, not a display number.
1347
Tim Hardeck7536ee42013-01-21 11:04:44 +01001348@item websocket
1349
1350Opens an additional TCP listening port dedicated to VNC Websocket connections.
Daniel P. Berrange275e0d62017-02-03 12:06:45 +00001351If a bare @var{websocket} option is given, the Websocket port is
13525700+@var{display}. An alternative port can be specified with the
1353syntax @code{websocket}=@var{port}.
1354
1355If @var{host} is specified connections will only be allowed from this host.
1356It is possible to control the websocket listen address independently, using
1357the syntax @code{websocket}=@var{host}:@var{port}.
1358
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001359If no TLS credentials are provided, the websocket connection runs in
1360unencrypted mode. If TLS credentials are provided, the websocket connection
1361requires encrypted client connections.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001362
blueswir15824d652009-03-28 06:44:27 +00001363@item password
1364
1365Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001366
1367The password must be set separately using the @code{set_password} command in
1368the @ref{pcsys_monitor}. The syntax to change your password is:
1369@code{set_password <protocol> <password>} where <protocol> could be either
1370"vnc" or "spice".
1371
1372If you would like to change <protocol> password expiration, you should use
1373@code{expire_password <protocol> <expiration-time>} where expiration time could
1374be one of the following options: now, never, +seconds or UNIX time of
1375expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1376to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1377date and time).
1378
1379You can also use keywords "now" or "never" for the expiration time to
1380allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001381
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001382@item tls-creds=@var{ID}
1383
1384Provides the ID of a set of TLS credentials to use to secure the
1385VNC server. They will apply to both the normal VNC server socket
1386and the websocket socket (if enabled). Setting TLS credentials
1387will cause the VNC server socket to enable the VeNCrypt auth
1388mechanism. The credentials should have been previously created
1389using the @option{-object tls-creds} argument.
1390
1391The @option{tls-creds} parameter obsoletes the @option{tls},
1392@option{x509}, and @option{x509verify} options, and as such
1393it is not permitted to set both new and old type options at
1394the same time.
1395
blueswir15824d652009-03-28 06:44:27 +00001396@item tls
1397
1398Require that client use TLS when communicating with the VNC server. This
1399uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1400attack. It is recommended that this option be combined with either the
Kevin Wolf4e257e52009-10-09 10:58:36 +02001401@option{x509} or @option{x509verify} options.
blueswir15824d652009-03-28 06:44:27 +00001402
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001403This option is now deprecated in favor of using the @option{tls-creds}
1404argument.
1405
blueswir15824d652009-03-28 06:44:27 +00001406@item x509=@var{/path/to/certificate/dir}
1407
1408Valid if @option{tls} is specified. Require that x509 credentials are used
1409for negotiating the TLS session. The server will send its x509 certificate
1410to the client. It is recommended that a password be set on the VNC server
1411to provide authentication of the client when this is used. The path following
1412this option specifies where the x509 certificates are to be loaded from.
1413See the @ref{vnc_security} section for details on generating certificates.
1414
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001415This option is now deprecated in favour of using the @option{tls-creds}
1416argument.
1417
blueswir15824d652009-03-28 06:44:27 +00001418@item x509verify=@var{/path/to/certificate/dir}
1419
1420Valid if @option{tls} is specified. Require that x509 credentials are used
1421for negotiating the TLS session. The server will send its x509 certificate
1422to the client, and request that the client send its own x509 certificate.
1423The server will validate the client's certificate against the CA certificate,
1424and reject clients when validation fails. If the certificate authority is
1425trusted, this is a sufficient authentication mechanism. You may still wish
1426to set a password on the VNC server as a second authentication layer. The
1427path following this option specifies where the x509 certificates are to
1428be loaded from. See the @ref{vnc_security} section for details on generating
1429certificates.
1430
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001431This option is now deprecated in favour of using the @option{tls-creds}
1432argument.
1433
blueswir15824d652009-03-28 06:44:27 +00001434@item sasl
1435
1436Require that the client use SASL to authenticate with the VNC server.
1437The exact choice of authentication method used is controlled from the
1438system / user's SASL configuration file for the 'qemu' service. This
1439is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1440unprivileged user, an environment variable SASL_CONF_PATH can be used
1441to make it search alternate locations for the service config.
1442While some SASL auth methods can also provide data encryption (eg GSSAPI),
1443it is recommended that SASL always be combined with the 'tls' and
1444'x509' settings to enable use of SSL and server certificates. This
1445ensures a data encryption preventing compromise of authentication
1446credentials. See the @ref{vnc_security} section for details on using
1447SASL authentication.
1448
1449@item acl
1450
1451Turn on access control lists for checking of the x509 client certificate
1452and SASL party. For x509 certs, the ACL check is made against the
1453certificate's distinguished name. This is something that looks like
1454@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1455made against the username, which depending on the SASL plugin, may
1456include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1457When the @option{acl} flag is set, the initial access list will be
1458empty, with a @code{deny} policy. Thus no one will be allowed to
1459use the VNC server until the ACLs have been loaded. This can be
1460achieved using the @code{acl} monitor command.
1461
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001462@item lossy
1463
1464Enable lossy compression methods (gradient, JPEG, ...). If this
1465option is set, VNC client may receive lossy framebuffer updates
1466depending on its encoding settings. Enabling this option can save
1467a lot of bandwidth at the expense of quality.
1468
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001469@item non-adaptive
1470
1471Disable adaptive encodings. Adaptive encodings are enabled by default.
1472An adaptive encoding will try to detect frequently updated screen regions,
1473and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001474This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001475adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001476like Tight.
1477
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001478@item share=[allow-exclusive|force-shared|ignore]
1479
1480Set display sharing policy. 'allow-exclusive' allows clients to ask
1481for exclusive access. As suggested by the rfb spec this is
1482implemented by dropping other connections. Connecting multiple
1483clients in parallel requires all clients asking for a shared session
1484(vncviewer: -shared switch). This is the default. 'force-shared'
1485disables exclusive client access. Useful for shared desktop sessions,
1486where you don't want someone forgetting specify -shared disconnect
1487everybody else. 'ignore' completely ignores the shared flag and
1488allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001489spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001490
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001491@item key-delay-ms
1492
1493Set keyboard delay, for key down and key up events, in milliseconds.
1494Default is 1. Keyboards are low-bandwidth devices, so this slowdown
1495can help the device and guest to keep up and not lose events in case
1496events are arriving in bulk. Possible causes for the latter are flaky
1497network connections, or scripts for automated testing.
1498
blueswir15824d652009-03-28 06:44:27 +00001499@end table
1500ETEXI
1501
1502STEXI
1503@end table
1504ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001505ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001506
Paolo Bonzini43f187a2017-01-04 13:50:37 +01001507ARCHHEADING(i386 target only, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001508STEXI
1509@table @option
1510ETEXI
1511
blueswir15824d652009-03-28 06:44:27 +00001512DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001513 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1514 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001515STEXI
1516@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001517@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001518Use it when installing Windows 2000 to avoid a disk full bug. After
1519Windows 2000 is installed, you no longer need this option (this option
1520slows down the IDE transfers).
1521ETEXI
1522
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02001523HXCOMM Deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00001524DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001525
blueswir15824d652009-03-28 06:44:27 +00001526DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001527 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1528 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001529STEXI
1530@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001531@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001532Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001533be needed to boot from old floppy disks.
1534ETEXI
1535
blueswir15824d652009-03-28 06:44:27 +00001536DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Shannon Zhaof5d8c8c2015-05-29 11:28:54 +01001537 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
blueswir15824d652009-03-28 06:44:27 +00001538STEXI
1539@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001540@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001541Disable ACPI (Advanced Configuration and Power Interface) support. Use
1542it if your guest OS complains about ACPI problems (PC target machine
1543only).
1544ETEXI
1545
blueswir15824d652009-03-28 06:44:27 +00001546DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001547 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001548STEXI
1549@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001550@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001551Disable HPET support.
1552ETEXI
1553
blueswir15824d652009-03-28 06:44:27 +00001554DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001555 "-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 +00001556 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001557STEXI
1558@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 +01001559@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001560Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001561For file=, take whole ACPI table from the specified files, including all
1562ACPI headers (possible overridden by other options).
1563For data=, only data
1564portion of the table is used, all header information is specified in the
1565command line.
Laszlo Ersekae123742016-01-18 15:12:13 +01001566If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1567fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1568to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1569spec.
blueswir15824d652009-03-28 06:44:27 +00001570ETEXI
1571
aliguorib6f6e3d2009-04-17 18:59:56 +00001572DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1573 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001574 " load SMBIOS entry from binary file\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001575 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1576 " [,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001577 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00001578 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1579 " [,uuid=uuid][,sku=str][,family=str]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001580 " specify SMBIOS type 1 fields\n"
1581 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1582 " [,asset=str][,location=str]\n"
1583 " specify SMBIOS type 2 fields\n"
1584 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1585 " [,sku=str]\n"
1586 " specify SMBIOS type 3 fields\n"
1587 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1588 " [,asset=str][,part=str]\n"
1589 " specify SMBIOS type 4 fields\n"
1590 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001591 " [,asset=str][,part=str][,speed=%d]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001592 " specify SMBIOS type 17 fields\n",
Wei Huangc30e1562015-09-07 10:39:29 +01001593 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
aliguorib6f6e3d2009-04-17 18:59:56 +00001594STEXI
1595@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001596@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00001597Load SMBIOS entry from binary file.
1598
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001599@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 +00001600Specify SMBIOS type 0 fields
1601
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001602@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 +00001603Specify SMBIOS type 1 fields
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05001604
1605@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}]
1606Specify SMBIOS type 2 fields
1607
1608@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1609Specify SMBIOS type 3 fields
1610
1611@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1612Specify SMBIOS type 4 fields
1613
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04001614@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 -05001615Specify SMBIOS type 17 fields
aliguorib6f6e3d2009-04-17 18:59:56 +00001616ETEXI
1617
blueswir15824d652009-03-28 06:44:27 +00001618STEXI
1619@end table
1620ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001621DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00001622
Paolo Bonzini43f187a2017-01-04 13:50:37 +01001623DEFHEADING(Network options)
blueswir15824d652009-03-28 06:44:27 +00001624STEXI
1625@table @option
1626ETEXI
1627
Jan Kiszkaad196a92009-06-24 14:42:28 +02001628HXCOMM Legacy slirp options (now moved to -net user):
1629#ifdef CONFIG_SLIRP
Blue Swirlad960902010-03-29 19:23:52 +00001630DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1631DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1632DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001633#ifndef _WIN32
Blue Swirlad960902010-03-29 19:23:52 +00001634DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001635#endif
1636#endif
1637
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001638DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
blueswir15824d652009-03-28 06:44:27 +00001639#ifdef CONFIG_SLIRP
Samuel Thibault0b11c032016-03-20 12:29:54 +01001640 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1641 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1642 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001643 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n"
Klaus Stengel63d29602012-10-27 19:53:39 +02001644 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001645#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001646 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001647#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001648 " configure a user mode network backend with ID 'str',\n"
1649 " its DHCP server and optional services\n"
blueswir15824d652009-03-28 06:44:27 +00001650#endif
1651#ifdef _WIN32
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001652 "-netdev tap,id=str,ifname=name\n"
1653 " configure a host TAP network backend with ID 'str'\n"
blueswir15824d652009-03-28 06:44:27 +00001654#else
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001655 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001656 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001657 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001658 " [,poll-us=n]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001659 " configure a host TAP network backend with ID 'str'\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001660 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001661 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1662 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1663 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001664 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001665 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1666 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00001667 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001668 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001669 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02001670 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001671 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1672 " 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 +02001673 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02001674 " (only has effect for virtio guests which use MSIX)\n"
1675 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001676 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001677 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08001678 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Jason Wang69e87b32016-07-06 09:57:55 +08001679 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
1680 " spent on busy polling for vhost net\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001681 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1682 " configure a host TAP network backend with ID 'str' that is\n"
1683 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1684 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01001685#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001686#ifdef __linux__
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001687 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1688 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1689 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1690 " [,rxcookie=rxcookie][,offset=offset]\n"
1691 " configure a network backend with ID 'str' connected to\n"
1692 " an Ethernet over L2TPv3 pseudowire.\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001693 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04001694 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001695 " VM to a router and even VM to Host. It is a nearly-universal\n"
1696 " standard (RFC3391). Note - this implementation uses static\n"
1697 " pre-configured tunnels (same as the Linux kernel).\n"
1698 " use 'src=' to specify source address\n"
1699 " use 'dst=' to specify destination address\n"
1700 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08001701 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001702 " use 'dstport=' to specify destination udp port\n"
1703 " use 'ipv6=on' to force v6\n"
1704 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1705 " well as a weak security measure\n"
1706 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1707 " use 'txcookie=0x012345678' to specify a txcookie\n"
1708 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1709 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1710 " use 'pincounter=on' to work around broken counter handling in peer\n"
1711 " use 'offset=X' to add an extra offset between header and data\n"
1712#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001713 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1714 " configure a network backend to connect to another network\n"
1715 " using a socket connection\n"
1716 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1717 " configure a network backend to connect to a multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08001718 " use 'localaddr=addr' to specify the host address to send packets from\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001719 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1720 " configure a network backend to connect to another network\n"
1721 " using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00001722#ifdef CONFIG_VDE
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001723 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1724 " configure a network backend to connect to port 'n' of a vde switch\n"
1725 " running on host and listening for incoming connections on 'socketpath'.\n"
blueswir15824d652009-03-28 06:44:27 +00001726 " Use group 'groupname' and mode 'octalmode' to change default\n"
1727 " ownership and permissions for communication port.\n"
1728#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001729#ifdef CONFIG_NETMAP
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001730 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
Vincenzo Maffione58952132013-11-06 11:44:06 +01001731 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1732 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1733 " netmap device, defaults to '/dev/netmap')\n"
1734#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001735 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1736 " configure a vhost-user network, backed by a chardev 'dev'\n"
1737 "-netdev hubport,id=str,hubid=n\n"
1738 " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL)
1739DEF("net", HAS_ARG, QEMU_OPTION_net,
1740 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1741 " old way to create a new NIC and connect it to VLAN 'n'\n"
1742 " (use the '-device devtype,netdev=str' option if possible instead)\n"
aliguoribb9ea792009-04-21 19:56:28 +00001743 "-net dump[,vlan=n][,file=f][,len=n]\n"
1744 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001745 "-net none use it alone to have zero network devices. If no -net option\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001746 " is provided, the default is '-net nic -net user'\n"
1747 "-net ["
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001748#ifdef CONFIG_SLIRP
1749 "user|"
1750#endif
1751 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001752 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001753#ifdef CONFIG_VDE
1754 "vde|"
1755#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001756#ifdef CONFIG_NETMAP
1757 "netmap|"
1758#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02001759 "socket][,vlan=n][,option][,option][,...]\n"
1760 " old way to initialize a host network interface\n"
1761 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001762STEXI
Blue Swirl609c1da2010-03-18 18:41:49 +00001763@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 +01001764@findex -net
blueswir15824d652009-03-28 06:44:27 +00001765Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
Anthony Liguori0d6b0b12009-08-14 11:20:47 -05001766= 0 is the default). The NIC is an e1000 by default on the PC
Markus Armbruster5607c382009-06-18 15:14:08 +02001767target. Optionally, the MAC address can be changed to @var{mac}, the
1768device address set to @var{addr} (PCI cards only),
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001769and a @var{name} can be assigned for use in monitor commands.
1770Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1771that the card should have; this option currently only affects virtio cards; set
1772@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
Stefan Weil071c9392012-04-07 09:23:36 +02001773NIC is created. QEMU can emulate several different models of network card.
blueswir15824d652009-03-28 06:44:27 +00001774Valid values for @var{type} are
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001775@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
blueswir15824d652009-03-28 06:44:27 +00001776@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1777@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
Peter Maydell585f6032012-10-04 16:22:01 +01001778Not all devices are supported on all targets. Use @code{-net nic,model=help}
blueswir15824d652009-03-28 06:44:27 +00001779for a list of available devices for your target.
1780
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001781@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001782@findex -netdev
Jan Kiszkaad196a92009-06-24 14:42:28 +02001783@item -net user[,@var{option}][,@var{option}][,...]
blueswir15824d652009-03-28 06:44:27 +00001784Use the user mode network stack which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02001785privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00001786
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001787@table @option
Jan Kiszkaad196a92009-06-24 14:42:28 +02001788@item vlan=@var{n}
1789Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1790
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001791@item id=@var{id}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001792@itemx name=@var{name}
Jan Kiszkaad196a92009-06-24 14:42:28 +02001793Assign symbolic name for use in monitor commands.
1794
Samuel Thibault0b11c032016-03-20 12:29:54 +01001795@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
1796be enabled. If neither is specified both protocols are enabled.
1797
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001798@item net=@var{addr}[/@var{mask}]
1799Set IP network address the guest will see. Optionally specify the netmask,
1800either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000180110.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001802
1803@item host=@var{addr}
1804Specify the guest-visible address of the host. Default is the 2nd IP in the
1805guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001806
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001807@item ipv6-net=@var{addr}[/@var{int}]
1808Set IPv6 network address the guest will see (default is fec0::/64). The
1809network prefix is given in the usual hexadecimal IPv6 address
1810notation. The prefix size is optional, and is given as the number of
1811valid top-most bits (default is 64).
Yann Bordenave7aac5312016-03-15 10:31:22 +01001812
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001813@item ipv6-host=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01001814Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
1815the guest network, i.e. xxxx::2.
1816
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02001817@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10001818If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02001819able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10001820to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001821
1822@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02001823Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001824
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001825@item dhcpstart=@var{addr}
1826Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10001827is 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 +02001828
1829@item dns=@var{addr}
1830Specify the guest-visible address of the virtual nameserver. The address must
1831be different from the host address. Default is the 3rd IP in the guest network,
1832i.e. x.x.x.3.
1833
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01001834@item ipv6-dns=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01001835Specify the guest-visible address of the IPv6 virtual nameserver. The address
1836must be different from the host address. Default is the 3rd IP in the guest
1837network, i.e. xxxx::3.
1838
Klaus Stengel63d29602012-10-27 19:53:39 +02001839@item dnssearch=@var{domain}
1840Provides an entry for the domain-search list sent by the built-in
1841DHCP server. More than one domain suffix can be transmitted by specifying
1842this option multiple times. If supported, this will cause the guest to
1843automatically try to append the given domain suffix(es) in case a domain name
1844can not be resolved.
1845
1846Example:
1847@example
1848qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1849@end example
1850
Jan Kiszkaad196a92009-06-24 14:42:28 +02001851@item tftp=@var{dir}
1852When using the user mode network stack, activate a built-in TFTP
1853server. The files in @var{dir} will be exposed as the root of a TFTP server.
1854The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001855@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02001856
1857@item bootfile=@var{file}
1858When using the user mode network stack, broadcast @var{file} as the BOOTP
1859filename. In conjunction with @option{tftp}, this can be used to network boot
1860a guest from a local directory.
1861
1862Example (using pxelinux):
1863@example
Stefan Weil3804da92012-05-11 22:21:50 +02001864qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02001865@end example
1866
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001867@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001868When using the user mode network stack, activate a built-in SMB
1869server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001870transparently. The IP address of the SMB server can be set to @var{addr}. By
1871default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001872
1873In the guest Windows OS, the line:
1874@example
187510.0.2.4 smbserver
1876@end example
1877must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1878or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1879
1880Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1881
Brade2d88302011-09-02 16:53:28 -04001882Note that a SAMBA server must be installed on the host OS.
1883QEMU was tested successfully with smbd versions from Red Hat 9,
1884Fedora Core 3 and OpenSUSE 11.x.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001885
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001886@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001887Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1888the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1889@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001890given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1891be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001892used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001893
1894For example, to redirect host X11 connection from screen 1 to guest
1895screen 0, use the following:
1896
1897@example
1898# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02001899qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001900# this host xterm should open in the guest X11 server
1901xterm -display :1
1902@end example
1903
1904To redirect telnet connections from host port 5555 to telnet port on
1905the guest, use the following:
1906
1907@example
1908# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02001909qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001910telnet localhost 5555
1911@end example
1912
1913Then when you use on the host @code{telnet localhost 5555}, you
1914connect to the guest telnet server.
1915
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001916@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001917@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001918Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02001919to the character device @var{dev} or to a program executed by @var{cmd:command}
1920which gets spawned for each connection. This option can be given multiple times.
1921
Stefan Weil43ffe612012-07-20 23:26:02 +02001922You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02001923lifetime, like in the following example:
1924
1925@example
1926# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1927# the guest accesses it
1928qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
1929@end example
1930
1931Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02001932so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02001933
1934@example
1935# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1936# and connect the TCP stream to its stdin/stdout
1937qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1938@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02001939
1940@end table
1941
1942Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1943processed and applied to -net user. Mixing them with the new configuration
1944syntax gives undefined results. Their use for new applications is discouraged
1945as they will be removed from future versions.
blueswir15824d652009-03-28 06:44:27 +00001946
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001947@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
1948@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 -05001949Connect the host TAP network interface @var{name} to VLAN @var{n}.
1950
1951Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00001952@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001953automatically provides one. The default network configure script is
1954@file{/etc/qemu-ifup} and the default network deconfigure script is
1955@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1956to disable script execution.
1957
1958If running QEMU as an unprivileged user, use the network helper
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10001959@var{helper} to configure the TAP interface and attach it to the bridge.
1960The default network helper executable is @file{/path/to/qemu-bridge-helper}
1961and the default bridge device is @file{br0}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001962
1963@option{fd}=@var{h} can be used to specify the handle of an already
1964opened host TAP interface.
1965
1966Examples:
blueswir15824d652009-03-28 06:44:27 +00001967
1968@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001969#launch a QEMU instance with the default network script
Stefan Weil3804da92012-05-11 22:21:50 +02001970qemu-system-i386 linux.img -net nic -net tap
blueswir15824d652009-03-28 06:44:27 +00001971@end example
1972
blueswir15824d652009-03-28 06:44:27 +00001973@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001974#launch a QEMU instance with two NICs, each one connected
1975#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02001976qemu-system-i386 linux.img \
1977 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1978 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
blueswir15824d652009-03-28 06:44:27 +00001979@end example
1980
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001981@example
1982#launch a QEMU instance with the default network helper to
1983#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02001984qemu-system-i386 linux.img \
Amos Kong420508f2013-10-23 04:49:28 +08001985 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001986@end example
1987
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001988@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001989@itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001990Connect a host TAP network interface to a host bridge device.
1991
1992Use the network helper @var{helper} to configure the TAP interface and
1993attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08001994@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001995device is @file{br0}.
1996
1997Examples:
1998
1999@example
2000#launch a QEMU instance with the default network helper to
2001#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02002002qemu-system-i386 linux.img -net bridge -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002003@end example
2004
2005@example
2006#launch a QEMU instance with the default network helper to
2007#connect a TAP device to bridge qemubr0
Stefan Weil3804da92012-05-11 22:21:50 +02002008qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002009@end example
2010
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002011@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 +02002012@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 +00002013
2014Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
2015machine using a TCP socket connection. If @option{listen} is
2016specified, QEMU waits for incoming connections on @var{port}
2017(@var{host} is optional). @option{connect} is used to connect to
2018another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2019specifies an already opened TCP socket.
2020
2021Example:
2022@example
2023# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002024qemu-system-i386 linux.img \
2025 -net nic,macaddr=52:54:00:12:34:56 \
2026 -net socket,listen=:1234
blueswir15824d652009-03-28 06:44:27 +00002027# connect the VLAN 0 of this instance to the VLAN 0
2028# of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02002029qemu-system-i386 linux.img \
2030 -net nic,macaddr=52:54:00:12:34:57 \
2031 -net socket,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002032@end example
2033
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002034@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002035@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 +00002036
2037Create a VLAN @var{n} shared with another QEMU virtual
2038machines using a UDP multicast socket, effectively making a bus for
2039every QEMU with same multicast address @var{maddr} and @var{port}.
2040NOTES:
2041@enumerate
2042@item
2043Several QEMU can be running on different hosts and share same bus (assuming
2044correct multicast setup for these hosts).
2045@item
2046mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2047@url{http://user-mode-linux.sf.net}.
2048@item
2049Use @option{fd=h} to specify an already opened UDP multicast socket.
2050@end enumerate
2051
2052Example:
2053@example
2054# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002055qemu-system-i386 linux.img \
2056 -net nic,macaddr=52:54:00:12:34:56 \
2057 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002058# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002059qemu-system-i386 linux.img \
2060 -net nic,macaddr=52:54:00:12:34:57 \
2061 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002062# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002063qemu-system-i386 linux.img \
2064 -net nic,macaddr=52:54:00:12:34:58 \
2065 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002066@end example
2067
2068Example (User Mode Linux compat.):
2069@example
2070# launch QEMU instance (note mcast address selected
2071# is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02002072qemu-system-i386 linux.img \
2073 -net nic,macaddr=52:54:00:12:34:56 \
2074 -net socket,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00002075# launch UML
2076/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2077@end example
2078
Mike Ryan3a75e742010-12-01 11:16:47 -08002079Example (send packets from host's 1.2.3.4):
2080@example
Stefan Weil3804da92012-05-11 22:21:50 +02002081qemu-system-i386 linux.img \
2082 -net nic,macaddr=52:54:00:12:34:56 \
2083 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08002084@end example
2085
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002086@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 +02002087@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 +01002088Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
2089protocol to transport Ethernet (and other Layer 2) data frames between
2090two systems. It is present in routers, firewalls and the Linux kernel
2091(from version 3.3 onwards).
2092
2093This transport allows a VM to communicate to another VM, router or firewall directly.
2094
2095@item src=@var{srcaddr}
2096 source address (mandatory)
2097@item dst=@var{dstaddr}
2098 destination address (mandatory)
2099@item udp
2100 select udp encapsulation (default is ip).
2101@item srcport=@var{srcport}
2102 source udp port.
2103@item dstport=@var{dstport}
2104 destination udp port.
2105@item ipv6
2106 force v6, otherwise defaults to v4.
2107@item rxcookie=@var{rxcookie}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002108@itemx txcookie=@var{txcookie}
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002109 Cookies are a weak form of security in the l2tpv3 specification.
2110Their function is mostly to prevent misconfiguration. By default they are 32
2111bit.
2112@item cookie64
2113 Set cookie size to 64 bit instead of the default 32
2114@item counter=off
2115 Force a 'cut-down' L2TPv3 with no counter as in
2116draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2117@item pincounter=on
2118 Work around broken counter handling in peer. This may also help on
2119networks which have packet reorder.
2120@item offset=@var{offset}
2121 Add an extra offset between header and data
2122
2123For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2124on the remote Linux host 1.2.3.4:
2125@example
2126# Setup tunnel on linux host using raw ip as encapsulation
2127# on 1.2.3.4
2128ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2129 encap udp udp_sport 16384 udp_dport 16384
2130ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2131 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2132ifconfig vmtunnel0 mtu 1500
2133ifconfig vmtunnel0 up
2134brctl addif br-lan vmtunnel0
2135
2136
2137# on 4.3.2.1
2138# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2139
2140qemu-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
2141
2142
2143@end example
2144
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002145@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 +02002146@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 +00002147Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2148listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2149and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02002150communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00002151with vde support enabled.
2152
2153Example:
2154@example
2155# launch vde switch
2156vde_switch -F -sock /tmp/myswitch
2157# launch QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002158qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00002159@end example
2160
Stefan Hajnoczi40e8c262013-02-26 11:07:16 +01002161@item -netdev hubport,id=@var{id},hubid=@var{hubid}
2162
2163Create a hub port on QEMU "vlan" @var{hubid}.
2164
2165The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
2166netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2167required hub automatically.
2168
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002169@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002170
2171Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2172be a unix domain socket backed one. The vhost-user uses a specifically defined
2173protocol to pass vhost ioctl replacement messages to an application on the other
2174end of the socket. On non-MSIX guests, the feature can be forced with
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002175@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2176be created for multiqueue vhost-user.
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002177
2178Example:
2179@example
2180qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2181 -numa node,memdev=mem \
Vincenzo Maffione79cad2f2017-02-20 17:45:09 +01002182 -chardev socket,id=chr0,path=/path/to/socket \
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002183 -netdev type=vhost-user,id=net0,chardev=chr0 \
2184 -device virtio-net-pci,netdev=net0
2185@end example
2186
aliguoribb9ea792009-04-21 19:56:28 +00002187@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2188Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2189At most @var{len} bytes (64k by default) per packet are stored. The file format is
2190libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
Thomas Huthd3e0c032015-10-13 12:40:02 +02002191Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
aliguoribb9ea792009-04-21 19:56:28 +00002192
blueswir15824d652009-03-28 06:44:27 +00002193@item -net none
2194Indicate that no network devices should be configured. It is used to
2195override the default configuration (@option{-net nic -net user}) which
2196is activated if no @option{-net} options are provided.
blueswir15824d652009-03-28 06:44:27 +00002197ETEXI
2198
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002199STEXI
2200@end table
2201ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002202DEFHEADING()
2203
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002204DEFHEADING(Character device options)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002205STEXI
2206
2207The general form of a character device option is:
2208@table @option
2209ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002210
2211DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Lin Ma517b3d42016-08-17 01:13:52 +08002212 "-chardev help\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002213 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05002214 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002215 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002216 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002217 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2218 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002219 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02002220 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002221 " [,logfile=PATH][,logappend=on|off]\n"
2222 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002223 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002224 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2225 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2226 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2227 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002228#ifdef _WIN32
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002229 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2230 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002231#else
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002232 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2233 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002234#endif
2235#ifdef CONFIG_BRLAPI
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002236 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002237#endif
2238#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2239 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002240 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2241 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002242#endif
2243#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002244 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2245 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002246#endif
Alon Levycbcc6332011-01-19 10:49:50 +02002247#if defined(CONFIG_SPICE)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002248 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2249 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02002250#endif
Blue Swirlad960902010-03-29 19:23:52 +00002251 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00002252)
2253
2254STEXI
Jan Kiszka97331282010-04-06 16:55:54 +02002255@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002256@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00002257Backend is one of:
2258@option{null},
2259@option{socket},
2260@option{udp},
2261@option{msmouse},
2262@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02002263@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00002264@option{file},
2265@option{pipe},
2266@option{console},
2267@option{serial},
2268@option{pty},
2269@option{stdio},
2270@option{braille},
2271@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002272@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02002273@option{parport},
2274@option{spicevmc}.
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002275@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002276The specific backend will determine the applicable options.
2277
Lin Ma517b3d42016-08-17 01:13:52 +08002278Use "-chardev help" to print all available chardev backend types.
2279
Matthew Booth7273a2d2009-10-30 13:41:12 +00002280All devices must have an id, which can be any string up to 127 characters long.
2281It is used to uniquely identify this device in other command line directives.
2282
Jan Kiszka97331282010-04-06 16:55:54 +02002283A character device may be used in multiplexing mode by multiple front-ends.
Peter Maydella40db1b2016-02-16 17:28:58 +00002284Specify @option{mux=on} to enable this mode.
2285A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2286backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2287If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2288create a multiplexer with your specified ID, and you can then configure multiple
2289front ends to use that chardev ID for their input/output. Up to four different
2290front ends can be connected to a single multiplexed chardev. (Without
2291multiplexing enabled, a chardev can only be used by a single front end.)
2292For instance you could use this to allow a single stdio chardev to be used by
2293two serial ports and the QEMU monitor:
2294
2295@example
2296-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002297-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002298-serial chardev:char0 \
2299-serial chardev:char0
2300@end example
2301
2302You can have more than one multiplexer in a system configuration; for instance
2303you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2304multiplexed between the QEMU monitor and a parallel port:
2305
2306@example
2307-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002308-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002309-parallel chardev:char0 \
2310-chardev tcp,...,mux=on,id=char1 \
2311-serial chardev:char1 \
2312-serial chardev:char1
2313@end example
2314
2315When you're using a multiplexed character device, some escape sequences are
2316interpreted in the input. @xref{mux_keys, Keys in the character backend
2317multiplexer}.
2318
2319Note that some other command line options may implicitly create multiplexed
2320character backends; for instance @option{-serial mon:stdio} creates a
2321multiplexed stdio backend connected to the serial port and the QEMU monitor,
2322and @option{-nographic} also multiplexes the console and the monitor to
2323stdio.
2324
2325There is currently no support for multiplexing in the other direction
2326(where a single QEMU front end takes input and output from multiple chardevs).
Jan Kiszka97331282010-04-06 16:55:54 +02002327
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002328Every backend supports the @option{logfile} option, which supplies the path
2329to a file to record all data transmitted via the backend. The @option{logappend}
2330option controls whether the log file will be truncated or appended to when
2331opened.
2332
2333Further options to each backend are described below.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002334
2335@item -chardev null ,id=@var{id}
2336A void device. This device will not emit any data, and will drop any data it
2337receives. The null backend does not take any options.
2338
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002339@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 +00002340
2341Create a two-way stream socket, which can be either a TCP or a unix socket. A
2342unix socket will be created if @option{path} is specified. Behaviour is
2343undefined if TCP options are specified for a unix socket.
2344
2345@option{server} specifies that the socket shall be a listening socket.
2346
2347@option{nowait} specifies that QEMU should not block waiting for a client to
2348connect to a listening socket.
2349
2350@option{telnet} specifies that traffic on the socket should interpret telnet
2351escape sequences.
2352
Corey Minyard5dd1f022014-10-02 11:17:37 -05002353@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2354the remote end goes away. qemu will delay this many seconds and then attempt
2355to reconnect. Zero disables reconnecting, and is the default.
2356
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002357@option{tls-creds} requests enablement of the TLS protocol for encryption,
2358and specifies the id of the TLS credentials to use for the handshake. The
2359credentials must be previously created with the @option{-object tls-creds}
2360argument.
2361
Matthew Booth7273a2d2009-10-30 13:41:12 +00002362TCP and unix socket options are given below:
2363
2364@table @option
2365
Aurelien Jarno8d533562010-03-27 11:52:05 +01002366@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002367
2368@option{host} for a listening socket specifies the local address to be bound.
2369For a connecting socket species the remote host to connect to. @option{host} is
2370optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2371
2372@option{port} for a listening socket specifies the local port to be bound. For a
2373connecting socket specifies the port on the remote host to connect to.
2374@option{port} can be given as either a port number or a service name.
2375@option{port} is required.
2376
2377@option{to} is only relevant to listening sockets. If it is specified, and
2378@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2379to and including @option{to} until it succeeds. @option{to} must be specified
2380as a port number.
2381
2382@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2383If neither is specified the socket may use either protocol.
2384
2385@option{nodelay} disables the Nagle algorithm.
2386
2387@item unix options: path=@var{path}
2388
2389@option{path} specifies the local path of the unix socket. @option{path} is
2390required.
2391
2392@end table
2393
2394@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2395
2396Sends all traffic from the guest to a remote host over UDP.
2397
2398@option{host} specifies the remote host to connect to. If not specified it
2399defaults to @code{localhost}.
2400
2401@option{port} specifies the port on the remote host to connect to. @option{port}
2402is required.
2403
2404@option{localaddr} specifies the local address to bind to. If not specified it
2405defaults to @code{0.0.0.0}.
2406
2407@option{localport} specifies the local port to bind to. If not specified any
2408available local port will be used.
2409
2410@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2411If neither is specified the device may use either protocol.
2412
2413@item -chardev msmouse ,id=@var{id}
2414
2415Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2416take any options.
2417
2418@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2419
2420Connect to a QEMU text console. @option{vc} may optionally be given a specific
2421size.
2422
2423@option{width} and @option{height} specify the width and height respectively of
2424the console, in pixels.
2425
2426@option{cols} and @option{rows} specify that the console be sized to fit a text
2427console with the given dimensions.
2428
Markus Armbruster4f573782013-07-26 16:44:32 +02002429@item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002430
Markus Armbruster3949e592013-02-06 21:27:24 +01002431Create a ring buffer with fixed size @option{size}.
Stefan Hajnoczie69f7d22016-09-19 11:56:26 +01002432@var{size} must be a power of two and defaults to @code{64K}.
Lei Li51767e72013-01-25 00:03:19 +08002433
Matthew Booth7273a2d2009-10-30 13:41:12 +00002434@item -chardev file ,id=@var{id} ,path=@var{path}
2435
2436Log all traffic received from the guest to a file.
2437
2438@option{path} specifies the path of the file to be opened. This file will be
2439created if it does not already exist, and overwritten if it does. @option{path}
2440is required.
2441
2442@item -chardev pipe ,id=@var{id} ,path=@var{path}
2443
2444Create a two-way connection to the guest. The behaviour differs slightly between
2445Windows hosts and other hosts:
2446
2447On Windows, a single duplex pipe will be created at
2448@file{\\.pipe\@option{path}}.
2449
2450On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2451@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2452received by the guest. Data written by the guest can be read from
2453@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2454be present.
2455
2456@option{path} forms part of the pipe path as described above. @option{path} is
2457required.
2458
2459@item -chardev console ,id=@var{id}
2460
2461Send traffic from the guest to QEMU's standard output. @option{console} does not
2462take any options.
2463
2464@option{console} is only available on Windows hosts.
2465
2466@item -chardev serial ,id=@var{id} ,path=@option{path}
2467
2468Send traffic from the guest to a serial device on the host.
2469
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002470On Unix hosts serial will actually accept any tty device,
2471not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002472
2473@option{path} specifies the name of the serial device to open.
2474
2475@item -chardev pty ,id=@var{id}
2476
2477Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2478not take any options.
2479
2480@option{pty} is not available on Windows hosts.
2481
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002482@item -chardev stdio ,id=@var{id} [,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002483Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002484
2485@option{signal} controls if signals are enabled on the terminal, that includes
2486exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2487default, use @option{signal=off} to disable it.
2488
Matthew Booth7273a2d2009-10-30 13:41:12 +00002489@item -chardev braille ,id=@var{id}
2490
2491Connect to a local BrlAPI server. @option{braille} does not take any options.
2492
2493@item -chardev tty ,id=@var{id} ,path=@var{path}
2494
Matthew Booth7273a2d2009-10-30 13:41:12 +00002495@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002496DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002497
2498@option{path} specifies the path to the tty. @option{path} is required.
2499
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002500@item -chardev parallel ,id=@var{id} ,path=@var{path}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002501@itemx -chardev parport ,id=@var{id} ,path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002502
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002503@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002504
2505Connect to a local parallel port.
2506
2507@option{path} specifies the path to the parallel port device. @option{path} is
2508required.
2509
Alon Levycbcc6332011-01-19 10:49:50 +02002510@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2511
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002512@option{spicevmc} is only available when spice support is built in.
2513
Alon Levycbcc6332011-01-19 10:49:50 +02002514@option{debug} debug level for spicevmc
2515
2516@option{name} name of spice channel to connect to
2517
2518Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002519
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002520@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2521
2522@option{spiceport} is only available when spice support is built in.
2523
2524@option{debug} debug level for spicevmc
2525
2526@option{name} name of spice port to connect to
2527
2528Connect to a spice port, allowing a Spice client to handle the traffic
2529identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002530ETEXI
2531
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002532STEXI
2533@end table
2534ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002535DEFHEADING()
2536
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002537DEFHEADING(Device URL Syntax)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002538STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002539
2540In addition to using normal file images for the emulated storage devices,
2541QEMU can also use networked resources such as iSCSI devices. These are
2542specified using a special URL syntax.
2543
2544@table @option
2545@item iSCSI
2546iSCSI support allows QEMU to access iSCSI resources directly and use as
2547images for the guest storage. Both disk and cdrom images are supported.
2548
2549Syntax for specifying iSCSI LUNs is
2550``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2551
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002552By default qemu will use the iSCSI initiator-name
2553'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2554line or a configuration file.
2555
Peter Lieven5dd7a532015-06-16 13:45:07 +02002556Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2557stalled requests and force a reestablishment of the session. The timeout
Peter Lieven90497362015-06-26 12:18:01 +02002558is specified in seconds. The default is 0 which means no timeout. Libiscsi
25591.15.0 or greater is required for this feature.
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002560
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002561Example (without authentication):
2562@example
Stefan Weil3804da92012-05-11 22:21:50 +02002563qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2564 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2565 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002566@end example
2567
2568Example (CHAP username/password via URL):
2569@example
Stefan Weil3804da92012-05-11 22:21:50 +02002570qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002571@end example
2572
2573Example (CHAP username/password via environment variables):
2574@example
2575LIBISCSI_CHAP_USERNAME="user" \
2576LIBISCSI_CHAP_PASSWORD="password" \
Stefan Weil3804da92012-05-11 22:21:50 +02002577qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002578@end example
2579
2580iSCSI support is an optional feature of QEMU and only available when
2581compiled and linked against libiscsi.
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11002582ETEXI
2583DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2584 "-iscsi [user=user][,password=password]\n"
2585 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
Paolo Bonzini2fe37982013-12-06 16:08:05 +01002586 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
Peter Lieven5dd7a532015-06-16 13:45:07 +02002587 " [,timeout=timeout]\n"
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11002588 " iSCSI session parameters\n", QEMU_ARCH_ALL)
2589STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002590
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002591iSCSI parameters such as username and password can also be specified via
2592a configuration file. See qemu-doc for more information and examples.
2593
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002594@item NBD
2595QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2596as Unix Domain Sockets.
2597
2598Syntax for specifying a NBD device using TCP
2599``nbd:<server-ip>:<port>[:exportname=<export>]''
2600
2601Syntax for specifying a NBD device using Unix Domain Sockets
2602``nbd:unix:<domain-socket>[:exportname=<export>]''
2603
2604
2605Example for TCP
2606@example
Stefan Weil3804da92012-05-11 22:21:50 +02002607qemu-system-i386 --drive file=nbd:192.0.2.1:30000
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002608@end example
2609
2610Example for Unix Domain Sockets
2611@example
Stefan Weil3804da92012-05-11 22:21:50 +02002612qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002613@end example
2614
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01002615@item SSH
2616QEMU supports SSH (Secure Shell) access to remote disks.
2617
2618Examples:
2619@example
2620qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2621qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2622@end example
2623
2624Currently authentication must be done using ssh-agent. Other
2625authentication methods may be supported in future.
2626
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002627@item Sheepdog
2628Sheepdog is a distributed storage system for QEMU.
2629QEMU supports using either local sheepdog devices or remote networked
2630devices.
2631
2632Syntax for specifying a sheepdog device
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002633@example
MORITA Kazutaka1b8bbb42013-02-22 12:39:53 +09002634sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002635@end example
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002636
2637Example
2638@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002639qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002640@end example
2641
Thomas Huth6135c5e2017-02-09 13:10:18 +01002642See also @url{https://sheepdog.github.io/sheepdog/}.
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002643
Bharata B Rao8809e282012-10-24 17:17:53 +05302644@item GlusterFS
Stefan Weil736a83f2016-11-19 20:22:07 +01002645GlusterFS is a user space distributed file system.
Bharata B Rao8809e282012-10-24 17:17:53 +05302646QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2647TCP, Unix Domain Sockets and RDMA transport protocols.
2648
2649Syntax for specifying a VM disk image on GlusterFS volume is
2650@example
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05302651
2652URI:
2653gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
2654
2655JSON:
2656'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
2657@ "server":[@{"type":"tcp","host":"...","port":"..."@},
2658@ @{"type":"unix","socket":"..."@}]@}@}'
Bharata B Rao8809e282012-10-24 17:17:53 +05302659@end example
2660
2661
2662Example
2663@example
Prasanna Kumar Kalever76b55502016-11-02 22:20:38 +05302664URI:
2665qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
2666@ file.debug=9,file.logfile=/var/log/qemu-gluster.log
2667
2668JSON:
2669qemu-system-x86_64 'json:@{"driver":"qcow2",
2670@ "file":@{"driver":"gluster",
2671@ "volume":"testvol","path":"a.img",
2672@ "debug":9,"logfile":"/var/log/qemu-gluster.log",
2673@ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
2674@ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
2675qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
2676@ file.debug=9,file.logfile=/var/log/qemu-gluster.log,
2677@ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
2678@ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
Bharata B Rao8809e282012-10-24 17:17:53 +05302679@end example
2680
2681See also @url{http://www.gluster.org}.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002682
Max Reitz23dce382016-11-02 18:55:37 +01002683@item HTTP/HTTPS/FTP/FTPS
2684QEMU supports read-only access to files accessed over http(s) and ftp(s).
Matthew Booth0a86cb72014-05-14 19:28:43 -04002685
2686Syntax using a single filename:
2687@example
2688<protocol>://[<username>[:<password>]@@]<host>/<path>
2689@end example
2690
2691where:
2692@table @option
2693@item protocol
Max Reitz23dce382016-11-02 18:55:37 +01002694'http', 'https', 'ftp', or 'ftps'.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002695
2696@item username
2697Optional username for authentication to the remote server.
2698
2699@item password
2700Optional password for authentication to the remote server.
2701
2702@item host
2703Address of the remote server.
2704
2705@item path
2706Path on the remote server, including any query string.
2707@end table
2708
2709The following options are also supported:
2710@table @option
2711@item url
2712The full URL when passing options to the driver explicitly.
2713
2714@item readahead
2715The amount of data to read ahead with each range request to the remote server.
2716This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2717does not have a suffix, it will be assumed to be in bytes. The value must be a
2718multiple of 512 bytes. It defaults to 256k.
2719
2720@item sslverify
2721Whether to verify the remote server's certificate when connecting over SSL. It
2722can have the value 'on' or 'off'. It defaults to 'on'.
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002723
Richard W.M. Jonesa94f83d2014-08-29 16:03:12 +01002724@item cookie
2725Send this cookie (it can also be a list of cookies separated by ';') with
2726each outgoing request. Only supported when using protocols such as HTTP
2727which support cookies, otherwise ignored.
2728
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002729@item timeout
2730Set the timeout in seconds of the CURL connection. This timeout is the time
2731that CURL waits for a response from the remote server to get the size of the
2732image to be downloaded. If not set, the default timeout of 5 seconds is used.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002733@end table
2734
2735Note that when passing options to qemu explicitly, @option{driver} is the value
2736of <protocol>.
2737
2738Example: boot from a remote Fedora 20 live ISO image
2739@example
2740qemu-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
2741
2742qemu-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
2743@end example
2744
2745Example: boot from a remote Fedora 20 cloud image using a local overlay for
2746writes, copy-on-read, and a readahead of 64k
2747@example
2748qemu-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
2749
2750qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
2751@end example
2752
2753Example: boot from an image stored on a VMware vSphere server with a self-signed
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002754certificate using a local overlay for writes, a readahead of 64k and a timeout
2755of 10 seconds.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002756@example
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002757qemu-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 -04002758
2759qemu-system-x86_64 -drive file=/tmp/test.qcow2
2760@end example
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002761ETEXI
2762
2763STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002764@end table
2765ETEXI
2766
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002767DEFHEADING(Bluetooth(R) options)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002768STEXI
2769@table @option
2770ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002771
blueswir15824d652009-03-28 06:44:27 +00002772DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00002773 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2774 "-bt hci,host[:id]\n" \
2775 " use host's HCI with the given name\n" \
2776 "-bt hci[,vlan=n]\n" \
2777 " emulate a standard HCI in virtual scatternet 'n'\n" \
2778 "-bt vhci[,vlan=n]\n" \
2779 " add host computer to virtual scatternet 'n' using VHCI\n" \
2780 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002781 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2782 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002783STEXI
blueswir15824d652009-03-28 06:44:27 +00002784@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002785@findex -bt
blueswir15824d652009-03-28 06:44:27 +00002786Defines the function of the corresponding Bluetooth HCI. -bt options
2787are matched with the HCIs present in the chosen machine type. For
2788example when emulating a machine with only one HCI built into it, only
2789the first @code{-bt hci[...]} option is valid and defines the HCI's
2790logic. The Transport Layer is decided by the machine type. Currently
2791the machines @code{n800} and @code{n810} have one HCI and all other
2792machines have none.
2793
2794@anchor{bt-hcis}
2795The following three types are recognized:
2796
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002797@table @option
blueswir15824d652009-03-28 06:44:27 +00002798@item -bt hci,null
2799(default) The corresponding Bluetooth HCI assumes no internal logic
2800and will not respond to any HCI commands or emit events.
2801
2802@item -bt hci,host[:@var{id}]
2803(@code{bluez} only) The corresponding HCI passes commands / events
2804to / from the physical HCI identified by the name @var{id} (default:
2805@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2806capable systems like Linux.
2807
2808@item -bt hci[,vlan=@var{n}]
2809Add a virtual, standard HCI that will participate in the Bluetooth
2810scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2811VLANs, devices inside a bluetooth network @var{n} can only communicate
2812with other devices in the same network (scatternet).
2813@end table
2814
2815@item -bt vhci[,vlan=@var{n}]
2816(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2817to the host bluetooth stack instead of to the emulated target. This
2818allows the host and target machines to participate in a common scatternet
2819and communicate. Requires the Linux @code{vhci} driver installed. Can
2820be used as following:
2821
2822@example
Stefan Weil3804da92012-05-11 22:21:50 +02002823qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00002824@end example
2825
2826@item -bt device:@var{dev}[,vlan=@var{n}]
2827Emulate a bluetooth device @var{dev} and place it in network @var{n}
2828(default @code{0}). QEMU can only emulate one type of bluetooth devices
2829currently:
2830
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002831@table @option
blueswir15824d652009-03-28 06:44:27 +00002832@item keyboard
2833Virtual wireless keyboard implementing the HIDP bluetooth profile.
2834@end table
blueswir15824d652009-03-28 06:44:27 +00002835ETEXI
2836
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002837STEXI
2838@end table
2839ETEXI
blueswir15824d652009-03-28 06:44:27 +00002840DEFHEADING()
2841
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002842#ifdef CONFIG_TPM
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002843DEFHEADING(TPM device options)
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002844
2845DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05002846 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2847 " use path to provide path to a character device; default is /dev/tpm0\n"
2848 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
2849 " not provided it will be searched for in /sys/class/misc/tpm?/device\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002850 QEMU_ARCH_ALL)
2851STEXI
2852
2853The general form of a TPM device option is:
2854@table @option
2855
2856@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2857@findex -tpmdev
2858Backend type must be:
Stefan Berger4549a8b2013-02-27 12:47:53 -05002859@option{passthrough}.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002860
2861The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04002862The @code{-tpmdev} option creates the TPM backend and requires a
2863@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002864
2865Options to each backend are described below.
2866
2867Use 'help' to print all available TPM backend types.
2868@example
2869qemu -tpmdev help
2870@end example
2871
Stefan Berger92dcc232013-02-27 12:47:54 -05002872@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05002873
2874(Linux-host only) Enable access to the host's TPM using the passthrough
2875driver.
2876
2877@option{path} specifies the path to the host's TPM device, i.e., on
2878a Linux host this would be @code{/dev/tpm0}.
2879@option{path} is optional and by default @code{/dev/tpm0} is used.
2880
Stefan Berger92dcc232013-02-27 12:47:54 -05002881@option{cancel-path} specifies the path to the host TPM device's sysfs
2882entry allowing for cancellation of an ongoing TPM command.
2883@option{cancel-path} is optional and by default QEMU will search for the
2884sysfs entry to use.
2885
Stefan Berger4549a8b2013-02-27 12:47:53 -05002886Some notes about using the host's TPM with the passthrough driver:
2887
2888The TPM device accessed by the passthrough driver must not be
2889used by any other application on the host.
2890
2891Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2892the VM's firmware (BIOS/UEFI) will not be able to initialize the
2893TPM again and may therefore not show a TPM-specific menu that would
2894otherwise allow the user to configure the TPM, e.g., allow the user to
2895enable/disable or activate/deactivate the TPM.
2896Further, if TPM ownership is released from within a VM then the host's TPM
2897will get disabled and deactivated. To enable and activate the
2898TPM again afterwards, the host has to be rebooted and the user is
2899required to enter the firmware's menu to enable and activate the TPM.
2900If the TPM is left disabled and/or deactivated most TPM commands will fail.
2901
2902To create a passthrough TPM use the following two options:
2903@example
2904-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2905@end example
2906Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2907@code{tpmdev=tpm0} in the device option.
2908
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002909@end table
2910
2911ETEXI
2912
2913DEFHEADING()
2914
2915#endif
2916
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002917DEFHEADING(Linux/Multiboot boot specific)
blueswir15824d652009-03-28 06:44:27 +00002918STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02002919
2920When using these options, you can use a given Linux or Multiboot
2921kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00002922for easier testing of various kernels.
2923
2924@table @option
2925ETEXI
2926
2927DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00002928 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002929STEXI
2930@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002931@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02002932Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2933or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00002934ETEXI
2935
2936DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00002937 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002938STEXI
2939@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002940@findex -append
blueswir15824d652009-03-28 06:44:27 +00002941Use @var{cmdline} as kernel command line
2942ETEXI
2943
2944DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00002945 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002946STEXI
2947@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002948@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00002949Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02002950
2951@item -initrd "@var{file1} arg=foo,@var{file2}"
2952
2953This syntax is only available with multiboot.
2954
2955Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2956first module.
blueswir15824d652009-03-28 06:44:27 +00002957ETEXI
2958
Grant Likely412beee2012-03-02 11:56:38 +00002959DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10002960 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00002961STEXI
2962@item -dtb @var{file}
2963@findex -dtb
2964Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2965on boot.
2966ETEXI
2967
blueswir15824d652009-03-28 06:44:27 +00002968STEXI
2969@end table
2970ETEXI
blueswir15824d652009-03-28 06:44:27 +00002971DEFHEADING()
2972
Paolo Bonzini43f187a2017-01-04 13:50:37 +01002973DEFHEADING(Debug/Expert options)
blueswir15824d652009-03-28 06:44:27 +00002974STEXI
2975@table @option
2976ETEXI
2977
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04002978DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
2979 "-fw_cfg [name=]<name>,file=<file>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02002980 " add named fw_cfg entry with contents from file\n"
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04002981 "-fw_cfg [name=]<name>,string=<str>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02002982 " add named fw_cfg entry with contents from string\n",
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04002983 QEMU_ARCH_ALL)
2984STEXI
Markus Armbruster63d31452016-04-18 18:29:50 +02002985
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04002986@item -fw_cfg [name=]@var{name},file=@var{file}
2987@findex -fw_cfg
Markus Armbruster63d31452016-04-18 18:29:50 +02002988Add named fw_cfg entry with contents from file @var{file}.
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04002989
2990@item -fw_cfg [name=]@var{name},string=@var{str}
Markus Armbruster63d31452016-04-18 18:29:50 +02002991Add named fw_cfg entry with contents from string @var{str}.
2992
2993The terminating NUL character of the contents of @var{str} will not be
2994included as part of the fw_cfg item data. To insert contents with
2995embedded NUL characters, you have to use the @var{file} parameter.
2996
2997The fw_cfg entries are passed by QEMU through to the guest.
2998
2999Example:
3000@example
3001 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3002@end example
3003creates an fw_cfg entry named opt/com.mycompany/blob with contents
3004from ./my_blob.bin.
3005
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003006ETEXI
3007
blueswir15824d652009-03-28 06:44:27 +00003008DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00003009 "-serial dev redirect the serial port to char device 'dev'\n",
3010 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003011STEXI
3012@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003013@findex -serial
blueswir15824d652009-03-28 06:44:27 +00003014Redirect the virtual serial port to host character device
3015@var{dev}. The default device is @code{vc} in graphical mode and
3016@code{stdio} in non graphical mode.
3017
3018This option can be used several times to simulate up to 4 serial
3019ports.
3020
3021Use @code{-serial none} to disable all serial ports.
3022
3023Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003024@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02003025@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00003026Virtual console. Optionally, a width and height can be given in pixel with
3027@example
3028vc:800x600
3029@end example
3030It is also possible to specify width or height in characters:
3031@example
3032vc:80Cx24C
3033@end example
3034@item pty
3035[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3036@item none
3037No device is allocated.
3038@item null
3039void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01003040@item chardev:@var{id}
3041Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00003042@item /dev/XXX
3043[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3044parameters are set according to the emulated ones.
3045@item /dev/parport@var{N}
3046[Linux only, parallel port only] Use host parallel port
3047@var{N}. Currently SPP and EPP parallel port features can be used.
3048@item file:@var{filename}
3049Write output to @var{filename}. No character can be read.
3050@item stdio
3051[Unix only] standard input/output
3052@item pipe:@var{filename}
3053name pipe @var{filename}
3054@item COM@var{n}
3055[Windows only] Use host serial port @var{n}
3056@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3057This implements UDP Net Console.
3058When @var{remote_host} or @var{src_ip} are not specified
3059they default to @code{0.0.0.0}.
3060When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00003061
3062If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003063@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3064@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00003065will appear in the netconsole session.
3066
3067If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003068and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00003069source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003070udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00003071version of netcat which can listen to a TCP port and send and receive
3072characters via udp. If you have a patched version of netcat which
3073activates telnet remote echo and single char transfer, then you can
Marc-André Lureaubd1caa32016-12-22 18:56:38 +04003074use the following options to set up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003075telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00003076@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02003077@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00003078-serial udp::4555@@:4556
3079@item netcat options:
3080-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3081@item telnet options:
3082localhost 5555
3083@end table
3084
Corey Minyard5dd1f022014-10-02 11:17:37 -05003085@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003086The TCP Net Console has two modes of operation. It can send the serial
3087I/O to a location or wait for a connection from a location. By default
3088the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3089the @var{server} option QEMU will wait for a client socket application
3090to connect to the port before continuing, unless the @code{nowait}
3091option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05003092algorithm. The @code{reconnect} option only applies if @var{noserver} is
3093set, if the connection goes down it will attempt to reconnect at the
3094given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00003095one TCP connection at a time is accepted. You can use @code{telnet} to
3096connect to the corresponding character device.
3097@table @code
3098@item Example to send tcp console to 192.168.0.2 port 4444
3099-serial tcp:192.168.0.2:4444
3100@item Example to listen and wait on port 4444 for connection
3101-serial tcp::4444,server
3102@item Example to not wait and listen on ip 192.168.0.100 port 4444
3103-serial tcp:192.168.0.100:4444,server,nowait
3104@end table
3105
3106@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3107The telnet protocol is used instead of raw tcp sockets. The options
3108work the same as if you had specified @code{-serial tcp}. The
3109difference is that the port acts like a telnet server or client using
3110telnet option negotiation. This will also allow you to send the
3111MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3112sequence. Typically in unix telnet you do it with Control-] and then
3113type "send break" followed by pressing the enter key.
3114
Corey Minyard5dd1f022014-10-02 11:17:37 -05003115@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003116A unix domain socket is used instead of a tcp socket. The option works the
3117same as if you had specified @code{-serial tcp} except the unix domain socket
3118@var{path} is used for connections.
3119
3120@item mon:@var{dev_string}
3121This is a special option to allow the monitor to be multiplexed onto
3122another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04003123@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00003124@var{dev_string} should be any one of the serial devices specified
3125above. An example to multiplex the monitor onto a telnet server
3126listening on port 4444 would be:
3127@table @code
3128@item -serial mon:telnet::4444,server,nowait
3129@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04003130When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3131QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00003132
3133@item braille
3134Braille device. This will use BrlAPI to display the braille output on a real
3135or fake device.
3136
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02003137@item msmouse
3138Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00003139@end table
3140ETEXI
3141
3142DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00003143 "-parallel dev redirect the parallel port to char device 'dev'\n",
3144 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003145STEXI
3146@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003147@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00003148Redirect the virtual parallel port to host device @var{dev} (same
3149devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3150be used to use hardware devices connected on the corresponding host
3151parallel port.
3152
3153This option can be used several times to simulate up to 3 parallel
3154ports.
3155
3156Use @code{-parallel none} to disable all parallel ports.
3157ETEXI
3158
3159DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00003160 "-monitor dev redirect the monitor to char device 'dev'\n",
3161 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003162STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01003163@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003164@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00003165Redirect the monitor to host device @var{dev} (same devices as the
3166serial port).
3167The default device is @code{vc} in graphical mode and @code{stdio} in
3168non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04003169Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00003170ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01003171DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00003172 "-qmp dev like -monitor but opens in 'control' mode\n",
3173 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003174STEXI
3175@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003176@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01003177Like -monitor but opens in 'control' mode.
3178ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01003179DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3180 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3181 QEMU_ARCH_ALL)
3182STEXI
3183@item -qmp-pretty @var{dev}
3184@findex -qmp-pretty
3185Like -qmp but uses pretty JSON formatting.
3186ETEXI
blueswir15824d652009-03-28 06:44:27 +00003187
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003188DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04003189 "-mon [chardev=]name[,mode=readline|control]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003190STEXI
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04003191@item -mon [chardev=]name[,mode=readline|control]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003192@findex -mon
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003193Setup monitor on chardev @var{name}.
3194ETEXI
3195
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003196DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00003197 "-debugcon dev redirect the debug console to char device 'dev'\n",
3198 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003199STEXI
3200@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003201@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003202Redirect the debug console to host device @var{dev} (same devices as the
3203serial port). The debug console is an I/O port which is typically port
32040xe9; writing to that I/O port sends output to this device.
3205The default device is @code{vc} in graphical mode and @code{stdio} in
3206non graphical mode.
3207ETEXI
3208
blueswir15824d652009-03-28 06:44:27 +00003209DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00003210 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003211STEXI
3212@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003213@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00003214Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3215from a script.
3216ETEXI
3217
aurel321b530a62009-04-05 20:08:59 +00003218DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00003219 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00003220STEXI
3221@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01003222@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00003223Run the emulation in single step mode.
3224ETEXI
3225
blueswir15824d652009-03-28 06:44:27 +00003226DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00003227 "-S freeze CPU at startup (use 'c' to start execution)\n",
3228 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003229STEXI
3230@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01003231@findex -S
blueswir15824d652009-03-28 06:44:27 +00003232Do not start CPU at startup (you must type 'c' in the monitor).
3233ETEXI
3234
Satoru Moriya888a6bc2013-04-19 16:42:06 +02003235DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3236 "-realtime [mlock=on|off]\n"
3237 " run qemu with realtime features\n"
3238 " mlock=on|off controls mlock support (default: on)\n",
3239 QEMU_ARCH_ALL)
3240STEXI
3241@item -realtime mlock=on|off
3242@findex -realtime
3243Run qemu with realtime features.
3244mlocking qemu and guest memory can be enabled via @option{mlock=on}
3245(enabled by default).
3246ETEXI
3247
aliguori59030a82009-04-05 18:43:41 +00003248DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00003249 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003250STEXI
aliguori59030a82009-04-05 18:43:41 +00003251@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003252@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00003253Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3254connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003255stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00003256within gdb and establish the connection via a pipe:
3257@example
Stefan Weil3804da92012-05-11 22:21:50 +02003258(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00003259@end example
blueswir15824d652009-03-28 06:44:27 +00003260ETEXI
3261
aliguori59030a82009-04-05 18:43:41 +00003262DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00003263 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3264 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003265STEXI
aliguori59030a82009-04-05 18:43:41 +00003266@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01003267@findex -s
aliguori59030a82009-04-05 18:43:41 +00003268Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3269(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00003270ETEXI
3271
3272DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00003273 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00003274 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003275STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00003276@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003277@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00003278Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00003279ETEXI
3280
Matthew Fernandezc235d732011-06-07 16:32:40 +00003281DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00003282 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00003283 QEMU_ARCH_ALL)
3284STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02003285@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00003286@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00003287Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00003288ETEXI
3289
Alex Bennée35145522016-03-15 14:30:20 +00003290DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3291 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3292 QEMU_ARCH_ALL)
3293STEXI
3294@item -dfilter @var{range1}[,...]
3295@findex -dfilter
3296Filter debug output to that relevant to a range of target addresses. The filter
3297spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3298@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3299addresses and sizes required. For example:
3300@example
3301 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3302@end example
3303Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3304the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3305block starting at 0xffffffc00005f000.
3306ETEXI
3307
blueswir15824d652009-03-28 06:44:27 +00003308DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00003309 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3310 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003311STEXI
3312@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003313@findex -L
blueswir15824d652009-03-28 06:44:27 +00003314Set the directory for the BIOS, VGA BIOS and keymaps.
Richard W.M. Jones37146e72016-05-16 17:34:35 +01003315
3316To list all the data directories, use @code{-L help}.
blueswir15824d652009-03-28 06:44:27 +00003317ETEXI
3318
3319DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00003320 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003321STEXI
3322@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003323@findex -bios
blueswir15824d652009-03-28 06:44:27 +00003324Set the filename for the BIOS.
3325ETEXI
3326
blueswir15824d652009-03-28 06:44:27 +00003327DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00003328 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003329STEXI
3330@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01003331@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00003332Enable KVM full virtualization support. This option is only available
3333if KVM support is enabled when compiling.
3334ETEXI
3335
Vincent Palatinb0cb0a62017-01-10 11:59:57 +01003336DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3337 "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386)
3338STEXI
3339@item -enable-hax
3340@findex -enable-hax
3341Enable HAX (Hardware-based Acceleration eXecution) support. This option
3342is only available if HAX support is enabled when compiling. HAX is only
3343applicable to MAC and Windows platform, and thus does not conflict with
3344KVM.
3345ETEXI
3346
aliguorie37630c2009-04-22 15:19:10 +00003347DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00003348 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003349DEF("xen-create", 0, QEMU_OPTION_xen_create,
3350 "-xen-create create domain using xen hypercalls, bypassing xend\n"
Blue Swirlad960902010-03-29 19:23:52 +00003351 " warning: should not be used when xend is in use\n",
3352 QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003353DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3354 "-xen-attach attach to existing xen domain\n"
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003355 " xend will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003356 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003357STEXI
3358@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003359@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003360Specify xen guest domain @var{id} (XEN only).
3361@item -xen-create
Stefan Weil6616b2a2010-02-05 23:52:05 +01003362@findex -xen-create
Stefan Weil95d5f082010-01-20 22:25:27 +01003363Create domain using xen hypercalls, bypassing xend.
3364Warning: should not be used when xend is in use (XEN only).
3365@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003366@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003367Attach to existing xen domain.
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003368xend will use this when starting QEMU (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003369ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003370
blueswir15824d652009-03-28 06:44:27 +00003371DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003372 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003373STEXI
3374@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003375@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003376Exit instead of rebooting.
3377ETEXI
3378
3379DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003380 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003381STEXI
3382@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003383@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003384Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3385This allows for instance switching to monitor to commit changes to the
3386disk image.
3387ETEXI
3388
3389DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3390 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003391 " start right away with a saved state (loadvm in monitor)\n",
3392 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003393STEXI
3394@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003395@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003396Start right away with a saved state (@code{loadvm} in monitor)
3397ETEXI
3398
3399#ifndef _WIN32
3400DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003401 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003402#endif
3403STEXI
3404@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003405@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003406Daemonize the QEMU process after initialization. QEMU will not detach from
3407standard IO until it is ready to receive connections on any of its devices.
3408This option is a useful way for external programs to launch QEMU without having
3409to cope with initialization race conditions.
3410ETEXI
3411
3412DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003413 "-option-rom rom load a file, rom, into the option ROM space\n",
3414 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003415STEXI
3416@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003417@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003418Load the contents of @var{file} as an option ROM.
3419This option is useful to load things like EtherBoot.
3420ETEXI
3421
Markus Armbrustere2180522014-10-06 16:19:07 +02003422HXCOMM Silently ignored for compatibility
3423DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003424
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003425HXCOMM Options deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00003426DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3427DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003428
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003429DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Paolo Bonzini78808142012-03-30 10:31:21 +00003430 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003431 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3432 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003433
blueswir15824d652009-03-28 06:44:27 +00003434STEXI
3435
Jan Kiszka68752042009-09-15 13:36:04 +02003436@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003437@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003438Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3439UTC or local time, respectively. @code{localtime} is required for correct date in
3440MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3441format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3442
Michael Tokarev9d85d552014-04-07 13:34:58 +04003443By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003444RTC as accurate reference clock inside the guest, specifically if the host
3445time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003446If you want to isolate the guest time from the host, you can set @option{clock}
3447to @code{rt} instead. To even prevent it from progressing during suspension,
3448you can set it to @code{vm}.
Jan Kiszka68752042009-09-15 13:36:04 +02003449
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003450Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3451specifically with Windows' ACPI HAL. This option will try to figure out how
3452many timer interrupts were not processed by the Windows guest and will
3453re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003454ETEXI
3455
3456DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003457 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003458 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003459 " instruction, enable aligning the host and virtual clocks\n" \
3460 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003461STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003462@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003463@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003464Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003465instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003466then the virtual cpu speed will be automatically adjusted to keep virtual
3467time within a few seconds of real time.
3468
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003469When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003470speed unless @option{sleep=on|off} is specified.
3471With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003472instantly whenever the virtual cpu goes to sleep mode and will not advance
3473if no timer is enabled. This behavior give deterministic execution times from
3474the guest point of view.
3475
blueswir15824d652009-03-28 06:44:27 +00003476Note that while this option can give deterministic behavior, it does not
3477provide cycle accurate emulation. Modern CPUs contain superscalar out of
3478order cores with complex cache hierarchies. The number of instructions
3479executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003480
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003481@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003482to synchronise the host clock and the virtual clock. The goal is to
3483have a guest running at the real frequency imposed by the shift option.
3484Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003485@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003486to inform about the delay.
3487Currently this option does not work when @option{shift} is @code{auto}.
3488Note: The sync algorithm will work for those shift values for which
3489the guest clock runs ahead of the host clock. Typically this happens
3490when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003491
3492When @option{rr} option is specified deterministic record/replay is enabled.
3493Replay log is written into @var{filename} file in record mode and
3494read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003495
3496Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3497at the start of execution recording. In replay mode this option is used
3498to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003499ETEXI
3500
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003501DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003502 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003503 " enable virtual hardware watchdog [default=none]\n",
3504 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003505STEXI
3506@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003507@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003508Create a virtual hardware watchdog device. Once enabled (by a guest
3509action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003510the guest or else the guest will be restarted. Choose a model for
3511which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003512
Xu Wangd7933ef2015-06-11 17:32:05 +02003513The @var{model} is the model of hardware watchdog to emulate. Use
3514@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003515watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003516
3517The following models may be available:
3518@table @option
3519@item ib700
3520iBASE 700 is a very simple ISA watchdog with a single timer.
3521@item i6300esb
3522Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3523dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003524@item diag288
3525A virtual watchdog for s390x backed by the diagnose 288 hypercall
3526(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003527@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003528ETEXI
3529
3530DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3531 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003532 " action when watchdog fires [default=reset]\n",
3533 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003534STEXI
3535@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003536@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003537
3538The @var{action} controls what QEMU will do when the watchdog timer
3539expires.
3540The default is
3541@code{reset} (forcefully reset the guest).
3542Other possible actions are:
3543@code{shutdown} (attempt to gracefully shutdown the guest),
3544@code{poweroff} (forcefully poweroff the guest),
3545@code{pause} (pause the guest),
3546@code{debug} (print a debug message and continue), or
3547@code{none} (do nothing).
3548
3549Note that the @code{shutdown} action requires that the guest responds
3550to ACPI signals, which it may not be able to do in the sort of
3551situations where the watchdog would have expired, and thus
3552@code{-watchdog-action shutdown} is not recommended for production use.
3553
3554Examples:
3555
3556@table @code
3557@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003558@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003559@end table
3560ETEXI
3561
blueswir15824d652009-03-28 06:44:27 +00003562DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003563 "-echr chr set terminal escape character instead of ctrl-a\n",
3564 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003565STEXI
3566
Kevin Wolf4e257e52009-10-09 10:58:36 +02003567@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003568@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003569Change the escape character used for switching to the monitor when using
3570monitor and serial sharing. The default is @code{0x01} when using the
3571@code{-nographic} option. @code{0x01} is equal to pressing
3572@code{Control-a}. You can select a different character from the ascii
3573control keys where 1 through 26 map to Control-a through Control-z. For
3574instance you could use the either of the following to change the escape
3575character to Control-t.
3576@table @code
3577@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003578@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003579@end table
3580ETEXI
3581
3582DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3583 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003584 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003585STEXI
3586@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003587@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003588Set virtio console.
Amit Shah98b19252010-01-20 00:36:52 +05303589
3590This option is maintained for backward compatibility.
3591
3592Please use @code{-device virtconsole} for the new way of invocation.
blueswir15824d652009-03-28 06:44:27 +00003593ETEXI
3594
3595DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003596 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003597STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003598@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003599@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003600Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003601ETEXI
3602
3603DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003604 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003605STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003606@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003607@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003608Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003609ETEXI
3610
3611DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003612 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3613 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3614 "-incoming unix:socketpath\n" \
3615 " prepare for incoming migration, listen on\n" \
3616 " specified protocol and socket address\n" \
3617 "-incoming fd:fd\n" \
3618 "-incoming exec:cmdline\n" \
3619 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003620 " or from given external command\n" \
3621 "-incoming defer\n" \
3622 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003623 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003624STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003625@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003626@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003627@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003628Prepare for incoming migration, listen on a given tcp port.
3629
3630@item -incoming unix:@var{socketpath}
3631Prepare for incoming migration, listen on a given unix socket.
3632
3633@item -incoming fd:@var{fd}
3634Accept incoming migration from a given filedescriptor.
3635
3636@item -incoming exec:@var{cmdline}
3637Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003638
3639@item -incoming defer
3640Wait for the URI to be specified via migrate_incoming. The monitor can
3641be used to change settings (such as migration parameters) prior to issuing
3642the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003643ETEXI
3644
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303645DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3646 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3647STEXI
3648@item -only-migratable
3649@findex -only-migratable
3650Only allow migratable devices. Devices will not be allowed to enter an
3651unmigratable state.
3652ETEXI
3653
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003654DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003655 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003656STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003657@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003658@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003659Don't create default devices. Normally, QEMU sets the default devices like serial
3660port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3661CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3662default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003663ETEXI
3664
blueswir15824d652009-03-28 06:44:27 +00003665#ifndef _WIN32
3666DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003667 "-chroot dir chroot to dir just before starting the VM\n",
3668 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003669#endif
3670STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003671@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003672@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003673Immediately before starting guest execution, chroot to the specified
3674directory. Especially useful in combination with -runas.
3675ETEXI
3676
3677#ifndef _WIN32
3678DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Blue Swirlad960902010-03-29 19:23:52 +00003679 "-runas user change to user id user just before starting the VM\n",
3680 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003681#endif
3682STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003683@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003684@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003685Immediately before starting guest execution, drop root privileges, switching
3686to the specified user.
3687ETEXI
3688
blueswir15824d652009-03-28 06:44:27 +00003689DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3690 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003691 " set OpenBIOS nvram variables\n",
3692 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003693STEXI
3694@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003695@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003696Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3697ETEXI
blueswir15824d652009-03-28 06:44:27 +00003698DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003699 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003700 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3701 QEMU_ARCH_MIPS)
Stefan Weil95d5f082010-01-20 22:25:27 +01003702STEXI
3703@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003704@findex -semihosting
Leon Alrae3b3c1692015-06-19 11:08:43 +01003705Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003706ETEXI
3707DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003708 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3709 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003710QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3711QEMU_ARCH_MIPS)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003712STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003713@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003714@findex -semihosting-config
Leon Alrae3b3c1692015-06-19 11:08:43 +01003715Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003716@table @option
3717@item target=@code{native|gdb|auto}
3718Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3719or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3720during debug sessions and @code{native} otherwise.
3721@item arg=@var{str1},arg=@var{str2},...
3722Allows the user to pass input arguments, and can be used multiple times to build
3723up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3724command line is still supported for backward compatibility. If both the
3725@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3726specified, the former is passed to semihosting as it always takes precedence.
3727@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003728ETEXI
blueswir15824d652009-03-28 06:44:27 +00003729DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003730 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003731STEXI
3732@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003733@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003734Old param mode (ARM only).
3735ETEXI
3736
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003737DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
3738 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
3739 QEMU_ARCH_ALL)
3740STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01003741@item -sandbox @var{arg}
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003742@findex -sandbox
3743Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3744disable it. The default is 'off'.
3745ETEXI
3746
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003747DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003748 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003749STEXI
3750@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003751@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003752Read device configuration from @var{file}. This approach is useful when you want to spawn
3753QEMU process with many command line options but you don't want to exceed the command line
3754character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003755ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003756DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3757 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003758 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003759STEXI
3760@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003761@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003762Write device configuration to @var{file}. The @var{file} can be either filename to save
3763command line and device configuration into file or dash @code{-}) character to print the
3764output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003765ETEXI
Anthony Liguori292444c2010-01-21 10:57:58 -06003766DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3767 "-nodefconfig\n"
Blue Swirlad960902010-03-29 19:23:52 +00003768 " do not load default config files at startup\n",
3769 QEMU_ARCH_ALL)
Anthony Liguori292444c2010-01-21 10:57:58 -06003770STEXI
3771@item -nodefconfig
Stefan Weil6616b2a2010-02-05 23:52:05 +01003772@findex -nodefconfig
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003773Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3774The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3775ETEXI
3776DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3777 "-no-user-config\n"
3778 " do not load user-provided config files at startup\n",
3779 QEMU_ARCH_ALL)
3780STEXI
3781@item -no-user-config
3782@findex -no-user-config
3783The @code{-no-user-config} option makes QEMU not load any of the user-provided
3784config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
3785files from @var{datadir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003786ETEXI
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003787DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03003788 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
Lluís23d15e82011-08-31 20:31:31 +02003789 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003790 QEMU_ARCH_ALL)
3791STEXI
Lluís23d15e82011-08-31 20:31:31 +02003792HXCOMM This line is not accurate, as some sub-options are backend-specific but
3793HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03003794@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003795@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03003796@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003797ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003798
Markus Armbruster31e70d62013-02-13 19:49:37 +01003799HXCOMM Internal use
3800DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3801DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003802
Paul Moore0f669982012-08-03 14:39:21 -04003803#ifdef __linux__
3804DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3805 "-enable-fips enable FIPS 140-2 compliance\n",
3806 QEMU_ARCH_ALL)
3807#endif
3808STEXI
3809@item -enable-fips
3810@findex -enable-fips
3811Enable FIPS 140-2 compliance mode.
3812ETEXI
3813
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003814HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003815DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003816
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003817HXCOMM Deprecated by kvm-pit driver properties
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003818DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003819 "", QEMU_ARCH_I386)
3820
Jan Kiszka4086bde2012-10-05 14:51:41 -03003821HXCOMM Deprecated (ignored)
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003822DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
Jan Kiszka4086bde2012-10-05 14:51:41 -03003823
Jan Kiszkae43d5942012-10-05 14:51:40 -03003824HXCOMM Deprecated by -machine kernel_irqchip=on|off property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003825DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
Jan Kiszkae43d5942012-10-05 14:51:40 -03003826
Jan Kiszka88eed342012-10-05 14:51:44 -03003827HXCOMM Deprecated (ignored)
3828DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
3829
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003830DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3831 "-msg timestamp[=on|off]\n"
3832 " change the format of messages\n"
3833 " on|off controls leading timestamps (default:on)\n",
3834 QEMU_ARCH_ALL)
3835STEXI
3836@item -msg timestamp[=on|off]
3837@findex -msg
3838prepend a timestamp to each log message.(default:on)
3839ETEXI
3840
Amit Shahabfd9ce2014-06-20 18:56:08 +05303841DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3842 "-dump-vmstate <file>\n"
3843 " Output vmstate information in JSON format to file.\n"
3844 " Use the scripts/vmstate-static-checker.py file to\n"
3845 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02003846 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05303847 QEMU_ARCH_ALL)
3848STEXI
3849@item -dump-vmstate @var{file}
3850@findex -dump-vmstate
3851Dump json-encoded vmstate information for current machine type to file
3852in @var{file}
3853ETEXI
3854
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003855STEXI
3856@end table
3857ETEXI
3858DEFHEADING()
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003859DEFHEADING(Generic object creation)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01003860STEXI
3861@table @option
3862ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01003863
3864DEF("object", HAS_ARG, QEMU_OPTION_object,
3865 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3866 " create a new object of type TYPENAME setting properties\n"
3867 " in the order they are specified. Note that the 'id'\n"
3868 " property must be set. These objects are placed in the\n"
3869 " '/objects' path.\n",
3870 QEMU_ARCH_ALL)
3871STEXI
3872@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3873@findex -object
3874Create a new object of type @var{typename} setting properties
3875in the order they are specified. Note that the 'id'
3876property must be set. These objects are placed in the
3877'/objects' path.
3878
3879@table @option
3880
3881@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off}
3882
3883Creates a memory file backend object, which can be used to back
3884the guest RAM with huge pages. The @option{id} parameter is a
3885unique ID that will be used to reference this memory region
3886when configuring the @option{-numa} argument. The @option{size}
3887option provides the size of the memory region, and accepts
3888common suffixes, eg @option{500M}. The @option{mem-path} provides
3889the path to either a shared memory or huge page filesystem mount.
3890The @option{share} boolean option determines whether the memory
3891region is marked as private to QEMU, or shared. The latter allows
3892a co-operating external process to access the QEMU memory region.
3893
3894@item -object rng-random,id=@var{id},filename=@var{/dev/random}
3895
3896Creates a random number generator backend which obtains entropy from
3897a device on the host. The @option{id} parameter is a unique ID that
3898will be used to reference this entropy backend from the @option{virtio-rng}
3899device. The @option{filename} parameter specifies which file to obtain
3900entropy from and if omitted defaults to @option{/dev/random}.
3901
3902@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
3903
3904Creates a random number generator backend which obtains entropy from
3905an external daemon running on the host. The @option{id} parameter is
3906a unique ID that will be used to reference this entropy backend from
3907the @option{virtio-rng} device. The @option{chardev} parameter is
3908the unique ID of a character device backend that provides the connection
3909to the RNG daemon.
3910
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00003911@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
3912
3913Creates a TLS anonymous credentials object, which can be used to provide
3914TLS support on network backends. The @option{id} parameter is a unique
3915ID which network backends will use to access the credentials. The
3916@option{endpoint} is either @option{server} or @option{client} depending
3917on whether the QEMU network backend that uses the credentials will be
3918acting as a client or as a server. If @option{verify-peer} is enabled
3919(the default) then once the handshake is completed, the peer credentials
3920will be verified, though this is a no-op for anonymous credentials.
3921
3922The @var{dir} parameter tells QEMU where to find the credential
3923files. For server endpoints, this directory may contain a file
3924@var{dh-params.pem} providing diffie-hellman parameters to use
3925for the TLS server. If the file is missing, QEMU will generate
3926a set of DH parameters at startup. This is a computationally
3927expensive operation that consumes random pool entropy, so it is
3928recommended that a persistent set of parameters be generated
3929upfront and saved.
3930
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01003931@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 +00003932
3933Creates a TLS anonymous credentials object, which can be used to provide
3934TLS support on network backends. The @option{id} parameter is a unique
3935ID which network backends will use to access the credentials. The
3936@option{endpoint} is either @option{server} or @option{client} depending
3937on whether the QEMU network backend that uses the credentials will be
3938acting as a client or as a server. If @option{verify-peer} is enabled
3939(the default) then once the handshake is completed, the peer credentials
3940will be verified. With x509 certificates, this implies that the clients
3941must be provided with valid client certificates too.
3942
3943The @var{dir} parameter tells QEMU where to find the credential
3944files. For server endpoints, this directory may contain a file
3945@var{dh-params.pem} providing diffie-hellman parameters to use
3946for the TLS server. If the file is missing, QEMU will generate
3947a set of DH parameters at startup. This is a computationally
3948expensive operation that consumes random pool entropy, so it is
3949recommended that a persistent set of parameters be generated
3950upfront and saved.
3951
3952For x509 certificate credentials the directory will contain further files
3953providing the x509 certificates. The certificates must be stored
3954in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
3955@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
3956@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
3957
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01003958For the @var{server-key.pem} and @var{client-key.pem} files which
3959contain sensitive private keys, it is possible to use an encrypted
3960version by providing the @var{passwordid} parameter. This provides
3961the ID of a previously created @code{secret} object containing the
3962password for decryption.
3963
zhanghailiang338d3f42016-03-01 13:37:02 +08003964@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 +08003965
3966Interval @var{t} can't be 0, this filter batches the packet delivery: all
3967packets arriving in a given interval on netdev @var{netdevid} are delayed
3968until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08003969@option{status} is optional that indicate whether the netfilter is
3970on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08003971
3972queue @var{all|rx|tx} is an option that can be applied to any netfilter.
3973
3974@option{all}: the filter is attached both to the receive and the transmit
3975 queue of the netdev (default).
3976
3977@option{rx}: the filter is attached to the receive queue of the netdev,
3978 where it will receive packets sent to the netdev.
3979
3980@option{tx}: the filter is attached to the transmit queue of the netdev,
3981 where it will receive packets sent by the netdev.
3982
Zhang Chenf6d3afb2016-03-15 15:41:33 +08003983@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
3984
3985filter-mirror on netdev @var{netdevid},mirror net packet to chardev
3986@var{chardevid}
3987
Zhang Chend46f75b2016-03-17 16:16:26 +08003988@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},
3989outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
3990
3991filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
3992@var{chardevid},and redirect indev's packet to filter.
3993Create a filter-redirector we need to differ outdev id from indev id, id can not
3994be the same. we can just use indev or outdev, but at least one of indev or outdev
3995need to be specified.
3996
Zhang Chene6eee8a2016-09-27 10:22:32 +08003997@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},rewriter-mode=@var{mode}[,queue=@var{all|rx|tx}]
3998
3999Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4000secondary from primary to keep secondary tcp connection,and rewrite
4001tcp packet to primary from secondary make tcp packet can be handled by
4002client.
4003
4004usage:
4005colo secondary:
4006-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4007-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4008-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4009
Changlong Xiec551cd52016-10-11 13:28:32 +08004010@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004011
4012Dump the network traffic on netdev @var{dev} to the file specified by
4013@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4014The file format is libpcap, so it can be analyzed with tools such as tcpdump
4015or Wireshark.
4016
Zhang Chen7dce4e62016-09-27 10:22:26 +08004017@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},
4018outdev=@var{chardevid}
4019
4020Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4021secondary packet. If the packets are same, we will output primary
4022packet to outdev@var{chardevid}, else we will notify colo-frame
4023do checkpoint and send primary packet to outdev@var{chardevid}.
4024
4025we must use it with the help of filter-mirror and filter-redirector.
4026
4027@example
4028
4029primary:
4030-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4031-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4032-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4033-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4034-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4035-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4036-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4037-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4038-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4039-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4040-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4041-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4042
4043secondary:
4044-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4045-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4046-chardev socket,id=red0,host=3.3.3.3,port=9003
4047-chardev socket,id=red1,host=3.3.3.3,port=9004
4048-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4049-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4050
4051@end example
4052
4053If you want to know the detail of above command line, you can read
4054the colo-compare git log.
4055
Gonglei1653a5f2016-10-28 16:33:23 +08004056@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4057
4058Creates a cryptodev backend which executes crypto opreation from
4059the QEMU cipher APIS. The @var{id} parameter is
4060a unique ID that will be used to reference this cryptodev backend from
4061the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4062which specify the queue number of cryptodev backend, the default of
4063@var{queues} is 1.
4064
4065@example
4066
4067 # qemu-system-x86_64 \
4068 [...] \
4069 -object cryptodev-backend-builtin,id=cryptodev0 \
4070 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4071 [...]
4072@end example
4073
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004074@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4075@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4076
4077Defines a secret to store a password, encryption key, or some other sensitive
4078data. The sensitive data can either be passed directly via the @var{data}
4079parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4080parameter is insecure unless the sensitive data is encrypted.
4081
4082The sensitive data can be provided in raw format (the default), or base64.
4083When encoded as JSON, the raw format only supports valid UTF-8 characters,
4084so base64 is recommended for sending binary data. QEMU will convert from
4085which ever format is provided to the format it needs internally. eg, an
4086RBD password can be provided in raw format, even though it will be base64
4087encoded when passed onto the RBD sever.
4088
4089For added protection, it is possible to encrypt the data associated with
4090a secret using the AES-256-CBC cipher. Use of encryption is indicated
4091by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4092parameter provides the ID of a previously defined secret that contains
4093the AES-256 decryption key. This key should be 32-bytes long and be
4094base64 encoded. The @var{iv} parameter provides the random initialization
4095vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004096base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004097
4098The simplest (insecure) usage is to provide the secret inline
4099
4100@example
4101
4102 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4103
4104@end example
4105
4106The simplest secure usage is to provide the secret via a file
4107
4108 # echo -n "letmein" > mypasswd.txt
4109 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4110
4111For greater security, AES-256-CBC should be used. To illustrate usage,
4112consider the openssl command line tool which can encrypt the data. Note
4113that when encrypting, the plaintext must be padded to the cipher block
4114size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4115
4116First a master key needs to be created in base64 encoding:
4117
4118@example
4119 # openssl rand -base64 32 > key.b64
4120 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4121@end example
4122
4123Each secret to be encrypted needs to have a random initialization vector
4124generated. These do not need to be kept secret
4125
4126@example
4127 # openssl rand -base64 16 > iv.b64
4128 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4129@end example
4130
4131The secret to be defined can now be encrypted, in this case we're
4132telling openssl to base64 encode the result, but it could be left
4133as raw bytes if desired.
4134
4135@example
4136 # SECRET=$(echo -n "letmein" |
4137 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4138@end example
4139
4140When launching QEMU, create a master secret pointing to @code{key.b64}
4141and specify that to be used to decrypt the user password. Pass the
4142contents of @code{iv.b64} to the second secret
4143
4144@example
4145 # $QEMU \
4146 -object secret,id=secmaster0,format=base64,file=key.b64 \
4147 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4148 data=$SECRET,iv=$(<iv.b64)
4149@end example
4150
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004151@end table
4152
4153ETEXI
4154
4155
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004156HXCOMM This is the last statement. Insert new options before this line!
4157STEXI
4158@end table
4159ETEXI