blob: 10b95688150bf4b3ab95a67a164a11f0021f17fb [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
9DEFHEADING(Standard options:)
10STEXI
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"
Jan Kiszka39d69602012-01-25 18:14:15 +010035 " kernel_irqchip=on|off controls accelerated irqchip support\n"
Don Slutzd1048be2014-11-21 11:18:52 -050036 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
Jason Baronddb97f12012-08-02 15:44:16 -040037 " kvm_shadow_mem=size of KVM shadow MMU\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"
40 " iommu=on|off controls emulated Intel IOMMU (VT-d) support (default=off)\n",
Jan Kiszka80f52a62011-07-23 12:39:46 +020041 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000042STEXI
Jan Kiszka80f52a62011-07-23 12:39:46 +020043@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
44@findex -machine
Peter Maydell585f6032012-10-04 16:22:01 +010045Select the emulated machine by @var{name}. Use @code{-machine help} to list
Jan Kiszka80f52a62011-07-23 12:39:46 +020046available machines. Supported machine properties are:
47@table @option
48@item accel=@var{accels1}[:@var{accels2}[:...]]
49This is used to enable an accelerator. Depending on the target architecture,
50kvm, xen, or tcg can be available. By default, tcg is used. If there is more
51than one accelerator specified, the next one is used if the previous one fails
52to initialize.
Jan Kiszka6a48ffa2011-10-15 13:43:48 +020053@item kernel_irqchip=on|off
54Enables in-kernel irqchip support for the chosen accelerator when available.
Don Slutzd1048be2014-11-21 11:18:52 -050055@item vmport=on|off|auto
56Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
57value based on accel. For accel=xen the default is off otherwise the default
58is on.
Jan Kiszka39d69602012-01-25 18:14:15 +010059@item kvm_shadow_mem=size
60Defines the size of the KVM shadow MMU.
Jason Baronddb97f12012-08-02 15:44:16 -040061@item dump-guest-core=on|off
62Include guest memory in a core dump. The default is on.
Luiz Capitulino8490fc72012-09-05 16:50:16 -030063@item mem-merge=on|off
64Enables or disables memory merge support. This feature, when supported by
65the host, de-duplicates identical memory pages among VMs instances
66(enabled by default).
Le Tana52a7fd2014-08-16 13:55:40 +080067@item iommu=on|off
68Enables or disables emulated Intel IOMMU (VT-d) support. The default is off.
Jan Kiszka80f52a62011-07-23 12:39:46 +020069@end table
blueswir15824d652009-03-28 06:44:27 +000070ETEXI
71
Jan Kiszka80f52a62011-07-23 12:39:46 +020072HXCOMM Deprecated by -machine
73DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
74
blueswir15824d652009-03-28 06:44:27 +000075DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
Peter Maydell585f6032012-10-04 16:22:01 +010076 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000077STEXI
78@item -cpu @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +010079@findex -cpu
Peter Maydell585f6032012-10-04 16:22:01 +010080Select CPU model (@code{-cpu help} for list and additional feature selection)
blueswir15824d652009-03-28 06:44:27 +000081ETEXI
82
83DEF("smp", HAS_ARG, QEMU_OPTION_smp,
Michael Tokarev12b7f572013-06-24 15:06:52 +040084 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
Jes Sorensen6be68d72009-07-23 17:03:42 +020085 " set the number of CPUs to 'n' [default=1]\n"
86 " maxcpus= maximum number of total cpus, including\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -070087 " offline CPUs for hotplug, etc\n"
Andre Przywara58a04db2009-08-28 10:49:57 +020088 " cores= number of CPU cores on one socket\n"
89 " threads= number of threads on one CPU core\n"
Blue Swirlad960902010-03-29 19:23:52 +000090 " sockets= number of discrete sockets in the system\n",
91 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +000092STEXI
Michael Tokarev12b7f572013-06-24 15:06:52 +040093@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
Stefan Weil6616b2a2010-02-05 23:52:05 +010094@findex -smp
blueswir15824d652009-03-28 06:44:27 +000095Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
96CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
97to 4.
Andre Przywara58a04db2009-08-28 10:49:57 +020098For the PC target, the number of @var{cores} per socket, the number
99of @var{threads} per cores and the total number of @var{sockets} can be
100specified. Missing values will be computed. If any on the three values is
101given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
102specifies the maximum number of hotpluggable CPUs.
blueswir15824d652009-03-28 06:44:27 +0000103ETEXI
104
aliguori268a3622009-04-21 22:30:27 +0000105DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Paolo Bonzini7febe362014-05-14 17:43:17 +0800106 "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
107 "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
aliguori268a3622009-04-21 22:30:27 +0000108STEXI
Luiz Capitulino4932b892014-05-14 17:43:10 +0800109@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
Paolo Bonzini7febe362014-05-14 17:43:17 +0800110@item -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100111@findex -numa
Paolo Bonzini7febe362014-05-14 17:43:17 +0800112Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
Luiz Capitulino4932b892014-05-14 17:43:10 +0800113and @samp{cpus} are omitted, resources are split equally. Also, note
114that the -@option{numa} option doesn't allocate any of the specified
115resources. That is, it just assigns existing resources to NUMA nodes. This
116means that one still has to use the @option{-m}, @option{-smp} options
Paolo Bonzini7febe362014-05-14 17:43:17 +0800117to allocate RAM and VCPUs respectively, and possibly @option{-object}
118to specify the memory backend for the @samp{memdev} suboption.
119
120@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one
121node uses @samp{memdev}, all of them have to use it.
aliguori268a3622009-04-21 22:30:27 +0000122ETEXI
123
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100124DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
125 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
126 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
127STEXI
128@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
129@findex -add-fd
130
131Add a file descriptor to an fd set. Valid options are:
132
133@table @option
134@item fd=@var{fd}
135This option defines the file descriptor of which a duplicate is added to fd set.
136The file descriptor cannot be stdin, stdout, or stderr.
137@item set=@var{set}
138This option defines the ID of the fd set to add the file descriptor to.
139@item opaque=@var{opaque}
140This option defines a free-form string that can be used to describe @var{fd}.
141@end table
142
143You can open an image using pre-opened file descriptors from an fd set:
144@example
145qemu-system-i386
146-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
147-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
148-drive file=/dev/fdset/2,index=0,media=disk
149@end example
150ETEXI
151
152DEF("set", HAS_ARG, QEMU_OPTION_set,
153 "-set group.id.arg=value\n"
154 " set <arg> parameter for item <id> of type <group>\n"
155 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
156STEXI
157@item -set @var{group}.@var{id}.@var{arg}=@var{value}
158@findex -set
159Set parameter @var{arg} for item @var{id} of type @var{group}\n"
160ETEXI
161
162DEF("global", HAS_ARG, QEMU_OPTION_global,
163 "-global driver.prop=value\n"
164 " set a global default for a driver property\n",
165 QEMU_ARCH_ALL)
166STEXI
167@item -global @var{driver}.@var{prop}=@var{value}
168@findex -global
169Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
170
171@example
172qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
173@end example
174
175In particular, you can use this to set driver properties for devices which are
176created automatically by the machine model. To create a device which is not
177created automatically and set properties on it, use -@option{device}.
178ETEXI
179
180DEF("boot", HAS_ARG, QEMU_OPTION_boot,
181 "-boot [order=drives][,once=drives][,menu=on|off]\n"
Amos Kongc8a6ae82013-03-19 14:23:27 +0800182 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100183 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
184 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
185 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
186 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
187 QEMU_ARCH_ALL)
188STEXI
Amos Kongc8a6ae82013-03-19 14:23:27 +0800189@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 +0100190@findex -boot
191Specify boot order @var{drives} as a string of drive letters. Valid
192drive letters depend on the target achitecture. The x86 PC uses: a, b
193(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
194from network adapter 1-4), hard disk boot is the default. To apply a
195particular boot order only on the first startup, specify it via
196@option{once}.
197
198Interactive boot menus/prompts can be enabled via @option{menu=on} as far
199as firmware/BIOS supports them. The default is non-interactive boot.
200
201A splash picture could be passed to bios, enabling user to show it as logo,
202when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
203supports them. Currently Seabios for X86 system support it.
204limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
205format(true color). The resolution should be supported by the SVGA mode, so
206the recommended is 320x240, 640x480, 800x640.
207
208A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
209when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
210reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
211system support it.
212
Amos Kongc8a6ae82013-03-19 14:23:27 +0800213Do strict boot via @option{strict=on} as far as firmware/BIOS
214supports it. This only effects when boot priority is changed by
215bootindex options. The default is non-strict boot.
216
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100217@example
218# try to boot from network first, then from hard disk
219qemu-system-i386 -boot order=nc
220# boot from CD-ROM first, switch back to default order after reboot
221qemu-system-i386 -boot once=d
222# boot with a splash picture for 5 seconds.
223qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
224@end example
225
226Note: The legacy format '-boot @var{drives}' is still supported but its
227use is discouraged as it may be removed from future versions.
228ETEXI
229
230DEF("m", HAS_ARG, QEMU_OPTION_m,
Igor Mammedovc270fb92014-06-02 15:25:02 +0200231 "-m[emory] [size=]megs[,slots=n,maxmem=size]\n"
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100232 " configure guest RAM\n"
233 " size: initial amount of guest memory (default: "
Igor Mammedovc270fb92014-06-02 15:25:02 +0200234 stringify(DEFAULT_RAM_SIZE) "MiB)\n"
235 " slots: number of hotplug slots (default: none)\n"
Matthew Rosatob6fe0122014-08-28 11:25:33 -0400236 " maxmem: maximum amount of guest memory (default: none)\n"
237 "NOTE: Some architectures might enforce a specific granularity\n",
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100238 QEMU_ARCH_ALL)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100239STEXI
Igor Mammedov6e1d3c12013-11-27 01:27:35 +0100240@item -m [size=]@var{megs}
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100241@findex -m
242Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
243a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
Igor Mammedovc270fb92014-06-02 15:25:02 +0200244gigabytes respectively. Optional pair @var{slots}, @var{maxmem} could be used
245to set amount of hotluggable memory slots and possible maximum amount of memory.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100246ETEXI
247
248DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
249 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
250STEXI
251@item -mem-path @var{path}
252@findex -mem-path
253Allocate guest RAM from a temporarily created file in @var{path}.
254ETEXI
255
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100256DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
257 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
258 QEMU_ARCH_ALL)
259STEXI
260@item -mem-prealloc
261@findex -mem-prealloc
262Preallocate memory when using -mem-path.
263ETEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100264
265DEF("k", HAS_ARG, QEMU_OPTION_k,
266 "-k language use keyboard layout (for example 'fr' for French)\n",
267 QEMU_ARCH_ALL)
268STEXI
269@item -k @var{language}
270@findex -k
271Use keyboard layout @var{language} (for example @code{fr} for
272French). This option is only needed where it is not easy to get raw PC
273keycodes (e.g. on Macs, with some X11 servers or with a VNC
274display). You don't normally need to use it on PC/Linux or PC/Windows
275hosts.
276
277The available layouts are:
278@example
279ar de-ch es fo fr-ca hu ja mk no pt-br sv
280da en-gb et fr fr-ch is lt nl pl ru th
281de en-us fi fr-be hr it lv nl-be pt sl tr
282@end example
283
284The default is @code{en-us}.
285ETEXI
286
287
288DEF("audio-help", 0, QEMU_OPTION_audio_help,
289 "-audio-help print list of audio drivers and their options\n",
290 QEMU_ARCH_ALL)
291STEXI
292@item -audio-help
293@findex -audio-help
294Will show the audio subsystem help: list of drivers, tunable
295parameters.
296ETEXI
297
298DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
299 "-soundhw c1,... enable audio support\n"
300 " and only specified sound cards (comma separated list)\n"
301 " use '-soundhw help' to get the list of supported cards\n"
302 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
303STEXI
304@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
305@findex -soundhw
306Enable audio and selected sound hardware. Use 'help' to print all
307available sound hardware.
308
309@example
310qemu-system-i386 -soundhw sb16,adlib disk.img
311qemu-system-i386 -soundhw es1370 disk.img
312qemu-system-i386 -soundhw ac97 disk.img
313qemu-system-i386 -soundhw hda disk.img
314qemu-system-i386 -soundhw all disk.img
315qemu-system-i386 -soundhw help
316@end example
317
318Note that Linux's i810_audio OSS kernel (for AC97) module might
319require manually specifying clocking.
320
321@example
322modprobe i810_audio clocking=48000
323@end example
324ETEXI
325
326DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
327 "-balloon none disable balloon device\n"
328 "-balloon virtio[,addr=str]\n"
329 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
330STEXI
331@item -balloon none
332@findex -balloon
333Disable balloon device.
334@item -balloon virtio[,addr=@var{addr}]
335Enable virtio balloon device (default), optionally with PCI address
336@var{addr}.
337ETEXI
338
339DEF("device", HAS_ARG, QEMU_OPTION_device,
340 "-device driver[,prop[=value][,...]]\n"
341 " add device (based on driver)\n"
342 " prop=value,... sets driver properties\n"
343 " use '-device help' to print all possible drivers\n"
344 " use '-device driver,help' to print all possible properties\n",
345 QEMU_ARCH_ALL)
346STEXI
347@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
348@findex -device
349Add device @var{driver}. @var{prop}=@var{value} sets driver
350properties. Valid properties depend on the driver. To get help on
351possible drivers and properties, use @code{-device help} and
352@code{-device @var{driver},help}.
353ETEXI
354
355DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000356 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100357 " set the name of the guest\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000358 " string1 sets the window title and string2 the process name (on Linux)\n"
359 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
360 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100361 QEMU_ARCH_ALL)
362STEXI
363@item -name @var{name}
364@findex -name
365Sets the @var{name} of the guest.
366This name will be displayed in the SDL window caption.
367The @var{name} will also be used for the VNC server.
368Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000369Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100370ETEXI
371
372DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
373 "-uuid %08x-%04x-%04x-%04x-%012x\n"
374 " specify machine UUID\n", QEMU_ARCH_ALL)
375STEXI
376@item -uuid @var{uuid}
377@findex -uuid
378Set system UUID.
379ETEXI
380
381STEXI
382@end table
383ETEXI
384DEFHEADING()
385
386DEFHEADING(Block device options:)
387STEXI
388@table @option
389ETEXI
390
blueswir15824d652009-03-28 06:44:27 +0000391DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000392 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
393DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000394STEXI
395@item -fda @var{file}
396@item -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100397@findex -fda
398@findex -fdb
blueswir15824d652009-03-28 06:44:27 +0000399Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
400use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
401ETEXI
402
403DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000404 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
405DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000406DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000407 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
408DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000409STEXI
410@item -hda @var{file}
411@item -hdb @var{file}
412@item -hdc @var{file}
413@item -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100414@findex -hda
415@findex -hdb
416@findex -hdc
417@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000418Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
419ETEXI
420
421DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000422 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
423 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000424STEXI
425@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100426@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000427Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
428@option{-cdrom} at the same time). You can use the host CD-ROM by
429using @file{/dev/cdrom} as filename (@pxref{host_drives}).
430ETEXI
431
432DEF("drive", HAS_ARG, QEMU_OPTION_drive,
433 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
434 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100435 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +0200436 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
437 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000438 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +0200439 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +0200440 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
441 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
442 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
443 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +0200444 " [[,iops_size=is]]\n"
Blue Swirlad960902010-03-29 19:23:52 +0000445 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000446STEXI
447@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +0100448@findex -drive
blueswir15824d652009-03-28 06:44:27 +0000449
450Define a new drive. Valid options are:
451
Kevin Wolfb3f046c2009-10-09 10:58:35 +0200452@table @option
blueswir15824d652009-03-28 06:44:27 +0000453@item file=@var{file}
454This option defines which disk image (@pxref{disk_images}) to use with
455this drive. If the filename contains comma, you must double it
456(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +1100457
458Special files such as iSCSI devices can be specified using protocol
459specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +0000460@item if=@var{interface}
461This option defines on which type on interface the drive is connected.
462Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
463@item bus=@var{bus},unit=@var{unit}
464These options define where is connected the drive by defining the bus number and
465the unit id.
466@item index=@var{index}
467This option defines where is connected the drive by using an index in the list
468of available connectors of a given interface type.
469@item media=@var{media}
470This option defines the type of the media: disk or cdrom.
471@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
472These options have the same definition as they have in @option{-hdachs}.
473@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +0400474@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
475(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +0000476@item cache=@var{cache}
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100477@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 +0200478@item aio=@var{aio}
479@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 +0100480@item discard=@var{discard}
481@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 +0000482@item format=@var{format}
483Specify which disk @var{format} will be used rather than detecting
484the format. Can be used to specifiy format=raw to avoid interpreting
485an untrusted format header.
486@item serial=@var{serial}
487This option specifies the serial number to assign to the device.
Markus Armbrusterc2cc47a2009-06-18 15:14:10 +0200488@item addr=@var{addr}
489Specify the controller's PCI address (if=virtio only).
Luiz Capitulinoae73e592011-07-12 17:35:08 -0300490@item werror=@var{action},rerror=@var{action}
491Specify which @var{action} to take on write and read errors. Valid actions are:
492"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
493"report" (report the error to the guest), "enospc" (pause QEMU only if the
494host disk is full; report the error to the guest otherwise).
495The default setting is @option{werror=enospc} and @option{rerror=report}.
496@item readonly
497Open drive @option{file} as read-only. Guest write attempts will fail.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000498@item copy-on-read=@var{copy-on-read}
499@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
500file sectors into the image file.
Peter Lieven465bee12014-05-18 00:58:19 +0200501@item detect-zeroes=@var{detect-zeroes}
502@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
503conversion of plain zero writes by the OS to driver specific optimized
504zero write commands. You may even choose "unmap" if @var{discard} is set
505to "unmap" to allow a zero write to be converted to an UNMAP operation.
blueswir15824d652009-03-28 06:44:27 +0000506@end table
507
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100508By default, the @option{cache=writeback} mode is used. It will report data
509writes as completed as soon as the data is present in the host page cache.
510This is safe as long as your guest OS makes sure to correctly flush disk caches
511where needed. If your guest OS does not handle volatile disk write caches
512correctly and your host crashes or loses power, then the guest may experience
513data corruption.
blueswir15824d652009-03-28 06:44:27 +0000514
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100515For such guests, you should consider using @option{cache=writethrough}. This
516means that the host page cache will be used to read and write data, but write
517notification will be sent to the guest only after QEMU has made sure to flush
518each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +0000519
Aurelien Jarnoc304d312009-05-03 23:29:14 +0200520The host page cache can be avoided entirely with @option{cache=none}. This will
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100521attempt to do disk IO directly to the guest's memory. QEMU may still perform
522an internal copy of the data. Note that this is considered a writeback mode and
523the guest OS must handle the disk write cache correctly in order to avoid data
524corruption on host crashes.
blueswir15824d652009-03-28 06:44:27 +0000525
Stefan Hajnoczi92196b22011-08-04 12:26:52 +0100526The host page cache can be avoided while only sending write notifications to
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100527the guest when the data has been flushed to the disk using
528@option{cache=directsync}.
blueswir15824d652009-03-28 06:44:27 +0000529
Alexander Graf016f5cf2010-05-26 17:51:49 +0200530In case you don't care about data integrity over host failures, use
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100531@option{cache=unsafe}. This option tells QEMU that it never needs to write any
532data to the disk but can instead keep things in cache. If anything goes wrong,
Stefan Weile7d81002011-12-10 00:19:46 +0100533like your host losing power, the disk storage getting disconnected accidentally,
Kevin Wolfa13e5e02012-11-21 12:26:56 +0100534etc. your image will most probably be rendered unusable. When using
Alexander Grafc3177282010-05-26 21:04:32 +0200535the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +0200536
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +0000537Copy-on-read avoids accessing the same backing file sectors repeatedly and is
538useful when the backing file is over a slow network. By default copy-on-read
539is off.
540
blueswir15824d652009-03-28 06:44:27 +0000541Instead of @option{-cdrom} you can use:
542@example
Stefan Weil3804da92012-05-11 22:21:50 +0200543qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000544@end example
545
546Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
547use:
548@example
Stefan Weil3804da92012-05-11 22:21:50 +0200549qemu-system-i386 -drive file=file,index=0,media=disk
550qemu-system-i386 -drive file=file,index=1,media=disk
551qemu-system-i386 -drive file=file,index=2,media=disk
552qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +0000553@end example
554
Corey Bryant587ed6b2012-10-18 15:19:34 -0400555You can open an image using pre-opened file descriptors from an fd set:
556@example
557qemu-system-i386
558-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
559-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
560-drive file=/dev/fdset/2,index=0,media=disk
561@end example
562
blueswir15824d652009-03-28 06:44:27 +0000563You can connect a CDROM to the slave of ide0:
564@example
Stefan Weil3804da92012-05-11 22:21:50 +0200565qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000566@end example
567
568If you don't specify the "file=" argument, you define an empty drive:
569@example
Stefan Weil3804da92012-05-11 22:21:50 +0200570qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +0000571@end example
572
573You can connect a SCSI disk with unit ID 6 on the bus #0:
574@example
Stefan Weil3804da92012-05-11 22:21:50 +0200575qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6
blueswir15824d652009-03-28 06:44:27 +0000576@end example
577
578Instead of @option{-fda}, @option{-fdb}, you can use:
579@example
Stefan Weil3804da92012-05-11 22:21:50 +0200580qemu-system-i386 -drive file=file,index=0,if=floppy
581qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +0000582@end example
583
584By default, @var{interface} is "ide" and @var{index} is automatically
585incremented:
586@example
Stefan Weil3804da92012-05-11 22:21:50 +0200587qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +0000588@end example
589is interpreted like:
590@example
Stefan Weil3804da92012-05-11 22:21:50 +0200591qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +0000592@end example
593ETEXI
594
595DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +0000596 "-mtdblock file use 'file' as on-board Flash memory image\n",
597 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000598STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200599@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100600@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +0200601Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +0000602ETEXI
603
604DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +0000605 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000606STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200607@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100608@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +0200609Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +0000610ETEXI
611
612DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +0000613 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000614STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +0200615@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100616@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +0200617Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +0000618ETEXI
619
blueswir15824d652009-03-28 06:44:27 +0000620DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +0000621 "-snapshot write to temporary files instead of disk image files\n",
622 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000623STEXI
624@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +0100625@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +0000626Write to temporary files instead of disk image files. In this case,
627the raw disk image you use is not written back. You can however force
628the write back by pressing @key{C-a s} (@pxref{disk_images}).
629ETEXI
630
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100631DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
632 "-hdachs c,h,s[,t]\n" \
633 " force hard disk 0 physical geometry and the optional BIOS\n" \
634 " translation (t=none or lba) (usually QEMU can guess them)\n",
Blue Swirlad960902010-03-29 19:23:52 +0000635 QEMU_ARCH_ALL)
Marcelo Tosattic9027602010-03-01 20:25:08 -0300636STEXI
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100637@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
638@findex -hdachs
639Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
640@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
641translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
642all those parameters. This option is useful for old MS-DOS disk
643images.
Markus Armbrusterc70a01e2013-02-13 19:49:40 +0100644ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530645
646DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530647 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530648 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530649 QEMU_ARCH_ALL)
650
651STEXI
652
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530653@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 +0530654@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530655Define a new file system device. Valid options are:
656@table @option
657@item @var{fsdriver}
658This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530659Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530660@item id=@var{id}
661Specifies identifier for this device
662@item path=@var{path}
663Specifies the export path for the file system device. Files under
664this path will be available to the 9p client on the guest.
665@item security_model=@var{security_model}
666Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530667Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530668In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200669credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530670to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530671attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530672file attributes. For "mapped-file" these attributes are stored in the
673hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530674interact with other unix tools. "none" security model is same as
675passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530676set file attributes like ownership. Security model is mandatory
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530677only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530678security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530679@item writeout=@var{writeout}
680This is an optional argument. The only supported value is "immediate".
681This means that host page cache will be used to read and write data but
682write notification will be sent to the guest only when the data has been
683reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +0530684@item readonly
685Enables exporting 9p share as a readonly mount for guests. By default
686read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530687@item socket=@var{socket}
688Enables proxy filesystem driver to use passed socket file for communicating
689with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530690@item sock_fd=@var{sock_fd}
691Enables proxy filesystem driver to use passed socket descriptor for
692communicating with virtfs-proxy-helper. Usually a helper like libvirt
693will create socketpair and pass one of the fds as sock_fd
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530694@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530695
696-fsdev option is used along with -device driver "virtio-9p-pci".
697@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
698Options for virtio-9p-pci driver are:
699@table @option
700@item fsdev=@var{id}
701Specifies the id value specified along with -fsdev option
702@item mount_tag=@var{mount_tag}
703Specifies the tag name to be used by the guest to mount this export point
704@end table
705
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530706ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +0530707
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530708DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530709 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530710 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530711 QEMU_ARCH_ALL)
712
713STEXI
714
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530715@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 +0530716@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530717
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530718The general form of a Virtual File system pass-through options are:
719@table @option
720@item @var{fsdriver}
721This option specifies the fs driver backend to use.
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530722Currently "local", "handle" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530723@item id=@var{id}
724Specifies identifier for this device
725@item path=@var{path}
726Specifies the export path for the file system device. Files under
727this path will be available to the 9p client on the guest.
728@item security_model=@var{security_model}
729Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530730Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530731In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +0200732credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530733to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530734attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +0530735file attributes. For "mapped-file" these attributes are stored in the
736hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530737interact with other unix tools. "none" security model is same as
738passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530739set file attributes like ownership. Security model is mandatory only
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530740for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +0530741model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +0530742@item writeout=@var{writeout}
743This is an optional argument. The only supported value is "immediate".
744This means that host page cache will be used to read and write data but
745write notification will be sent to the guest only when the data has been
746reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +0530747@item readonly
748Enables exporting 9p share as a readonly mount for guests. By default
749read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +0530750@item socket=@var{socket}
751Enables proxy filesystem driver to use passed socket file for
752communicating with virtfs-proxy-helper. Usually a helper like libvirt
753will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +0530754@item sock_fd
755Enables proxy filesystem driver to use passed 'sock_fd' as the socket
756descriptor for interfacing with virtfs-proxy-helper
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530757@end table
758ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +0530759
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +0530760DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
761 "-virtfs_synth Create synthetic file system image\n",
762 QEMU_ARCH_ALL)
763STEXI
764@item -virtfs_synth
765@findex -virtfs_synth
766Create synthetic file system image
767ETEXI
768
blueswir15824d652009-03-28 06:44:27 +0000769STEXI
770@end table
771ETEXI
blueswir15824d652009-03-28 06:44:27 +0000772DEFHEADING()
773
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100774DEFHEADING(USB options:)
775STEXI
776@table @option
777ETEXI
778
779DEF("usb", 0, QEMU_OPTION_usb,
780 "-usb enable the USB driver (will be the default soon)\n",
781 QEMU_ARCH_ALL)
782STEXI
783@item -usb
784@findex -usb
785Enable the USB driver (will be the default soon)
786ETEXI
787
788DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
789 "-usbdevice name add the host or guest USB device 'name'\n",
790 QEMU_ARCH_ALL)
791STEXI
792
793@item -usbdevice @var{devname}
794@findex -usbdevice
795Add the USB device @var{devname}. @xref{usb_devices}.
796
797@table @option
798
799@item mouse
800Virtual Mouse. This will override the PS/2 mouse emulation when activated.
801
802@item tablet
803Pointer device that uses absolute coordinates (like a touchscreen). This
804means QEMU is able to report the mouse position without having to grab the
805mouse. Also overrides the PS/2 mouse emulation when activated.
806
807@item disk:[format=@var{format}]:@var{file}
808Mass storage device based on file. The optional @var{format} argument
809will be used rather than detecting the format. Can be used to specifiy
810@code{format=raw} to avoid interpreting an untrusted format header.
811
812@item host:@var{bus}.@var{addr}
813Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
814
815@item host:@var{vendor_id}:@var{product_id}
816Pass through the host device identified by @var{vendor_id}:@var{product_id}
817(Linux only).
818
819@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
820Serial converter to host character device @var{dev}, see @code{-serial} for the
821available devices.
822
823@item braille
824Braille device. This will use BrlAPI to display the braille output on a real
825or fake device.
826
827@item net:@var{options}
828Network adapter that supports CDC ethernet and RNDIS protocols.
829
830@end table
831ETEXI
832
833STEXI
834@end table
835ETEXI
836DEFHEADING()
837
blueswir15824d652009-03-28 06:44:27 +0000838DEFHEADING(Display options:)
blueswir15824d652009-03-28 06:44:27 +0000839STEXI
840@table @option
841ETEXI
842
Jes Sorensen1472a952011-03-16 13:33:31 +0100843DEF("display", HAS_ARG, QEMU_OPTION_display,
844 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Jes Sorensen3264ff12011-03-16 13:33:33 +0100845 " [,window_close=on|off]|curses|none|\n"
Jan Kiszka881249c2014-03-12 08:33:50 +0100846 " gtk[,grab_on_hover=on|off]|\n"
Jes Sorensen3264ff12011-03-16 13:33:33 +0100847 " vnc=<display>[,<optargs>]\n"
Jes Sorensen1472a952011-03-16 13:33:31 +0100848 " select display type\n", QEMU_ARCH_ALL)
849STEXI
850@item -display @var{type}
851@findex -display
852Select type of display to use. This option is a replacement for the
853old style -sdl/-curses/... options. Valid values for @var{type} are
854@table @option
855@item sdl
856Display video output via SDL (usually in a separate graphics
857window; see the SDL documentation for other possibilities).
858@item curses
859Display video output via curses. For graphics device models which
860support a text mode, QEMU can display this output using a
861curses/ncurses interface. Nothing is displayed when the graphics
862device is in graphical mode or if the graphics device does not support
863a text mode. Generally only the VGA device models support text mode.
Jes Sorensen4171d322011-03-16 13:33:32 +0100864@item none
865Do not display video output. The guest will still see an emulated
866graphics card, but its output will not be displayed to the QEMU
867user. This option differs from the -nographic option in that it
868only affects what is done with video output; -nographic also changes
869the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +0100870@item gtk
871Display video output in a GTK window. This interface provides drop-down
872menus and other UI elements to configure and control the VM during
873runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +0100874@item vnc
875Start a VNC server on display <arg>
Jes Sorensen1472a952011-03-16 13:33:31 +0100876@end table
877ETEXI
878
blueswir15824d652009-03-28 06:44:27 +0000879DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +0000880 "-nographic disable graphical output and redirect serial I/Os to console\n",
881 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000882STEXI
883@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +0100884@findex -nographic
blueswir15824d652009-03-28 06:44:27 +0000885Normally, QEMU uses SDL to display the VGA output. With this option,
886you can totally disable graphical output so that QEMU is a simple
887command line application. The emulated serial port is redirected on
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +0400888the console and muxed with the monitor (unless redirected elsewhere
889explicitly). Therefore, you can still use QEMU to debug a Linux kernel
Ramkumar Ramachandrab031f412013-07-20 16:53:09 +0530890with a serial console. Use @key{C-a h} for help on switching between
891the console and monitor.
blueswir15824d652009-03-28 06:44:27 +0000892ETEXI
893
blueswir15824d652009-03-28 06:44:27 +0000894DEF("curses", 0, QEMU_OPTION_curses,
Blue Swirlad960902010-03-29 19:23:52 +0000895 "-curses use a curses/ncurses interface instead of SDL\n",
896 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000897STEXI
898@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +0100899@findex -curses
blueswir15824d652009-03-28 06:44:27 +0000900Normally, QEMU uses SDL to display the VGA output. With this option,
901QEMU can display the VGA output when in text mode using a
902curses/ncurses interface. Nothing is displayed in graphical mode.
903ETEXI
904
blueswir15824d652009-03-28 06:44:27 +0000905DEF("no-frame", 0, QEMU_OPTION_no_frame,
Blue Swirlad960902010-03-29 19:23:52 +0000906 "-no-frame open SDL window without a frame and window decorations\n",
907 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000908STEXI
909@item -no-frame
Stefan Weil6616b2a2010-02-05 23:52:05 +0100910@findex -no-frame
blueswir15824d652009-03-28 06:44:27 +0000911Do not use decorations for SDL windows and start them using the whole
912available screen space. This makes the using QEMU in a dedicated desktop
913workspace more convenient.
914ETEXI
915
blueswir15824d652009-03-28 06:44:27 +0000916DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +0000917 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
918 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000919STEXI
920@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +0100921@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +1000922Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
923affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +0000924ETEXI
925
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -0500926DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +0000927 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
928 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -0500929STEXI
930@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +0100931@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +1000932Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
933affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -0500934ETEXI
935
blueswir15824d652009-03-28 06:44:27 +0000936DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +0000937 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000938STEXI
939@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +0100940@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +0000941Disable SDL window close capability.
942ETEXI
943
blueswir15824d652009-03-28 06:44:27 +0000944DEF("sdl", 0, QEMU_OPTION_sdl,
Blue Swirlad960902010-03-29 19:23:52 +0000945 "-sdl enable SDL\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000946STEXI
947@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +0100948@findex -sdl
blueswir15824d652009-03-28 06:44:27 +0000949Enable SDL.
950ETEXI
951
Gerd Hoffmann29b00402010-03-11 11:13:27 -0300952DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +0300953 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
954 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
955 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
956 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6]\n"
957 " [,tls-ciphers=<list>]\n"
958 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
959 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
960 " [,sasl][,password=<secret>][,disable-ticketing]\n"
961 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
962 " [,jpeg-wan-compression=[auto|never|always]]\n"
963 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
964 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +0200965 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
966 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +0300967 " enable spice\n"
968 " at least one of {port, tls-port} is mandatory\n",
969 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -0300970STEXI
971@item -spice @var{option}[,@var{option}[,...]]
972@findex -spice
973Enable the spice remote desktop protocol. Valid options are
974
975@table @option
976
977@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -0300978Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -0300979
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +0200980@item addr=<addr>
981Set the IP address spice is listening on. Default is any address.
982
983@item ipv4
984@item ipv6
985Force using the specified IP version.
986
Gerd Hoffmann29b00402010-03-11 11:13:27 -0300987@item password=<secret>
988Set the password you need to authenticate.
989
Marc-André Lureau48b3ed02011-05-17 10:40:33 +0200990@item sasl
991Require that the client use SASL to authenticate with the spice.
992The exact choice of authentication method used is controlled from the
993system / user's SASL configuration file for the 'qemu' service. This
994is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
995unprivileged user, an environment variable SASL_CONF_PATH can be used
996to make it search alternate locations for the service config.
997While some SASL auth methods can also provide data encryption (eg GSSAPI),
998it is recommended that SASL always be combined with the 'tls' and
999'x509' settings to enable use of SSL and server certificates. This
1000ensures a data encryption preventing compromise of authentication
1001credentials.
1002
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001003@item disable-ticketing
1004Allow client connects without authentication.
1005
Hans de Goeded4970b02011-03-27 16:43:54 +02001006@item disable-copy-paste
1007Disable copy paste between the client and the guest.
1008
Hans de Goede5ad24e52013-06-08 15:37:27 +02001009@item disable-agent-file-xfer
1010Disable spice-vdagent based file-xfer between the client and the guest.
1011
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001012@item tls-port=<nr>
1013Set the TCP port spice is listening on for encrypted channels.
1014
1015@item x509-dir=<dir>
1016Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1017
1018@item x509-key-file=<file>
1019@item x509-key-password=<file>
1020@item x509-cert-file=<file>
1021@item x509-cacert-file=<file>
1022@item x509-dh-key-file=<file>
1023The x509 file names can also be configured individually.
1024
1025@item tls-ciphers=<list>
1026Specify which ciphers to use.
1027
Alon Levyd70d6b32011-12-20 13:05:18 +02001028@item tls-channel=[main|display|cursor|inputs|record|playback]
1029@item plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001030Force specific channel to be used with or without TLS encryption. The
1031options can be specified multiple times to configure multiple
1032channels. The special name "default" can be used to set the default
1033mode. For channels which are not explicitly forced into one mode the
1034spice client is allowed to pick tls/plaintext as he pleases.
1035
Yonit Halperin9f04e092010-07-14 13:26:34 +03001036@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1037Configure image compression (lossless).
1038Default is auto_glz.
1039
1040@item jpeg-wan-compression=[auto|never|always]
1041@item zlib-glz-wan-compression=[auto|never|always]
1042Configure wan image compression (lossy for slow links).
1043Default is auto.
1044
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001045@item streaming-video=[off|all|filter]
1046Configure video stream detection. Default is filter.
1047
1048@item agent-mouse=[on|off]
1049Enable/disable passing mouse events via vdagent. Default is on.
1050
1051@item playback-compression=[on|off]
1052Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1053
Yonit Halperin8c957052012-08-21 11:51:59 +03001054@item seamless-migration=[on|off]
1055Enable/disable spice seamless migration. Default is off.
1056
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001057@end table
1058ETEXI
1059
blueswir15824d652009-03-28 06:44:27 +00001060DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001061 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1062 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001063STEXI
1064@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001065@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001066Rotate graphical output 90 deg left (only PXA LCD).
1067ETEXI
1068
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001069DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1070 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1071 QEMU_ARCH_ALL)
1072STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001073@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001074@findex -rotate
1075Rotate graphical output some deg left (only PXA LCD).
1076ETEXI
1077
blueswir15824d652009-03-28 06:44:27 +00001078DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001079 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001080 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001081STEXI
malce4558dc2012-08-27 18:33:21 +04001082@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001083@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001084Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001085@table @option
blueswir15824d652009-03-28 06:44:27 +00001086@item cirrus
1087Cirrus Logic GD5446 Video card. All Windows versions starting from
1088Windows 95 should recognize and use this graphic card. For optimal
1089performances, use 16 bit color depth in the guest and the host OS.
1090(This one is the default)
1091@item std
1092Standard VGA card with Bochs VBE extensions. If your guest OS
1093supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1094to use high resolution modes (>= 1280x1024x16) then you should use
1095this option.
1096@item vmware
1097VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1098recent XFree86/XOrg server or Windows guest with a driver for this
1099card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001100@item qxl
1101QXL paravirtual graphic card. It is VGA compatible (including VESA
11022.0 VBE support). Works best with qxl guest drivers installed though.
1103Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001104@item tcx
1105(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1106sun4m machines and offers both 8-bit and 24-bit colour depths at a
1107fixed resolution of 1024x768.
1108@item cg3
1109(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1110for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1111resolutions aimed at people wishing to run older Solaris versions.
blueswir15824d652009-03-28 06:44:27 +00001112@item none
1113Disable VGA card.
1114@end table
1115ETEXI
1116
1117DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001118 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001119STEXI
1120@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001121@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001122Start in full screen.
1123ETEXI
1124
blueswir15824d652009-03-28 06:44:27 +00001125DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001126 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1127 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001128STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001129@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001130@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001131Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001132ETEXI
1133
1134DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Blue Swirlad960902010-03-29 19:23:52 +00001135 "-vnc display start a VNC server on display\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001136STEXI
1137@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001138@findex -vnc
blueswir15824d652009-03-28 06:44:27 +00001139Normally, QEMU uses SDL to display the VGA output. With this option,
1140you can have QEMU listen on VNC display @var{display} and redirect the VGA
1141display over the VNC session. It is very useful to enable the usb
1142tablet device when using this option (option @option{-usbdevice
1143tablet}). When using the VNC display, you must use the @option{-k}
1144parameter to set the keyboard layout if you are not using en-us. Valid
1145syntax for the @var{display} is
1146
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001147@table @option
blueswir15824d652009-03-28 06:44:27 +00001148
1149@item @var{host}:@var{d}
1150
1151TCP connections will only be allowed from @var{host} on display @var{d}.
1152By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1153be omitted in which case the server will accept connections from any host.
1154
Kevin Wolf4e257e52009-10-09 10:58:36 +02001155@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001156
1157Connections will be allowed over UNIX domain sockets where @var{path} is the
1158location of a unix socket to listen for connections on.
1159
1160@item none
1161
1162VNC is initialized but not started. The monitor @code{change} command
1163can be used to later start the VNC server.
1164
1165@end table
1166
1167Following the @var{display} value there may be one or more @var{option} flags
1168separated by commas. Valid options are
1169
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001170@table @option
blueswir15824d652009-03-28 06:44:27 +00001171
1172@item reverse
1173
1174Connect to a listening VNC client via a ``reverse'' connection. The
1175client is specified by the @var{display}. For reverse network
1176connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1177is a TCP port number, not a display number.
1178
Tim Hardeck7536ee42013-01-21 11:04:44 +01001179@item websocket
1180
1181Opens an additional TCP listening port dedicated to VNC Websocket connections.
Peter Maydell085d8132013-03-18 17:20:07 +00001182By definition the Websocket port is 5700+@var{display}. If @var{host} is
Tim Hardeck7536ee42013-01-21 11:04:44 +01001183specified connections will only be allowed from this host.
1184As an alternative the Websocket port could be specified by using
1185@code{websocket}=@var{port}.
Tim Hardeck0057a0d2013-04-23 16:33:01 +02001186TLS encryption for the Websocket connection is supported if the required
1187certificates are specified with the VNC option @option{x509}.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001188
blueswir15824d652009-03-28 06:44:27 +00001189@item password
1190
1191Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001192
1193The password must be set separately using the @code{set_password} command in
1194the @ref{pcsys_monitor}. The syntax to change your password is:
1195@code{set_password <protocol> <password>} where <protocol> could be either
1196"vnc" or "spice".
1197
1198If you would like to change <protocol> password expiration, you should use
1199@code{expire_password <protocol> <expiration-time>} where expiration time could
1200be one of the following options: now, never, +seconds or UNIX time of
1201expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1202to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1203date and time).
1204
1205You can also use keywords "now" or "never" for the expiration time to
1206allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001207
1208@item tls
1209
1210Require that client use TLS when communicating with the VNC server. This
1211uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1212attack. It is recommended that this option be combined with either the
Kevin Wolf4e257e52009-10-09 10:58:36 +02001213@option{x509} or @option{x509verify} options.
blueswir15824d652009-03-28 06:44:27 +00001214
1215@item x509=@var{/path/to/certificate/dir}
1216
1217Valid if @option{tls} is specified. Require that x509 credentials are used
1218for negotiating the TLS session. The server will send its x509 certificate
1219to the client. It is recommended that a password be set on the VNC server
1220to provide authentication of the client when this is used. The path following
1221this option specifies where the x509 certificates are to be loaded from.
1222See the @ref{vnc_security} section for details on generating certificates.
1223
1224@item x509verify=@var{/path/to/certificate/dir}
1225
1226Valid if @option{tls} is specified. Require that x509 credentials are used
1227for negotiating the TLS session. The server will send its x509 certificate
1228to the client, and request that the client send its own x509 certificate.
1229The server will validate the client's certificate against the CA certificate,
1230and reject clients when validation fails. If the certificate authority is
1231trusted, this is a sufficient authentication mechanism. You may still wish
1232to set a password on the VNC server as a second authentication layer. The
1233path following this option specifies where the x509 certificates are to
1234be loaded from. See the @ref{vnc_security} section for details on generating
1235certificates.
1236
1237@item sasl
1238
1239Require that the client use SASL to authenticate with the VNC server.
1240The exact choice of authentication method used is controlled from the
1241system / user's SASL configuration file for the 'qemu' service. This
1242is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1243unprivileged user, an environment variable SASL_CONF_PATH can be used
1244to make it search alternate locations for the service config.
1245While some SASL auth methods can also provide data encryption (eg GSSAPI),
1246it is recommended that SASL always be combined with the 'tls' and
1247'x509' settings to enable use of SSL and server certificates. This
1248ensures a data encryption preventing compromise of authentication
1249credentials. See the @ref{vnc_security} section for details on using
1250SASL authentication.
1251
1252@item acl
1253
1254Turn on access control lists for checking of the x509 client certificate
1255and SASL party. For x509 certs, the ACL check is made against the
1256certificate's distinguished name. This is something that looks like
1257@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1258made against the username, which depending on the SASL plugin, may
1259include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1260When the @option{acl} flag is set, the initial access list will be
1261empty, with a @code{deny} policy. Thus no one will be allowed to
1262use the VNC server until the ACLs have been loaded. This can be
1263achieved using the @code{acl} monitor command.
1264
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001265@item lossy
1266
1267Enable lossy compression methods (gradient, JPEG, ...). If this
1268option is set, VNC client may receive lossy framebuffer updates
1269depending on its encoding settings. Enabling this option can save
1270a lot of bandwidth at the expense of quality.
1271
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001272@item non-adaptive
1273
1274Disable adaptive encodings. Adaptive encodings are enabled by default.
1275An adaptive encoding will try to detect frequently updated screen regions,
1276and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001277This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001278adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001279like Tight.
1280
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001281@item share=[allow-exclusive|force-shared|ignore]
1282
1283Set display sharing policy. 'allow-exclusive' allows clients to ask
1284for exclusive access. As suggested by the rfb spec this is
1285implemented by dropping other connections. Connecting multiple
1286clients in parallel requires all clients asking for a shared session
1287(vncviewer: -shared switch). This is the default. 'force-shared'
1288disables exclusive client access. Useful for shared desktop sessions,
1289where you don't want someone forgetting specify -shared disconnect
1290everybody else. 'ignore' completely ignores the shared flag and
1291allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001292spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001293
blueswir15824d652009-03-28 06:44:27 +00001294@end table
1295ETEXI
1296
1297STEXI
1298@end table
1299ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001300ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001301
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001302ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001303STEXI
1304@table @option
1305ETEXI
1306
blueswir15824d652009-03-28 06:44:27 +00001307DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001308 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1309 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001310STEXI
1311@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001312@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001313Use it when installing Windows 2000 to avoid a disk full bug. After
1314Windows 2000 is installed, you no longer need this option (this option
1315slows down the IDE transfers).
1316ETEXI
1317
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02001318HXCOMM Deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00001319DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001320
blueswir15824d652009-03-28 06:44:27 +00001321DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001322 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1323 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001324STEXI
1325@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001326@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001327Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001328be needed to boot from old floppy disks.
1329ETEXI
1330
blueswir15824d652009-03-28 06:44:27 +00001331DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Blue Swirlad960902010-03-29 19:23:52 +00001332 "-no-acpi disable ACPI\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001333STEXI
1334@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001335@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001336Disable ACPI (Advanced Configuration and Power Interface) support. Use
1337it if your guest OS complains about ACPI problems (PC target machine
1338only).
1339ETEXI
1340
blueswir15824d652009-03-28 06:44:27 +00001341DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001342 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001343STEXI
1344@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001345@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001346Disable HPET support.
1347ETEXI
1348
blueswir15824d652009-03-28 06:44:27 +00001349DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001350 "-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 +00001351 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001352STEXI
1353@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 +01001354@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001355Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001356For file=, take whole ACPI table from the specified files, including all
1357ACPI headers (possible overridden by other options).
1358For data=, only data
1359portion of the table is used, all header information is specified in the
1360command line.
blueswir15824d652009-03-28 06:44:27 +00001361ETEXI
1362
aliguorib6f6e3d2009-04-17 18:59:56 +00001363DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1364 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001365 " load SMBIOS entry from binary file\n"
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001366 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001367 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00001368 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1369 " [,uuid=uuid][,sku=str][,family=str]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001370 " specify SMBIOS type 1 fields\n", QEMU_ARCH_I386)
aliguorib6f6e3d2009-04-17 18:59:56 +00001371STEXI
1372@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001373@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00001374Load SMBIOS entry from binary file.
1375
Gabriel L. Somlo84351842014-05-19 10:09:54 -04001376@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 +00001377Specify SMBIOS type 0 fields
1378
Blue Swirl609c1da2010-03-18 18:41:49 +00001379@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 +00001380Specify SMBIOS type 1 fields
1381ETEXI
1382
blueswir15824d652009-03-28 06:44:27 +00001383STEXI
1384@end table
1385ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001386DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00001387
1388DEFHEADING(Network options:)
1389STEXI
1390@table @option
1391ETEXI
1392
Jan Kiszkaad196a92009-06-24 14:42:28 +02001393HXCOMM Legacy slirp options (now moved to -net user):
1394#ifdef CONFIG_SLIRP
Blue Swirlad960902010-03-29 19:23:52 +00001395DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1396DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1397DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001398#ifndef _WIN32
Blue Swirlad960902010-03-29 19:23:52 +00001399DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
Jan Kiszkaad196a92009-06-24 14:42:28 +02001400#endif
1401#endif
1402
Blue Swirlbab79442009-06-09 21:50:02 +03001403DEF("net", HAS_ARG, QEMU_OPTION_net,
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001404 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
blueswir15824d652009-03-28 06:44:27 +00001405 " create a new Network Interface Card and connect it to VLAN 'n'\n"
1406#ifdef CONFIG_SLIRP
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02001407 "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
Klaus Stengel63d29602012-10-27 19:53:39 +02001408 " [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n"
1409 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001410#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001411 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02001412#endif
1413 " connect the user mode network stack to VLAN 'n', configure its\n"
1414 " DHCP server and enabled optional services\n"
blueswir15824d652009-03-28 06:44:27 +00001415#endif
1416#ifdef _WIN32
1417 "-net tap[,vlan=n][,name=str],ifname=name\n"
1418 " connect the host TAP network interface to VLAN 'n'\n"
1419#else
Jason Wangec396012013-02-22 22:57:52 +08001420 "-net tap[,vlan=n][,name=str][,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Michal Privoznik3528a3c2012-11-23 09:52:39 +01001421 " connect the host TAP network interface to VLAN 'n'\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001422 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1423 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1424 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001425 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001426 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1427 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00001428 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001429 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001430 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02001431 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001432 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1433 " 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 +02001434 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02001435 " (only has effect for virtio guests which use MSIX)\n"
1436 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02001437 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08001438 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08001439 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001440 "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
1441 " connects a host TAP network interface to a host bridge device 'br'\n"
1442 " (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
1443 " (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01001444#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001445#ifdef __linux__
1446 "-net l2tpv3[,vlan=n][,name=str],src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on/off][,udp=on/off][,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]\n"
1447 " connect the VLAN to an Ethernet over L2TPv3 pseudowire\n"
1448 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04001449 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001450 " VM to a router and even VM to Host. It is a nearly-universal\n"
1451 " standard (RFC3391). Note - this implementation uses static\n"
1452 " pre-configured tunnels (same as the Linux kernel).\n"
1453 " use 'src=' to specify source address\n"
1454 " use 'dst=' to specify destination address\n"
1455 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08001456 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001457 " use 'dstport=' to specify destination udp port\n"
1458 " use 'ipv6=on' to force v6\n"
1459 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1460 " well as a weak security measure\n"
1461 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1462 " use 'txcookie=0x012345678' to specify a txcookie\n"
1463 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1464 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1465 " use 'pincounter=on' to work around broken counter handling in peer\n"
1466 " use 'offset=X' to add an extra offset between header and data\n"
1467#endif
blueswir15824d652009-03-28 06:44:27 +00001468 "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
1469 " connect the vlan 'n' to another VLAN using a socket connection\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08001470 "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
blueswir15824d652009-03-28 06:44:27 +00001471 " connect the vlan 'n' to multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08001472 " use 'localaddr=addr' to specify the host address to send packets from\n"
Benjamin0e0e7fa2012-01-11 09:20:54 +09001473 "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
1474 " connect the vlan 'n' to another VLAN using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00001475#ifdef CONFIG_VDE
1476 "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1477 " connect the vlan 'n' to port 'n' of a vde switch running\n"
1478 " on host and listening for incoming connections on 'socketpath'.\n"
1479 " Use group 'groupname' and mode 'octalmode' to change default\n"
1480 " ownership and permissions for communication port.\n"
1481#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001482#ifdef CONFIG_NETMAP
1483 "-net netmap,ifname=name[,devname=nmname]\n"
1484 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1485 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1486 " netmap device, defaults to '/dev/netmap')\n"
1487#endif
aliguoribb9ea792009-04-21 19:56:28 +00001488 "-net dump[,vlan=n][,file=f][,len=n]\n"
1489 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07001490 "-net none use it alone to have zero network devices. If no -net option\n"
Blue Swirlad960902010-03-29 19:23:52 +00001491 " is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL)
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001492DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1493 "-netdev ["
1494#ifdef CONFIG_SLIRP
1495 "user|"
1496#endif
1497 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001498 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01001499#ifdef CONFIG_VDE
1500 "vde|"
1501#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01001502#ifdef CONFIG_NETMAP
1503 "netmap|"
1504#endif
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03001505 "vhost-user|"
Stefan Hajnoczi40e8c262013-02-26 11:07:16 +01001506 "socket|"
1507 "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001508STEXI
Blue Swirl609c1da2010-03-18 18:41:49 +00001509@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 +01001510@findex -net
blueswir15824d652009-03-28 06:44:27 +00001511Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
Anthony Liguori0d6b0b12009-08-14 11:20:47 -05001512= 0 is the default). The NIC is an e1000 by default on the PC
Markus Armbruster5607c382009-06-18 15:14:08 +02001513target. Optionally, the MAC address can be changed to @var{mac}, the
1514device address set to @var{addr} (PCI cards only),
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001515and a @var{name} can be assigned for use in monitor commands.
1516Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1517that the card should have; this option currently only affects virtio cards; set
1518@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
Stefan Weil071c9392012-04-07 09:23:36 +02001519NIC is created. QEMU can emulate several different models of network card.
blueswir15824d652009-03-28 06:44:27 +00001520Valid values for @var{type} are
Michael S. Tsirkinffe63702009-06-21 19:51:18 +03001521@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
blueswir15824d652009-03-28 06:44:27 +00001522@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1523@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
Peter Maydell585f6032012-10-04 16:22:01 +01001524Not all devices are supported on all targets. Use @code{-net nic,model=help}
blueswir15824d652009-03-28 06:44:27 +00001525for a list of available devices for your target.
1526
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001527@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001528@findex -netdev
Jan Kiszkaad196a92009-06-24 14:42:28 +02001529@item -net user[,@var{option}][,@var{option}][,...]
blueswir15824d652009-03-28 06:44:27 +00001530Use the user mode network stack which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02001531privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00001532
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001533@table @option
Jan Kiszkaad196a92009-06-24 14:42:28 +02001534@item vlan=@var{n}
1535Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1536
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001537@item id=@var{id}
Jan Kiszkaad196a92009-06-24 14:42:28 +02001538@item name=@var{name}
1539Assign symbolic name for use in monitor commands.
1540
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001541@item net=@var{addr}[/@var{mask}]
1542Set IP network address the guest will see. Optionally specify the netmask,
1543either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000154410.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001545
1546@item host=@var{addr}
1547Specify the guest-visible address of the host. Default is the 2nd IP in the
1548guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001549
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02001550@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10001551If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02001552able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10001553to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001554
1555@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02001556Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001557
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001558@item dhcpstart=@var{addr}
1559Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10001560is 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 +02001561
1562@item dns=@var{addr}
1563Specify the guest-visible address of the virtual nameserver. The address must
1564be different from the host address. Default is the 3rd IP in the guest network,
1565i.e. x.x.x.3.
1566
Klaus Stengel63d29602012-10-27 19:53:39 +02001567@item dnssearch=@var{domain}
1568Provides an entry for the domain-search list sent by the built-in
1569DHCP server. More than one domain suffix can be transmitted by specifying
1570this option multiple times. If supported, this will cause the guest to
1571automatically try to append the given domain suffix(es) in case a domain name
1572can not be resolved.
1573
1574Example:
1575@example
1576qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1577@end example
1578
Jan Kiszkaad196a92009-06-24 14:42:28 +02001579@item tftp=@var{dir}
1580When using the user mode network stack, activate a built-in TFTP
1581server. The files in @var{dir} will be exposed as the root of a TFTP server.
1582The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001583@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02001584
1585@item bootfile=@var{file}
1586When using the user mode network stack, broadcast @var{file} as the BOOTP
1587filename. In conjunction with @option{tftp}, this can be used to network boot
1588a guest from a local directory.
1589
1590Example (using pxelinux):
1591@example
Stefan Weil3804da92012-05-11 22:21:50 +02001592qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02001593@end example
1594
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001595@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001596When using the user mode network stack, activate a built-in SMB
1597server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001598transparently. The IP address of the SMB server can be set to @var{addr}. By
1599default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001600
1601In the guest Windows OS, the line:
1602@example
160310.0.2.4 smbserver
1604@end example
1605must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1606or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1607
1608Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1609
Brade2d88302011-09-02 16:53:28 -04001610Note that a SAMBA server must be installed on the host OS.
1611QEMU was tested successfully with smbd versions from Red Hat 9,
1612Fedora Core 3 and OpenSUSE 11.x.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001613
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001614@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001615Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1616the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1617@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001618given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1619be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001620used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02001621
1622For example, to redirect host X11 connection from screen 1 to guest
1623screen 0, use the following:
1624
1625@example
1626# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02001627qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001628# this host xterm should open in the guest X11 server
1629xterm -display :1
1630@end example
1631
1632To redirect telnet connections from host port 5555 to telnet port on
1633the guest, use the following:
1634
1635@example
1636# on the host
Stefan Weil3804da92012-05-11 22:21:50 +02001637qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
Jan Kiszkaad196a92009-06-24 14:42:28 +02001638telnet localhost 5555
1639@end example
1640
1641Then when you use on the host @code{telnet localhost 5555}, you
1642connect to the guest telnet server.
1643
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02001644@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Alexander Grafb412eb62012-06-03 09:45:01 +02001645@item guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02001646Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02001647to the character device @var{dev} or to a program executed by @var{cmd:command}
1648which gets spawned for each connection. This option can be given multiple times.
1649
Stefan Weil43ffe612012-07-20 23:26:02 +02001650You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02001651lifetime, like in the following example:
1652
1653@example
1654# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1655# the guest accesses it
1656qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
1657@end example
1658
1659Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02001660so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02001661
1662@example
1663# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1664# and connect the TCP stream to its stdin/stdout
1665qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1666@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02001667
1668@end table
1669
1670Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1671processed and applied to -net user. Mixing them with the new configuration
1672syntax gives undefined results. Their use for new applications is discouraged
1673as they will be removed from future versions.
blueswir15824d652009-03-28 06:44:27 +00001674
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001675@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001676@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1677Connect the host TAP network interface @var{name} to VLAN @var{n}.
1678
1679Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00001680@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001681automatically provides one. The default network configure script is
1682@file{/etc/qemu-ifup} and the default network deconfigure script is
1683@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1684to disable script execution.
1685
1686If running QEMU as an unprivileged user, use the network helper
1687@var{helper} to configure the TAP interface. The default network
Amos Kong420508f2013-10-23 04:49:28 +08001688helper executable is @file{/path/to/qemu-bridge-helper}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001689
1690@option{fd}=@var{h} can be used to specify the handle of an already
1691opened host TAP interface.
1692
1693Examples:
blueswir15824d652009-03-28 06:44:27 +00001694
1695@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001696#launch a QEMU instance with the default network script
Stefan Weil3804da92012-05-11 22:21:50 +02001697qemu-system-i386 linux.img -net nic -net tap
blueswir15824d652009-03-28 06:44:27 +00001698@end example
1699
blueswir15824d652009-03-28 06:44:27 +00001700@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001701#launch a QEMU instance with two NICs, each one connected
1702#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02001703qemu-system-i386 linux.img \
1704 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1705 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
blueswir15824d652009-03-28 06:44:27 +00001706@end example
1707
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001708@example
1709#launch a QEMU instance with the default network helper to
1710#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02001711qemu-system-i386 linux.img \
Amos Kong420508f2013-10-23 04:49:28 +08001712 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001713@end example
1714
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001715@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001716@item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1717Connect a host TAP network interface to a host bridge device.
1718
1719Use the network helper @var{helper} to configure the TAP interface and
1720attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08001721@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001722device is @file{br0}.
1723
1724Examples:
1725
1726@example
1727#launch a QEMU instance with the default network helper to
1728#connect a TAP device to bridge br0
Stefan Weil3804da92012-05-11 22:21:50 +02001729qemu-system-i386 linux.img -net bridge -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001730@end example
1731
1732@example
1733#launch a QEMU instance with the default network helper to
1734#connect a TAP device to bridge qemubr0
Stefan Weil3804da92012-05-11 22:21:50 +02001735qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
Corey Bryanta7c36ee2012-01-26 09:42:27 -05001736@end example
1737
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001738@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Blue Swirl609c1da2010-03-18 18:41:49 +00001739@item -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 +00001740
1741Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1742machine using a TCP socket connection. If @option{listen} is
1743specified, QEMU waits for incoming connections on @var{port}
1744(@var{host} is optional). @option{connect} is used to connect to
1745another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1746specifies an already opened TCP socket.
1747
1748Example:
1749@example
1750# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02001751qemu-system-i386 linux.img \
1752 -net nic,macaddr=52:54:00:12:34:56 \
1753 -net socket,listen=:1234
blueswir15824d652009-03-28 06:44:27 +00001754# connect the VLAN 0 of this instance to the VLAN 0
1755# of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02001756qemu-system-i386 linux.img \
1757 -net nic,macaddr=52:54:00:12:34:57 \
1758 -net socket,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00001759@end example
1760
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001761@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
Mike Ryan3a75e742010-12-01 11:16:47 -08001762@item -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 +00001763
1764Create a VLAN @var{n} shared with another QEMU virtual
1765machines using a UDP multicast socket, effectively making a bus for
1766every QEMU with same multicast address @var{maddr} and @var{port}.
1767NOTES:
1768@enumerate
1769@item
1770Several QEMU can be running on different hosts and share same bus (assuming
1771correct multicast setup for these hosts).
1772@item
1773mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1774@url{http://user-mode-linux.sf.net}.
1775@item
1776Use @option{fd=h} to specify an already opened UDP multicast socket.
1777@end enumerate
1778
1779Example:
1780@example
1781# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02001782qemu-system-i386 linux.img \
1783 -net nic,macaddr=52:54:00:12:34:56 \
1784 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00001785# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02001786qemu-system-i386 linux.img \
1787 -net nic,macaddr=52:54:00:12:34:57 \
1788 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00001789# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02001790qemu-system-i386 linux.img \
1791 -net nic,macaddr=52:54:00:12:34:58 \
1792 -net socket,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00001793@end example
1794
1795Example (User Mode Linux compat.):
1796@example
1797# launch QEMU instance (note mcast address selected
1798# is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02001799qemu-system-i386 linux.img \
1800 -net nic,macaddr=52:54:00:12:34:56 \
1801 -net socket,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00001802# launch UML
1803/path/to/linux ubd0=/path/to/root_fs eth0=mcast
1804@end example
1805
Mike Ryan3a75e742010-12-01 11:16:47 -08001806Example (send packets from host's 1.2.3.4):
1807@example
Stefan Weil3804da92012-05-11 22:21:50 +02001808qemu-system-i386 linux.img \
1809 -net nic,macaddr=52:54:00:12:34:56 \
1810 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08001811@end example
1812
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01001813@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}]
1814@item -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}]
1815Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
1816protocol to transport Ethernet (and other Layer 2) data frames between
1817two systems. It is present in routers, firewalls and the Linux kernel
1818(from version 3.3 onwards).
1819
1820This transport allows a VM to communicate to another VM, router or firewall directly.
1821
1822@item src=@var{srcaddr}
1823 source address (mandatory)
1824@item dst=@var{dstaddr}
1825 destination address (mandatory)
1826@item udp
1827 select udp encapsulation (default is ip).
1828@item srcport=@var{srcport}
1829 source udp port.
1830@item dstport=@var{dstport}
1831 destination udp port.
1832@item ipv6
1833 force v6, otherwise defaults to v4.
1834@item rxcookie=@var{rxcookie}
1835@item txcookie=@var{txcookie}
1836 Cookies are a weak form of security in the l2tpv3 specification.
1837Their function is mostly to prevent misconfiguration. By default they are 32
1838bit.
1839@item cookie64
1840 Set cookie size to 64 bit instead of the default 32
1841@item counter=off
1842 Force a 'cut-down' L2TPv3 with no counter as in
1843draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
1844@item pincounter=on
1845 Work around broken counter handling in peer. This may also help on
1846networks which have packet reorder.
1847@item offset=@var{offset}
1848 Add an extra offset between header and data
1849
1850For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
1851on the remote Linux host 1.2.3.4:
1852@example
1853# Setup tunnel on linux host using raw ip as encapsulation
1854# on 1.2.3.4
1855ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
1856 encap udp udp_sport 16384 udp_dport 16384
1857ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
1858 0xFFFFFFFF peer_session_id 0xFFFFFFFF
1859ifconfig vmtunnel0 mtu 1500
1860ifconfig vmtunnel0 up
1861brctl addif br-lan vmtunnel0
1862
1863
1864# on 4.3.2.1
1865# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
1866
1867qemu-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
1868
1869
1870@end example
1871
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01001872@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
Blue Swirl609c1da2010-03-18 18:41:49 +00001873@item -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 +00001874Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1875listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1876and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02001877communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00001878with vde support enabled.
1879
1880Example:
1881@example
1882# launch vde switch
1883vde_switch -F -sock /tmp/myswitch
1884# launch QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02001885qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00001886@end example
1887
Stefan Hajnoczi40e8c262013-02-26 11:07:16 +01001888@item -netdev hubport,id=@var{id},hubid=@var{hubid}
1889
1890Create a hub port on QEMU "vlan" @var{hubid}.
1891
1892The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
1893netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
1894required hub automatically.
1895
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03001896@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off]
1897
1898Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
1899be a unix domain socket backed one. The vhost-user uses a specifically defined
1900protocol to pass vhost ioctl replacement messages to an application on the other
1901end of the socket. On non-MSIX guests, the feature can be forced with
1902@var{vhostforce}.
1903
1904Example:
1905@example
1906qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
1907 -numa node,memdev=mem \
1908 -chardev socket,path=/path/to/socket \
1909 -netdev type=vhost-user,id=net0,chardev=chr0 \
1910 -device virtio-net-pci,netdev=net0
1911@end example
1912
aliguoribb9ea792009-04-21 19:56:28 +00001913@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1914Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1915At most @var{len} bytes (64k by default) per packet are stored. The file format is
1916libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1917
blueswir15824d652009-03-28 06:44:27 +00001918@item -net none
1919Indicate that no network devices should be configured. It is used to
1920override the default configuration (@option{-net nic -net user}) which
1921is activated if no @option{-net} options are provided.
blueswir15824d652009-03-28 06:44:27 +00001922ETEXI
1923
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001924STEXI
1925@end table
1926ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00001927DEFHEADING()
1928
1929DEFHEADING(Character device options:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01001930STEXI
1931
1932The general form of a character device option is:
1933@table @option
1934ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00001935
1936DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Jan Kiszka97331282010-04-06 16:55:54 +02001937 "-chardev null,id=id[,mux=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05001938 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
1939 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off] (tcp)\n"
1940 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001941 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02001942 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1943 "-chardev msmouse,id=id[,mux=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001944 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02001945 " [,mux=on|off]\n"
Markus Armbruster4f573782013-07-26 16:44:32 +02001946 "-chardev ringbuf,id=id[,size=size]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02001947 "-chardev file,id=id,path=path[,mux=on|off]\n"
1948 "-chardev pipe,id=id,path=path[,mux=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001949#ifdef _WIN32
Jan Kiszka97331282010-04-06 16:55:54 +02001950 "-chardev console,id=id[,mux=on|off]\n"
1951 "-chardev serial,id=id,path=path[,mux=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001952#else
Jan Kiszka97331282010-04-06 16:55:54 +02001953 "-chardev pty,id=id[,mux=on|off]\n"
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02001954 "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001955#endif
1956#ifdef CONFIG_BRLAPI
Jan Kiszka97331282010-04-06 16:55:54 +02001957 "-chardev braille,id=id[,mux=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001958#endif
1959#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1960 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01001961 "-chardev serial,id=id,path=path[,mux=on|off]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02001962 "-chardev tty,id=id,path=path[,mux=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001963#endif
1964#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01001965 "-chardev parallel,id=id,path=path[,mux=on|off]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02001966 "-chardev parport,id=id,path=path[,mux=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00001967#endif
Alon Levycbcc6332011-01-19 10:49:50 +02001968#if defined(CONFIG_SPICE)
1969 "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01001970 "-chardev spiceport,id=id,name=name[,debug=debug]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02001971#endif
Blue Swirlad960902010-03-29 19:23:52 +00001972 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00001973)
1974
1975STEXI
Jan Kiszka97331282010-04-06 16:55:54 +02001976@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001977@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00001978Backend is one of:
1979@option{null},
1980@option{socket},
1981@option{udp},
1982@option{msmouse},
1983@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02001984@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00001985@option{file},
1986@option{pipe},
1987@option{console},
1988@option{serial},
1989@option{pty},
1990@option{stdio},
1991@option{braille},
1992@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01001993@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02001994@option{parport},
1995@option{spicevmc}.
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01001996@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00001997The specific backend will determine the applicable options.
1998
1999All devices must have an id, which can be any string up to 127 characters long.
2000It is used to uniquely identify this device in other command line directives.
2001
Jan Kiszka97331282010-04-06 16:55:54 +02002002A character device may be used in multiplexing mode by multiple front-ends.
2003The key sequence of @key{Control-a} and @key{c} will rotate the input focus
2004between attached front-ends. Specify @option{mux=on} to enable this mode.
2005
Matthew Booth7273a2d2009-10-30 13:41:12 +00002006Options to each backend are described below.
2007
2008@item -chardev null ,id=@var{id}
2009A void device. This device will not emit any data, and will drop any data it
2010receives. The null backend does not take any options.
2011
Corey Minyard5dd1f022014-10-02 11:17:37 -05002012@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002013
2014Create a two-way stream socket, which can be either a TCP or a unix socket. A
2015unix socket will be created if @option{path} is specified. Behaviour is
2016undefined if TCP options are specified for a unix socket.
2017
2018@option{server} specifies that the socket shall be a listening socket.
2019
2020@option{nowait} specifies that QEMU should not block waiting for a client to
2021connect to a listening socket.
2022
2023@option{telnet} specifies that traffic on the socket should interpret telnet
2024escape sequences.
2025
Corey Minyard5dd1f022014-10-02 11:17:37 -05002026@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2027the remote end goes away. qemu will delay this many seconds and then attempt
2028to reconnect. Zero disables reconnecting, and is the default.
2029
Matthew Booth7273a2d2009-10-30 13:41:12 +00002030TCP and unix socket options are given below:
2031
2032@table @option
2033
Aurelien Jarno8d533562010-03-27 11:52:05 +01002034@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002035
2036@option{host} for a listening socket specifies the local address to be bound.
2037For a connecting socket species the remote host to connect to. @option{host} is
2038optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2039
2040@option{port} for a listening socket specifies the local port to be bound. For a
2041connecting socket specifies the port on the remote host to connect to.
2042@option{port} can be given as either a port number or a service name.
2043@option{port} is required.
2044
2045@option{to} is only relevant to listening sockets. If it is specified, and
2046@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2047to and including @option{to} until it succeeds. @option{to} must be specified
2048as a port number.
2049
2050@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2051If neither is specified the socket may use either protocol.
2052
2053@option{nodelay} disables the Nagle algorithm.
2054
2055@item unix options: path=@var{path}
2056
2057@option{path} specifies the local path of the unix socket. @option{path} is
2058required.
2059
2060@end table
2061
2062@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2063
2064Sends all traffic from the guest to a remote host over UDP.
2065
2066@option{host} specifies the remote host to connect to. If not specified it
2067defaults to @code{localhost}.
2068
2069@option{port} specifies the port on the remote host to connect to. @option{port}
2070is required.
2071
2072@option{localaddr} specifies the local address to bind to. If not specified it
2073defaults to @code{0.0.0.0}.
2074
2075@option{localport} specifies the local port to bind to. If not specified any
2076available local port will be used.
2077
2078@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2079If neither is specified the device may use either protocol.
2080
2081@item -chardev msmouse ,id=@var{id}
2082
2083Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2084take any options.
2085
2086@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2087
2088Connect to a QEMU text console. @option{vc} may optionally be given a specific
2089size.
2090
2091@option{width} and @option{height} specify the width and height respectively of
2092the console, in pixels.
2093
2094@option{cols} and @option{rows} specify that the console be sized to fit a text
2095console with the given dimensions.
2096
Markus Armbruster4f573782013-07-26 16:44:32 +02002097@item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002098
Markus Armbruster3949e592013-02-06 21:27:24 +01002099Create a ring buffer with fixed size @option{size}.
2100@var{size} must be a power of two, and defaults to @code{64K}).
Lei Li51767e72013-01-25 00:03:19 +08002101
Matthew Booth7273a2d2009-10-30 13:41:12 +00002102@item -chardev file ,id=@var{id} ,path=@var{path}
2103
2104Log all traffic received from the guest to a file.
2105
2106@option{path} specifies the path of the file to be opened. This file will be
2107created if it does not already exist, and overwritten if it does. @option{path}
2108is required.
2109
2110@item -chardev pipe ,id=@var{id} ,path=@var{path}
2111
2112Create a two-way connection to the guest. The behaviour differs slightly between
2113Windows hosts and other hosts:
2114
2115On Windows, a single duplex pipe will be created at
2116@file{\\.pipe\@option{path}}.
2117
2118On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2119@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2120received by the guest. Data written by the guest can be read from
2121@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2122be present.
2123
2124@option{path} forms part of the pipe path as described above. @option{path} is
2125required.
2126
2127@item -chardev console ,id=@var{id}
2128
2129Send traffic from the guest to QEMU's standard output. @option{console} does not
2130take any options.
2131
2132@option{console} is only available on Windows hosts.
2133
2134@item -chardev serial ,id=@var{id} ,path=@option{path}
2135
2136Send traffic from the guest to a serial device on the host.
2137
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002138On Unix hosts serial will actually accept any tty device,
2139not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002140
2141@option{path} specifies the name of the serial device to open.
2142
2143@item -chardev pty ,id=@var{id}
2144
2145Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2146not take any options.
2147
2148@option{pty} is not available on Windows hosts.
2149
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002150@item -chardev stdio ,id=@var{id} [,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002151Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002152
2153@option{signal} controls if signals are enabled on the terminal, that includes
2154exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2155default, use @option{signal=off} to disable it.
2156
2157@option{stdio} is not available on Windows hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002158
2159@item -chardev braille ,id=@var{id}
2160
2161Connect to a local BrlAPI server. @option{braille} does not take any options.
2162
2163@item -chardev tty ,id=@var{id} ,path=@var{path}
2164
Matthew Booth7273a2d2009-10-30 13:41:12 +00002165@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002166DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002167
2168@option{path} specifies the path to the tty. @option{path} is required.
2169
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002170@item -chardev parallel ,id=@var{id} ,path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002171@item -chardev parport ,id=@var{id} ,path=@var{path}
2172
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002173@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002174
2175Connect to a local parallel port.
2176
2177@option{path} specifies the path to the parallel port device. @option{path} is
2178required.
2179
Alon Levycbcc6332011-01-19 10:49:50 +02002180@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2181
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002182@option{spicevmc} is only available when spice support is built in.
2183
Alon Levycbcc6332011-01-19 10:49:50 +02002184@option{debug} debug level for spicevmc
2185
2186@option{name} name of spice channel to connect to
2187
2188Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002189
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002190@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2191
2192@option{spiceport} is only available when spice support is built in.
2193
2194@option{debug} debug level for spicevmc
2195
2196@option{name} name of spice port to connect to
2197
2198Connect to a spice port, allowing a Spice client to handle the traffic
2199identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002200ETEXI
2201
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002202STEXI
2203@end table
2204ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002205DEFHEADING()
2206
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002207DEFHEADING(Device URL Syntax:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002208STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002209
2210In addition to using normal file images for the emulated storage devices,
2211QEMU can also use networked resources such as iSCSI devices. These are
2212specified using a special URL syntax.
2213
2214@table @option
2215@item iSCSI
2216iSCSI support allows QEMU to access iSCSI resources directly and use as
2217images for the guest storage. Both disk and cdrom images are supported.
2218
2219Syntax for specifying iSCSI LUNs is
2220``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2221
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002222By default qemu will use the iSCSI initiator-name
2223'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2224line or a configuration file.
2225
2226
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002227Example (without authentication):
2228@example
Stefan Weil3804da92012-05-11 22:21:50 +02002229qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2230 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2231 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002232@end example
2233
2234Example (CHAP username/password via URL):
2235@example
Stefan Weil3804da92012-05-11 22:21:50 +02002236qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002237@end example
2238
2239Example (CHAP username/password via environment variables):
2240@example
2241LIBISCSI_CHAP_USERNAME="user" \
2242LIBISCSI_CHAP_PASSWORD="password" \
Stefan Weil3804da92012-05-11 22:21:50 +02002243qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002244@end example
2245
2246iSCSI support is an optional feature of QEMU and only available when
2247compiled and linked against libiscsi.
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11002248ETEXI
2249DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2250 "-iscsi [user=user][,password=password]\n"
2251 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
Paolo Bonzini2fe37982013-12-06 16:08:05 +01002252 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
Ronnie Sahlbergf9dadc92012-01-26 09:39:02 +11002253 " iSCSI session parameters\n", QEMU_ARCH_ALL)
2254STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002255
Ronnie Sahlberg31459f42012-08-06 18:24:55 +10002256iSCSI parameters such as username and password can also be specified via
2257a configuration file. See qemu-doc for more information and examples.
2258
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002259@item NBD
2260QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2261as Unix Domain Sockets.
2262
2263Syntax for specifying a NBD device using TCP
2264``nbd:<server-ip>:<port>[:exportname=<export>]''
2265
2266Syntax for specifying a NBD device using Unix Domain Sockets
2267``nbd:unix:<domain-socket>[:exportname=<export>]''
2268
2269
2270Example for TCP
2271@example
Stefan Weil3804da92012-05-11 22:21:50 +02002272qemu-system-i386 --drive file=nbd:192.0.2.1:30000
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002273@end example
2274
2275Example for Unix Domain Sockets
2276@example
Stefan Weil3804da92012-05-11 22:21:50 +02002277qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
Ronnie Sahlberg08ae3302011-10-27 20:33:21 +11002278@end example
2279
Richard W.M. Jones0a12ec82013-04-09 15:30:53 +01002280@item SSH
2281QEMU supports SSH (Secure Shell) access to remote disks.
2282
2283Examples:
2284@example
2285qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2286qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2287@end example
2288
2289Currently authentication must be done using ssh-agent. Other
2290authentication methods may be supported in future.
2291
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002292@item Sheepdog
2293Sheepdog is a distributed storage system for QEMU.
2294QEMU supports using either local sheepdog devices or remote networked
2295devices.
2296
2297Syntax for specifying a sheepdog device
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002298@example
MORITA Kazutaka1b8bbb42013-02-22 12:39:53 +09002299sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002300@end example
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002301
2302Example
2303@example
MORITA Kazutaka5d6768e2013-02-22 12:39:51 +09002304qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
Ronnie Sahlbergd9990222011-10-28 20:13:39 +11002305@end example
2306
2307See also @url{http://http://www.osrg.net/sheepdog/}.
2308
Bharata B Rao8809e282012-10-24 17:17:53 +05302309@item GlusterFS
2310GlusterFS is an user space distributed file system.
2311QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2312TCP, Unix Domain Sockets and RDMA transport protocols.
2313
2314Syntax for specifying a VM disk image on GlusterFS volume is
2315@example
2316gluster[+transport]://[server[:port]]/volname/image[?socket=...]
2317@end example
2318
2319
2320Example
2321@example
Lei Lidb2d5eb2013-03-07 15:50:26 +08002322qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
Bharata B Rao8809e282012-10-24 17:17:53 +05302323@end example
2324
2325See also @url{http://www.gluster.org}.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002326
2327@item HTTP/HTTPS/FTP/FTPS/TFTP
2328QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp.
2329
2330Syntax using a single filename:
2331@example
2332<protocol>://[<username>[:<password>]@@]<host>/<path>
2333@end example
2334
2335where:
2336@table @option
2337@item protocol
2338'http', 'https', 'ftp', 'ftps', or 'tftp'.
2339
2340@item username
2341Optional username for authentication to the remote server.
2342
2343@item password
2344Optional password for authentication to the remote server.
2345
2346@item host
2347Address of the remote server.
2348
2349@item path
2350Path on the remote server, including any query string.
2351@end table
2352
2353The following options are also supported:
2354@table @option
2355@item url
2356The full URL when passing options to the driver explicitly.
2357
2358@item readahead
2359The amount of data to read ahead with each range request to the remote server.
2360This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2361does not have a suffix, it will be assumed to be in bytes. The value must be a
2362multiple of 512 bytes. It defaults to 256k.
2363
2364@item sslverify
2365Whether to verify the remote server's certificate when connecting over SSL. It
2366can have the value 'on' or 'off'. It defaults to 'on'.
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002367
Richard W.M. Jonesa94f83d2014-08-29 16:03:12 +01002368@item cookie
2369Send this cookie (it can also be a list of cookies separated by ';') with
2370each outgoing request. Only supported when using protocols such as HTTP
2371which support cookies, otherwise ignored.
2372
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002373@item timeout
2374Set the timeout in seconds of the CURL connection. This timeout is the time
2375that CURL waits for a response from the remote server to get the size of the
2376image to be downloaded. If not set, the default timeout of 5 seconds is used.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002377@end table
2378
2379Note that when passing options to qemu explicitly, @option{driver} is the value
2380of <protocol>.
2381
2382Example: boot from a remote Fedora 20 live ISO image
2383@example
2384qemu-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
2385
2386qemu-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
2387@end example
2388
2389Example: boot from a remote Fedora 20 cloud image using a local overlay for
2390writes, copy-on-read, and a readahead of 64k
2391@example
2392qemu-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
2393
2394qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
2395@end example
2396
2397Example: boot from an image stored on a VMware vSphere server with a self-signed
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002398certificate using a local overlay for writes, a readahead of 64k and a timeout
2399of 10 seconds.
Matthew Booth0a86cb72014-05-14 19:28:43 -04002400@example
Daniel Henrique Barboza212aefa2014-08-13 12:44:27 -03002401qemu-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 -04002402
2403qemu-system-x86_64 -drive file=/tmp/test.qcow2
2404@end example
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002405ETEXI
2406
2407STEXI
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11002408@end table
2409ETEXI
2410
Matthew Booth7273a2d2009-10-30 13:41:12 +00002411DEFHEADING(Bluetooth(R) options:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002412STEXI
2413@table @option
2414ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002415
blueswir15824d652009-03-28 06:44:27 +00002416DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00002417 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2418 "-bt hci,host[:id]\n" \
2419 " use host's HCI with the given name\n" \
2420 "-bt hci[,vlan=n]\n" \
2421 " emulate a standard HCI in virtual scatternet 'n'\n" \
2422 "-bt vhci[,vlan=n]\n" \
2423 " add host computer to virtual scatternet 'n' using VHCI\n" \
2424 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002425 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2426 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002427STEXI
blueswir15824d652009-03-28 06:44:27 +00002428@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002429@findex -bt
blueswir15824d652009-03-28 06:44:27 +00002430Defines the function of the corresponding Bluetooth HCI. -bt options
2431are matched with the HCIs present in the chosen machine type. For
2432example when emulating a machine with only one HCI built into it, only
2433the first @code{-bt hci[...]} option is valid and defines the HCI's
2434logic. The Transport Layer is decided by the machine type. Currently
2435the machines @code{n800} and @code{n810} have one HCI and all other
2436machines have none.
2437
2438@anchor{bt-hcis}
2439The following three types are recognized:
2440
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002441@table @option
blueswir15824d652009-03-28 06:44:27 +00002442@item -bt hci,null
2443(default) The corresponding Bluetooth HCI assumes no internal logic
2444and will not respond to any HCI commands or emit events.
2445
2446@item -bt hci,host[:@var{id}]
2447(@code{bluez} only) The corresponding HCI passes commands / events
2448to / from the physical HCI identified by the name @var{id} (default:
2449@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2450capable systems like Linux.
2451
2452@item -bt hci[,vlan=@var{n}]
2453Add a virtual, standard HCI that will participate in the Bluetooth
2454scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2455VLANs, devices inside a bluetooth network @var{n} can only communicate
2456with other devices in the same network (scatternet).
2457@end table
2458
2459@item -bt vhci[,vlan=@var{n}]
2460(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2461to the host bluetooth stack instead of to the emulated target. This
2462allows the host and target machines to participate in a common scatternet
2463and communicate. Requires the Linux @code{vhci} driver installed. Can
2464be used as following:
2465
2466@example
Stefan Weil3804da92012-05-11 22:21:50 +02002467qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00002468@end example
2469
2470@item -bt device:@var{dev}[,vlan=@var{n}]
2471Emulate a bluetooth device @var{dev} and place it in network @var{n}
2472(default @code{0}). QEMU can only emulate one type of bluetooth devices
2473currently:
2474
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002475@table @option
blueswir15824d652009-03-28 06:44:27 +00002476@item keyboard
2477Virtual wireless keyboard implementing the HIDP bluetooth profile.
2478@end table
blueswir15824d652009-03-28 06:44:27 +00002479ETEXI
2480
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002481STEXI
2482@end table
2483ETEXI
blueswir15824d652009-03-28 06:44:27 +00002484DEFHEADING()
2485
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002486#ifdef CONFIG_TPM
2487DEFHEADING(TPM device options:)
2488
2489DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05002490 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2491 " use path to provide path to a character device; default is /dev/tpm0\n"
2492 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
2493 " not provided it will be searched for in /sys/class/misc/tpm?/device\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002494 QEMU_ARCH_ALL)
2495STEXI
2496
2497The general form of a TPM device option is:
2498@table @option
2499
2500@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2501@findex -tpmdev
2502Backend type must be:
Stefan Berger4549a8b2013-02-27 12:47:53 -05002503@option{passthrough}.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002504
2505The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04002506The @code{-tpmdev} option creates the TPM backend and requires a
2507@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002508
2509Options to each backend are described below.
2510
2511Use 'help' to print all available TPM backend types.
2512@example
2513qemu -tpmdev help
2514@end example
2515
Stefan Berger92dcc232013-02-27 12:47:54 -05002516@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05002517
2518(Linux-host only) Enable access to the host's TPM using the passthrough
2519driver.
2520
2521@option{path} specifies the path to the host's TPM device, i.e., on
2522a Linux host this would be @code{/dev/tpm0}.
2523@option{path} is optional and by default @code{/dev/tpm0} is used.
2524
Stefan Berger92dcc232013-02-27 12:47:54 -05002525@option{cancel-path} specifies the path to the host TPM device's sysfs
2526entry allowing for cancellation of an ongoing TPM command.
2527@option{cancel-path} is optional and by default QEMU will search for the
2528sysfs entry to use.
2529
Stefan Berger4549a8b2013-02-27 12:47:53 -05002530Some notes about using the host's TPM with the passthrough driver:
2531
2532The TPM device accessed by the passthrough driver must not be
2533used by any other application on the host.
2534
2535Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2536the VM's firmware (BIOS/UEFI) will not be able to initialize the
2537TPM again and may therefore not show a TPM-specific menu that would
2538otherwise allow the user to configure the TPM, e.g., allow the user to
2539enable/disable or activate/deactivate the TPM.
2540Further, if TPM ownership is released from within a VM then the host's TPM
2541will get disabled and deactivated. To enable and activate the
2542TPM again afterwards, the host has to be rebooted and the user is
2543required to enter the firmware's menu to enable and activate the TPM.
2544If the TPM is left disabled and/or deactivated most TPM commands will fail.
2545
2546To create a passthrough TPM use the following two options:
2547@example
2548-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2549@end example
2550Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2551@code{tpmdev=tpm0} in the device option.
2552
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05002553@end table
2554
2555ETEXI
2556
2557DEFHEADING()
2558
2559#endif
2560
Alexander Graf7677f052009-06-28 16:55:55 +02002561DEFHEADING(Linux/Multiboot boot specific:)
blueswir15824d652009-03-28 06:44:27 +00002562STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02002563
2564When using these options, you can use a given Linux or Multiboot
2565kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00002566for easier testing of various kernels.
2567
2568@table @option
2569ETEXI
2570
2571DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00002572 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002573STEXI
2574@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002575@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02002576Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2577or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00002578ETEXI
2579
2580DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00002581 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002582STEXI
2583@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002584@findex -append
blueswir15824d652009-03-28 06:44:27 +00002585Use @var{cmdline} as kernel command line
2586ETEXI
2587
2588DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00002589 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002590STEXI
2591@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002592@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00002593Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02002594
2595@item -initrd "@var{file1} arg=foo,@var{file2}"
2596
2597This syntax is only available with multiboot.
2598
2599Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2600first module.
blueswir15824d652009-03-28 06:44:27 +00002601ETEXI
2602
Grant Likely412beee2012-03-02 11:56:38 +00002603DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10002604 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00002605STEXI
2606@item -dtb @var{file}
2607@findex -dtb
2608Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2609on boot.
2610ETEXI
2611
blueswir15824d652009-03-28 06:44:27 +00002612STEXI
2613@end table
2614ETEXI
blueswir15824d652009-03-28 06:44:27 +00002615DEFHEADING()
2616
2617DEFHEADING(Debug/Expert options:)
blueswir15824d652009-03-28 06:44:27 +00002618STEXI
2619@table @option
2620ETEXI
2621
2622DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00002623 "-serial dev redirect the serial port to char device 'dev'\n",
2624 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002625STEXI
2626@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002627@findex -serial
blueswir15824d652009-03-28 06:44:27 +00002628Redirect the virtual serial port to host character device
2629@var{dev}. The default device is @code{vc} in graphical mode and
2630@code{stdio} in non graphical mode.
2631
2632This option can be used several times to simulate up to 4 serial
2633ports.
2634
2635Use @code{-serial none} to disable all serial ports.
2636
2637Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002638@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02002639@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00002640Virtual console. Optionally, a width and height can be given in pixel with
2641@example
2642vc:800x600
2643@end example
2644It is also possible to specify width or height in characters:
2645@example
2646vc:80Cx24C
2647@end example
2648@item pty
2649[Linux only] Pseudo TTY (a new PTY is automatically allocated)
2650@item none
2651No device is allocated.
2652@item null
2653void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01002654@item chardev:@var{id}
2655Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00002656@item /dev/XXX
2657[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2658parameters are set according to the emulated ones.
2659@item /dev/parport@var{N}
2660[Linux only, parallel port only] Use host parallel port
2661@var{N}. Currently SPP and EPP parallel port features can be used.
2662@item file:@var{filename}
2663Write output to @var{filename}. No character can be read.
2664@item stdio
2665[Unix only] standard input/output
2666@item pipe:@var{filename}
2667name pipe @var{filename}
2668@item COM@var{n}
2669[Windows only] Use host serial port @var{n}
2670@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2671This implements UDP Net Console.
2672When @var{remote_host} or @var{src_ip} are not specified
2673they default to @code{0.0.0.0}.
2674When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00002675
2676If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002677@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
2678@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00002679will appear in the netconsole session.
2680
2681If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002682and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00002683source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002684udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00002685version of netcat which can listen to a TCP port and send and receive
2686characters via udp. If you have a patched version of netcat which
2687activates telnet remote echo and single char transfer, then you can
2688use the following options to step up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002689telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00002690@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02002691@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00002692-serial udp::4555@@:4556
2693@item netcat options:
2694-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2695@item telnet options:
2696localhost 5555
2697@end table
2698
Corey Minyard5dd1f022014-10-02 11:17:37 -05002699@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00002700The TCP Net Console has two modes of operation. It can send the serial
2701I/O to a location or wait for a connection from a location. By default
2702the TCP Net Console is sent to @var{host} at the @var{port}. If you use
2703the @var{server} option QEMU will wait for a client socket application
2704to connect to the port before continuing, unless the @code{nowait}
2705option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05002706algorithm. The @code{reconnect} option only applies if @var{noserver} is
2707set, if the connection goes down it will attempt to reconnect at the
2708given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00002709one TCP connection at a time is accepted. You can use @code{telnet} to
2710connect to the corresponding character device.
2711@table @code
2712@item Example to send tcp console to 192.168.0.2 port 4444
2713-serial tcp:192.168.0.2:4444
2714@item Example to listen and wait on port 4444 for connection
2715-serial tcp::4444,server
2716@item Example to not wait and listen on ip 192.168.0.100 port 4444
2717-serial tcp:192.168.0.100:4444,server,nowait
2718@end table
2719
2720@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
2721The telnet protocol is used instead of raw tcp sockets. The options
2722work the same as if you had specified @code{-serial tcp}. The
2723difference is that the port acts like a telnet server or client using
2724telnet option negotiation. This will also allow you to send the
2725MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
2726sequence. Typically in unix telnet you do it with Control-] and then
2727type "send break" followed by pressing the enter key.
2728
Corey Minyard5dd1f022014-10-02 11:17:37 -05002729@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00002730A unix domain socket is used instead of a tcp socket. The option works the
2731same as if you had specified @code{-serial tcp} except the unix domain socket
2732@var{path} is used for connections.
2733
2734@item mon:@var{dev_string}
2735This is a special option to allow the monitor to be multiplexed onto
2736another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04002737@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00002738@var{dev_string} should be any one of the serial devices specified
2739above. An example to multiplex the monitor onto a telnet server
2740listening on port 4444 would be:
2741@table @code
2742@item -serial mon:telnet::4444,server,nowait
2743@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04002744When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
2745QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00002746
2747@item braille
2748Braille device. This will use BrlAPI to display the braille output on a real
2749or fake device.
2750
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02002751@item msmouse
2752Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00002753@end table
2754ETEXI
2755
2756DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00002757 "-parallel dev redirect the parallel port to char device 'dev'\n",
2758 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002759STEXI
2760@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002761@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00002762Redirect the virtual parallel port to host device @var{dev} (same
2763devices as the serial port). On Linux hosts, @file{/dev/parportN} can
2764be used to use hardware devices connected on the corresponding host
2765parallel port.
2766
2767This option can be used several times to simulate up to 3 parallel
2768ports.
2769
2770Use @code{-parallel none} to disable all parallel ports.
2771ETEXI
2772
2773DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00002774 "-monitor dev redirect the monitor to char device 'dev'\n",
2775 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002776STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01002777@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002778@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00002779Redirect the monitor to host device @var{dev} (same devices as the
2780serial port).
2781The default device is @code{vc} in graphical mode and @code{stdio} in
2782non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04002783Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00002784ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01002785DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00002786 "-qmp dev like -monitor but opens in 'control' mode\n",
2787 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01002788STEXI
2789@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002790@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01002791Like -monitor but opens in 'control' mode.
2792ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01002793DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
2794 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
2795 QEMU_ARCH_ALL)
2796STEXI
2797@item -qmp-pretty @var{dev}
2798@findex -qmp-pretty
2799Like -qmp but uses pretty JSON formatting.
2800ETEXI
blueswir15824d652009-03-28 06:44:27 +00002801
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01002802DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Michael Tokarevf17e4ea2013-06-15 13:47:32 +04002803 "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01002804STEXI
Michael Tokarevf17e4ea2013-06-15 13:47:32 +04002805@item -mon [chardev=]name[,mode=readline|control][,default]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002806@findex -mon
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01002807Setup monitor on chardev @var{name}.
2808ETEXI
2809
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08002810DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00002811 "-debugcon dev redirect the debug console to char device 'dev'\n",
2812 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08002813STEXI
2814@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002815@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08002816Redirect the debug console to host device @var{dev} (same devices as the
2817serial port). The debug console is an I/O port which is typically port
28180xe9; writing to that I/O port sends output to this device.
2819The default device is @code{vc} in graphical mode and @code{stdio} in
2820non graphical mode.
2821ETEXI
2822
blueswir15824d652009-03-28 06:44:27 +00002823DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00002824 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002825STEXI
2826@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002827@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00002828Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
2829from a script.
2830ETEXI
2831
aurel321b530a62009-04-05 20:08:59 +00002832DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00002833 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00002834STEXI
2835@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01002836@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00002837Run the emulation in single step mode.
2838ETEXI
2839
blueswir15824d652009-03-28 06:44:27 +00002840DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00002841 "-S freeze CPU at startup (use 'c' to start execution)\n",
2842 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002843STEXI
2844@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01002845@findex -S
blueswir15824d652009-03-28 06:44:27 +00002846Do not start CPU at startup (you must type 'c' in the monitor).
2847ETEXI
2848
Satoru Moriya888a6bc2013-04-19 16:42:06 +02002849DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
2850 "-realtime [mlock=on|off]\n"
2851 " run qemu with realtime features\n"
2852 " mlock=on|off controls mlock support (default: on)\n",
2853 QEMU_ARCH_ALL)
2854STEXI
2855@item -realtime mlock=on|off
2856@findex -realtime
2857Run qemu with realtime features.
2858mlocking qemu and guest memory can be enabled via @option{mlock=on}
2859(enabled by default).
2860ETEXI
2861
aliguori59030a82009-04-05 18:43:41 +00002862DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00002863 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002864STEXI
aliguori59030a82009-04-05 18:43:41 +00002865@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002866@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00002867Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
2868connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002869stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00002870within gdb and establish the connection via a pipe:
2871@example
Stefan Weil3804da92012-05-11 22:21:50 +02002872(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00002873@end example
blueswir15824d652009-03-28 06:44:27 +00002874ETEXI
2875
aliguori59030a82009-04-05 18:43:41 +00002876DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00002877 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
2878 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002879STEXI
aliguori59030a82009-04-05 18:43:41 +00002880@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01002881@findex -s
aliguori59030a82009-04-05 18:43:41 +00002882Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
2883(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00002884ETEXI
2885
2886DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00002887 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00002888 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002889STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00002890@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002891@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00002892Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00002893ETEXI
2894
Matthew Fernandezc235d732011-06-07 16:32:40 +00002895DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00002896 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00002897 QEMU_ARCH_ALL)
2898STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02002899@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00002900@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00002901Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00002902ETEXI
2903
blueswir15824d652009-03-28 06:44:27 +00002904DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00002905 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
2906 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002907STEXI
2908@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002909@findex -L
blueswir15824d652009-03-28 06:44:27 +00002910Set the directory for the BIOS, VGA BIOS and keymaps.
2911ETEXI
2912
2913DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00002914 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002915STEXI
2916@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002917@findex -bios
blueswir15824d652009-03-28 06:44:27 +00002918Set the filename for the BIOS.
2919ETEXI
2920
blueswir15824d652009-03-28 06:44:27 +00002921DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00002922 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002923STEXI
2924@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01002925@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00002926Enable KVM full virtualization support. This option is only available
2927if KVM support is enabled when compiling.
2928ETEXI
2929
aliguorie37630c2009-04-22 15:19:10 +00002930DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00002931 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00002932DEF("xen-create", 0, QEMU_OPTION_xen_create,
2933 "-xen-create create domain using xen hypercalls, bypassing xend\n"
Blue Swirlad960902010-03-29 19:23:52 +00002934 " warning: should not be used when xend is in use\n",
2935 QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00002936DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2937 "-xen-attach attach to existing xen domain\n"
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002938 " xend will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00002939 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01002940STEXI
2941@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002942@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01002943Specify xen guest domain @var{id} (XEN only).
2944@item -xen-create
Stefan Weil6616b2a2010-02-05 23:52:05 +01002945@findex -xen-create
Stefan Weil95d5f082010-01-20 22:25:27 +01002946Create domain using xen hypercalls, bypassing xend.
2947Warning: should not be used when xend is in use (XEN only).
2948@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01002949@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01002950Attach to existing xen domain.
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002951xend will use this when starting QEMU (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01002952ETEXI
aliguorie37630c2009-04-22 15:19:10 +00002953
blueswir15824d652009-03-28 06:44:27 +00002954DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00002955 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002956STEXI
2957@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01002958@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00002959Exit instead of rebooting.
2960ETEXI
2961
2962DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00002963 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002964STEXI
2965@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01002966@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00002967Don't exit QEMU on guest shutdown, but instead only stop the emulation.
2968This allows for instance switching to monitor to commit changes to the
2969disk image.
2970ETEXI
2971
2972DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
2973 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00002974 " start right away with a saved state (loadvm in monitor)\n",
2975 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002976STEXI
2977@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002978@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00002979Start right away with a saved state (@code{loadvm} in monitor)
2980ETEXI
2981
2982#ifndef _WIN32
2983DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00002984 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002985#endif
2986STEXI
2987@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01002988@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00002989Daemonize the QEMU process after initialization. QEMU will not detach from
2990standard IO until it is ready to receive connections on any of its devices.
2991This option is a useful way for external programs to launch QEMU without having
2992to cope with initialization race conditions.
2993ETEXI
2994
2995DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00002996 "-option-rom rom load a file, rom, into the option ROM space\n",
2997 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002998STEXI
2999@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003000@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003001Load the contents of @var{file} as an option ROM.
3002This option is useful to load things like EtherBoot.
3003ETEXI
3004
Markus Armbrustere2180522014-10-06 16:19:07 +02003005HXCOMM Silently ignored for compatibility
3006DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003007
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003008HXCOMM Options deprecated by -rtc
Blue Swirlad960902010-03-29 19:23:52 +00003009DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3010DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003011
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003012DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Paolo Bonzini78808142012-03-30 10:31:21 +00003013 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003014 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3015 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003016
blueswir15824d652009-03-28 06:44:27 +00003017STEXI
3018
Jan Kiszka68752042009-09-15 13:36:04 +02003019@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003020@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003021Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3022UTC or local time, respectively. @code{localtime} is required for correct date in
3023MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3024format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3025
Michael Tokarev9d85d552014-04-07 13:34:58 +04003026By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003027RTC as accurate reference clock inside the guest, specifically if the host
3028time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003029If you want to isolate the guest time from the host, you can set @option{clock}
3030to @code{rt} instead. To even prevent it from progressing during suspension,
3031you can set it to @code{vm}.
Jan Kiszka68752042009-09-15 13:36:04 +02003032
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003033Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3034specifically with Windows' ACPI HAL. This option will try to figure out how
3035many timer interrupts were not processed by the Windows guest and will
3036re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003037ETEXI
3038
3039DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003040 "-icount [shift=N|auto][,align=on|off]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003041 " enable virtual instruction counter with 2^N clock ticks per\n" \
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003042 " instruction and enable aligning the host and virtual clocks\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003043STEXI
Sebastian Tanase1ad95802014-07-25 11:56:28 +02003044@item -icount [shift=@var{N}|auto]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003045@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003046Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003047instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003048then the virtual cpu speed will be automatically adjusted to keep virtual
3049time within a few seconds of real time.
3050
3051Note that while this option can give deterministic behavior, it does not
3052provide cycle accurate emulation. Modern CPUs contain superscalar out of
3053order cores with complex cache hierarchies. The number of instructions
3054executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003055
3056@option{align=on} will activate the delay algorithm which will try to
3057to synchronise the host clock and the virtual clock. The goal is to
3058have a guest running at the real frequency imposed by the shift option.
3059Whenever the guest clock is behind the host clock and if
3060@option{align=on} is specified then we print a messsage to the user
3061to inform about the delay.
3062Currently this option does not work when @option{shift} is @code{auto}.
3063Note: The sync algorithm will work for those shift values for which
3064the guest clock runs ahead of the host clock. Typically this happens
3065when the shift value is high (how high depends on the host machine).
blueswir15824d652009-03-28 06:44:27 +00003066ETEXI
3067
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003068DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3069 "-watchdog i6300esb|ib700\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003070 " enable virtual hardware watchdog [default=none]\n",
3071 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003072STEXI
3073@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003074@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003075Create a virtual hardware watchdog device. Once enabled (by a guest
3076action), the watchdog must be periodically polled by an agent inside
3077the guest or else the guest will be restarted.
3078
3079The @var{model} is the model of hardware watchdog to emulate. Choices
3080for model are: @code{ib700} (iBASE 700) which is a very simple ISA
3081watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
3082controller hub) which is a much more featureful PCI-based dual-timer
3083watchdog. Choose a model for which your guest has drivers.
3084
Peter Maydell585f6032012-10-04 16:22:01 +01003085Use @code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003086watchdog can be enabled for a guest.
3087ETEXI
3088
3089DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3090 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003091 " action when watchdog fires [default=reset]\n",
3092 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003093STEXI
3094@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003095@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003096
3097The @var{action} controls what QEMU will do when the watchdog timer
3098expires.
3099The default is
3100@code{reset} (forcefully reset the guest).
3101Other possible actions are:
3102@code{shutdown} (attempt to gracefully shutdown the guest),
3103@code{poweroff} (forcefully poweroff the guest),
3104@code{pause} (pause the guest),
3105@code{debug} (print a debug message and continue), or
3106@code{none} (do nothing).
3107
3108Note that the @code{shutdown} action requires that the guest responds
3109to ACPI signals, which it may not be able to do in the sort of
3110situations where the watchdog would have expired, and thus
3111@code{-watchdog-action shutdown} is not recommended for production use.
3112
3113Examples:
3114
3115@table @code
3116@item -watchdog i6300esb -watchdog-action pause
3117@item -watchdog ib700
3118@end table
3119ETEXI
3120
blueswir15824d652009-03-28 06:44:27 +00003121DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003122 "-echr chr set terminal escape character instead of ctrl-a\n",
3123 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003124STEXI
3125
Kevin Wolf4e257e52009-10-09 10:58:36 +02003126@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003127@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003128Change the escape character used for switching to the monitor when using
3129monitor and serial sharing. The default is @code{0x01} when using the
3130@code{-nographic} option. @code{0x01} is equal to pressing
3131@code{Control-a}. You can select a different character from the ascii
3132control keys where 1 through 26 map to Control-a through Control-z. For
3133instance you could use the either of the following to change the escape
3134character to Control-t.
3135@table @code
3136@item -echr 0x14
3137@item -echr 20
3138@end table
3139ETEXI
3140
3141DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3142 "-virtioconsole c\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003143 " set virtio console\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003144STEXI
3145@item -virtioconsole @var{c}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003146@findex -virtioconsole
blueswir15824d652009-03-28 06:44:27 +00003147Set virtio console.
Amit Shah98b19252010-01-20 00:36:52 +05303148
3149This option is maintained for backward compatibility.
3150
3151Please use @code{-device virtconsole} for the new way of invocation.
blueswir15824d652009-03-28 06:44:27 +00003152ETEXI
3153
3154DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003155 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003156STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003157@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003158@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003159Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003160ETEXI
3161
3162DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003163 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003164STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003165@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003166@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003167Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003168ETEXI
3169
3170DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Blue Swirlad960902010-03-29 19:23:52 +00003171 "-incoming p prepare for incoming migration, listen on port p\n",
3172 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003173STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003174@item -incoming @var{port}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003175@findex -incoming
Stefan Weil95d5f082010-01-20 22:25:27 +01003176Prepare for incoming migration, listen on @var{port}.
blueswir15824d652009-03-28 06:44:27 +00003177ETEXI
3178
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003179DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003180 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003181STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003182@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003183@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003184Don't create default devices. Normally, QEMU sets the default devices like serial
3185port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3186CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3187default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003188ETEXI
3189
blueswir15824d652009-03-28 06:44:27 +00003190#ifndef _WIN32
3191DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003192 "-chroot dir chroot to dir just before starting the VM\n",
3193 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003194#endif
3195STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003196@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003197@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003198Immediately before starting guest execution, chroot to the specified
3199directory. Especially useful in combination with -runas.
3200ETEXI
3201
3202#ifndef _WIN32
3203DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Blue Swirlad960902010-03-29 19:23:52 +00003204 "-runas user change to user id user just before starting the VM\n",
3205 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003206#endif
3207STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003208@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003209@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003210Immediately before starting guest execution, drop root privileges, switching
3211to the specified user.
3212ETEXI
3213
blueswir15824d652009-03-28 06:44:27 +00003214DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3215 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003216 " set OpenBIOS nvram variables\n",
3217 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003218STEXI
3219@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003220@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003221Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3222ETEXI
blueswir15824d652009-03-28 06:44:27 +00003223DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003224 "-semihosting semihosting mode\n",
3225 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32)
Stefan Weil95d5f082010-01-20 22:25:27 +01003226STEXI
3227@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003228@findex -semihosting
Liviu Ionescua38bb072014-12-11 12:07:48 +00003229Enable semihosting mode (ARM, M68K, Xtensa only).
3230ETEXI
3231DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
3232 "-semihosting-config [enable=on|off,]target=native|gdb|auto semihosting configuration\n",
3233QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32)
3234STEXI
3235@item -semihosting-config [enable=on|off,]target=native|gdb|auto
3236@findex -semihosting-config
3237Enable semihosting and define where the semihosting calls will be addressed,
3238to QEMU (@code{native}) or to GDB (@code{gdb}). The default is @code{auto}, which means
3239@code{gdb} during debug sessions and @code{native} otherwise (ARM, M68K, Xtensa only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003240ETEXI
blueswir15824d652009-03-28 06:44:27 +00003241DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00003242 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003243STEXI
3244@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01003245@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01003246Old param mode (ARM only).
3247ETEXI
3248
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003249DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
3250 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
3251 QEMU_ARCH_ALL)
3252STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01003253@item -sandbox @var{arg}
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03003254@findex -sandbox
3255Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
3256disable it. The default is 'off'.
3257ETEXI
3258
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003259DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00003260 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003261STEXI
3262@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003263@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003264Read device configuration from @var{file}. This approach is useful when you want to spawn
3265QEMU process with many command line options but you don't want to exceed the command line
3266character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003267ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02003268DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3269 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00003270 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003271STEXI
3272@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003273@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02003274Write device configuration to @var{file}. The @var{file} can be either filename to save
3275command line and device configuration into file or dash @code{-}) character to print the
3276output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003277ETEXI
Anthony Liguori292444c2010-01-21 10:57:58 -06003278DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3279 "-nodefconfig\n"
Blue Swirlad960902010-03-29 19:23:52 +00003280 " do not load default config files at startup\n",
3281 QEMU_ARCH_ALL)
Anthony Liguori292444c2010-01-21 10:57:58 -06003282STEXI
3283@item -nodefconfig
Stefan Weil6616b2a2010-02-05 23:52:05 +01003284@findex -nodefconfig
Eduardo Habkostf29a5612012-05-02 13:07:29 -03003285Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3286The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3287ETEXI
3288DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3289 "-no-user-config\n"
3290 " do not load user-provided config files at startup\n",
3291 QEMU_ARCH_ALL)
3292STEXI
3293@item -no-user-config
3294@findex -no-user-config
3295The @code{-no-user-config} option makes QEMU not load any of the user-provided
3296config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
3297files from @var{datadir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06003298ETEXI
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003299DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Lluís23d15e82011-08-31 20:31:31 +02003300 "-trace [events=<file>][,file=<file>]\n"
3301 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003302 QEMU_ARCH_ALL)
3303STEXI
Lluís23d15e82011-08-31 20:31:31 +02003304HXCOMM This line is not accurate, as some sub-options are backend-specific but
3305HXCOMM HX does not support conditional compilation of text.
3306@item -trace [events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003307@findex -trace
Lluíse4858972011-08-31 20:31:03 +02003308
Lluís23d15e82011-08-31 20:31:31 +02003309Specify tracing options.
3310
3311@table @option
3312@item events=@var{file}
3313Immediately enable events listed in @var{file}.
3314The file must contain one event name (as listed in the @var{trace-events} file)
3315per line.
Stefan Weilc1ba4e02011-09-05 18:13:03 +02003316This option is only available if QEMU has been compiled with
3317either @var{simple} or @var{stderr} tracing backend.
Lluís23d15e82011-08-31 20:31:31 +02003318@item file=@var{file}
3319Log output traces to @var{file}.
3320
Stefan Weilc1ba4e02011-09-05 18:13:03 +02003321This option is only available if QEMU has been compiled with
3322the @var{simple} tracing backend.
Lluís23d15e82011-08-31 20:31:31 +02003323@end table
Prerna Saxenaab6540d2010-08-09 11:48:32 +01003324ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003325
Markus Armbruster31e70d62013-02-13 19:49:37 +01003326HXCOMM Internal use
3327DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
3328DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02003329
Paul Moore0f669982012-08-03 14:39:21 -04003330#ifdef __linux__
3331DEF("enable-fips", 0, QEMU_OPTION_enablefips,
3332 "-enable-fips enable FIPS 140-2 compliance\n",
3333 QEMU_ARCH_ALL)
3334#endif
3335STEXI
3336@item -enable-fips
3337@findex -enable-fips
3338Enable FIPS 140-2 compliance mode.
3339ETEXI
3340
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003341HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003342DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03003343
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003344HXCOMM Deprecated by kvm-pit driver properties
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003345DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
Jan Kiszkac21fb4f2012-10-05 14:51:42 -03003346 "", QEMU_ARCH_I386)
3347
Jan Kiszka4086bde2012-10-05 14:51:41 -03003348HXCOMM Deprecated (ignored)
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003349DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
Jan Kiszka4086bde2012-10-05 14:51:41 -03003350
Jan Kiszkae43d5942012-10-05 14:51:40 -03003351HXCOMM Deprecated by -machine kernel_irqchip=on|off property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07003352DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
Jan Kiszkae43d5942012-10-05 14:51:40 -03003353
Jan Kiszka88eed342012-10-05 14:51:44 -03003354HXCOMM Deprecated (ignored)
3355DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
3356
Anthony Liguori68d98d32012-06-25 14:36:33 -05003357DEF("object", HAS_ARG, QEMU_OPTION_object,
3358 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3359 " create an new object of type TYPENAME setting properties\n"
3360 " in the order they are specified. Note that the 'id'\n"
3361 " property must be set. These objects are placed in the\n"
3362 " '/objects' path.\n",
3363 QEMU_ARCH_ALL)
Markus Armbruster6265c432013-02-13 19:49:39 +01003364STEXI
3365@item -object @var{typename}[,@var{prop1}=@var{value1},...]
3366@findex -object
3367Create an new object of type @var{typename} setting properties
3368in the order they are specified. Note that the 'id'
3369property must be set. These objects are placed in the
3370'/objects' path.
3371ETEXI
Anthony Liguori68d98d32012-06-25 14:36:33 -05003372
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04003373DEF("msg", HAS_ARG, QEMU_OPTION_msg,
3374 "-msg timestamp[=on|off]\n"
3375 " change the format of messages\n"
3376 " on|off controls leading timestamps (default:on)\n",
3377 QEMU_ARCH_ALL)
3378STEXI
3379@item -msg timestamp[=on|off]
3380@findex -msg
3381prepend a timestamp to each log message.(default:on)
3382ETEXI
3383
Amit Shahabfd9ce2014-06-20 18:56:08 +05303384DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
3385 "-dump-vmstate <file>\n"
3386 " Output vmstate information in JSON format to file.\n"
3387 " Use the scripts/vmstate-static-checker.py file to\n"
3388 " check for possible regressions in migration code\n"
3389 " by comparing two such vmstate dumps.",
3390 QEMU_ARCH_ALL)
3391STEXI
3392@item -dump-vmstate @var{file}
3393@findex -dump-vmstate
3394Dump json-encoded vmstate information for current machine type to file
3395in @var{file}
3396ETEXI
3397
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003398HXCOMM This is the last statement. Insert new options before this line!
3399STEXI
3400@end table
3401ETEXI