mirror: Switch mirror_do_read() to byte-based
[qemu/kevin.git] / qemu-options.hx
blobddab656eb37f7fb7104c9ffed1f0e9499d1a8013
1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
6 HXCOMM architectures.
7 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
9 DEFHEADING(Standard options)
10 STEXI
11 @table @option
12 ETEXI
14 DEF("help", 0, QEMU_OPTION_h,
15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL)
16 STEXI
17 @item -h
18 @findex -h
19 Display help and exit
20 ETEXI
22 DEF("version", 0, QEMU_OPTION_version,
23 "-version display version information and exit\n", QEMU_ARCH_ALL)
24 STEXI
25 @item -version
26 @findex -version
27 Display version information and exit
28 ETEXI
30 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31 "-machine [type=]name[,prop[=value][,...]]\n"
32 " selects emulated machine ('-machine help' for list)\n"
33 " property accel=accel1[:accel2[:...]] selects accelerator\n"
34 " supported accelerators are kvm, xen, hax or tcg (default: tcg)\n"
35 " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
36 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
37 " kvm_shadow_mem=size of KVM shadow MMU in bytes\n"
38 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
39 " mem-merge=on|off controls memory merge support (default: on)\n"
40 " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
41 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
42 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
43 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
44 " nvdimm=on|off controls NVDIMM support (default=off)\n"
45 " enforce-config-section=on|off enforce configuration section migration (default=off)\n"
46 " s390-squash-mcss=on|off controls support for squashing into default css (default=off)\n",
47 QEMU_ARCH_ALL)
48 STEXI
49 @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
50 @findex -machine
51 Select the emulated machine by @var{name}. Use @code{-machine help} to list
52 available machines. Supported machine properties are:
53 @table @option
54 @item accel=@var{accels1}[:@var{accels2}[:...]]
55 This is used to enable an accelerator. Depending on the target architecture,
56 kvm, xen, hax or tcg can be available. By default, tcg is used. If there is
57 more than one accelerator specified, the next one is used if the previous one
58 fails to initialize.
59 @item kernel_irqchip=on|off
60 Controls in-kernel irqchip support for the chosen accelerator when available.
61 @item gfx_passthru=on|off
62 Enables IGD GFX passthrough support for the chosen machine when available.
63 @item vmport=on|off|auto
64 Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
65 value based on accel. For accel=xen the default is off otherwise the default
66 is on.
67 @item kvm_shadow_mem=size
68 Defines the size of the KVM shadow MMU.
69 @item dump-guest-core=on|off
70 Include guest memory in a core dump. The default is on.
71 @item mem-merge=on|off
72 Enables or disables memory merge support. This feature, when supported by
73 the host, de-duplicates identical memory pages among VMs instances
74 (enabled by default).
75 @item aes-key-wrap=on|off
76 Enables or disables AES key wrapping support on s390-ccw hosts. This feature
77 controls whether AES wrapping keys will be created to allow
78 execution of AES cryptographic functions. The default is on.
79 @item dea-key-wrap=on|off
80 Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
81 controls whether DEA wrapping keys will be created to allow
82 execution of DEA cryptographic functions. The default is on.
83 @item nvdimm=on|off
84 Enables or disables NVDIMM support. The default is off.
85 @item s390-squash-mcss=on|off
86 Enables or disables squashing subchannels into the default css.
87 The default is off.
88 @end table
89 ETEXI
91 HXCOMM Deprecated by -machine
92 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
94 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
95 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
96 STEXI
97 @item -cpu @var{model}
98 @findex -cpu
99 Select CPU model (@code{-cpu help} for list and additional feature selection)
100 ETEXI
102 DEF("accel", HAS_ARG, QEMU_OPTION_accel,
103 "-accel [accel=]accelerator[,thread=single|multi]\n"
104 " select accelerator (kvm, xen, hax or tcg; use 'help' for a list)\n"
105 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
106 STEXI
107 @item -accel @var{name}[,prop=@var{value}[,...]]
108 @findex -accel
109 This is used to enable an accelerator. Depending on the target architecture,
110 kvm, xen, hax or tcg can be available. By default, tcg is used. If there is
111 more than one accelerator specified, the next one is used if the previous one
112 fails to initialize.
113 @table @option
114 @item thread=single|multi
115 Controls number of TCG threads. When the TCG is multi-threaded there will be one
116 thread per vCPU therefor taking advantage of additional host cores. The default
117 is to enable multi-threading where both the back-end and front-ends support it and
118 no incompatible TCG features have been enabled (e.g. icount/replay).
119 @end table
120 ETEXI
122 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
123 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
124 " set the number of CPUs to 'n' [default=1]\n"
125 " maxcpus= maximum number of total cpus, including\n"
126 " offline CPUs for hotplug, etc\n"
127 " cores= number of CPU cores on one socket\n"
128 " threads= number of threads on one CPU core\n"
129 " sockets= number of discrete sockets in the system\n",
130 QEMU_ARCH_ALL)
131 STEXI
132 @item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
133 @findex -smp
134 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
135 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
136 to 4.
137 For the PC target, the number of @var{cores} per socket, the number
138 of @var{threads} per cores and the total number of @var{sockets} can be
139 specified. Missing values will be computed. If any on the three values is
140 given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
141 specifies the maximum number of hotpluggable CPUs.
142 ETEXI
144 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
145 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
146 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
147 "-numa dist,src=source,dst=destination,val=distance\n", QEMU_ARCH_ALL)
148 STEXI
149 @item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
150 @itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
151 @itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
152 @itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
153 @findex -numa
154 Define a NUMA node and assign RAM and VCPUs to it.
155 Set the NUMA distance from a source node to a destination node.
157 Legacy VCPU assignment uses @samp{cpus} option where
158 @var{firstcpu} and @var{lastcpu} are CPU indexes. Each
159 @samp{cpus} option represent a contiguous range of CPU indexes
160 (or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
161 set of VCPUs can be represented by providing multiple @samp{cpus}
162 options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
163 split between them.
165 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
166 a NUMA node:
167 @example
168 -numa node,cpus=0-2,cpus=5
169 @end example
171 @samp{cpu} option is a new alternative to @samp{cpus} option
172 which uses @samp{socket-id|core-id|thread-id} properties to assign
173 CPU objects to a @var{node} using topology layout properties of CPU.
174 The set of properties is machine specific, and depends on used
175 machine type/@samp{smp} options. It could be queried with
176 @samp{hotpluggable-cpus} monitor command.
177 @samp{node-id} property specifies @var{node} to which CPU object
178 will be assigned, it's required for @var{node} to be declared
179 with @samp{node} option before it's used with @samp{cpu} option.
181 For example:
182 @example
183 -M pc \
184 -smp 1,sockets=2,maxcpus=2 \
185 -numa node,nodeid=0 -numa node,nodeid=1 \
186 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
187 @end example
189 @samp{mem} assigns a given RAM amount to a node. @samp{memdev}
190 assigns RAM from a given memory backend device to a node. If
191 @samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
192 split equally between them.
194 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
195 if one node uses @samp{memdev}, all of them have to use it.
197 @var{source} and @var{destination} are NUMA node IDs.
198 @var{distance} is the NUMA distance from @var{source} to @var{destination}.
199 The distance from a node to itself is always 10. If any pair of nodes is
200 given a distance, then all pairs must be given distances. Although, when
201 distances are only given in one direction for each pair of nodes, then
202 the distances in the opposite directions are assumed to be the same. If,
203 however, an asymmetrical pair of distances is given for even one node
204 pair, then all node pairs must be provided distance values for both
205 directions, even when they are symmetrical. When a node is unreachable
206 from another node, set the pair's distance to 255.
208 Note that the -@option{numa} option doesn't allocate any of the
209 specified resources, it just assigns existing resources to NUMA
210 nodes. This means that one still has to use the @option{-m},
211 @option{-smp} options to allocate RAM and VCPUs respectively.
213 ETEXI
215 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
216 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
217 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
218 STEXI
219 @item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
220 @findex -add-fd
222 Add a file descriptor to an fd set. Valid options are:
224 @table @option
225 @item fd=@var{fd}
226 This option defines the file descriptor of which a duplicate is added to fd set.
227 The file descriptor cannot be stdin, stdout, or stderr.
228 @item set=@var{set}
229 This option defines the ID of the fd set to add the file descriptor to.
230 @item opaque=@var{opaque}
231 This option defines a free-form string that can be used to describe @var{fd}.
232 @end table
234 You can open an image using pre-opened file descriptors from an fd set:
235 @example
236 qemu-system-i386
237 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
238 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
239 -drive file=/dev/fdset/2,index=0,media=disk
240 @end example
241 ETEXI
243 DEF("set", HAS_ARG, QEMU_OPTION_set,
244 "-set group.id.arg=value\n"
245 " set <arg> parameter for item <id> of type <group>\n"
246 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
247 STEXI
248 @item -set @var{group}.@var{id}.@var{arg}=@var{value}
249 @findex -set
250 Set parameter @var{arg} for item @var{id} of type @var{group}
251 ETEXI
253 DEF("global", HAS_ARG, QEMU_OPTION_global,
254 "-global driver.property=value\n"
255 "-global driver=driver,property=property,value=value\n"
256 " set a global default for a driver property\n",
257 QEMU_ARCH_ALL)
258 STEXI
259 @item -global @var{driver}.@var{prop}=@var{value}
260 @itemx -global driver=@var{driver},property=@var{property},value=@var{value}
261 @findex -global
262 Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
264 @example
265 qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
266 @end example
268 In particular, you can use this to set driver properties for devices which are
269 created automatically by the machine model. To create a device which is not
270 created automatically and set properties on it, use -@option{device}.
272 -global @var{driver}.@var{prop}=@var{value} is shorthand for -global
273 driver=@var{driver},property=@var{prop},value=@var{value}. The
274 longhand syntax works even when @var{driver} contains a dot.
275 ETEXI
277 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
278 "-boot [order=drives][,once=drives][,menu=on|off]\n"
279 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
280 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
281 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
282 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
283 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
284 QEMU_ARCH_ALL)
285 STEXI
286 @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]
287 @findex -boot
288 Specify boot order @var{drives} as a string of drive letters. Valid
289 drive letters depend on the target architecture. The x86 PC uses: a, b
290 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
291 from network adapter 1-4), hard disk boot is the default. To apply a
292 particular boot order only on the first startup, specify it via
293 @option{once}. Note that the @option{order} or @option{once} parameter
294 should not be used together with the @option{bootindex} property of
295 devices, since the firmware implementations normally do not support both
296 at the same time.
298 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
299 as firmware/BIOS supports them. The default is non-interactive boot.
301 A splash picture could be passed to bios, enabling user to show it as logo,
302 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
303 supports them. Currently Seabios for X86 system support it.
304 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
305 format(true color). The resolution should be supported by the SVGA mode, so
306 the recommended is 320x240, 640x480, 800x640.
308 A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
309 when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
310 reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
311 system support it.
313 Do strict boot via @option{strict=on} as far as firmware/BIOS
314 supports it. This only effects when boot priority is changed by
315 bootindex options. The default is non-strict boot.
317 @example
318 # try to boot from network first, then from hard disk
319 qemu-system-i386 -boot order=nc
320 # boot from CD-ROM first, switch back to default order after reboot
321 qemu-system-i386 -boot once=d
322 # boot with a splash picture for 5 seconds.
323 qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
324 @end example
326 Note: The legacy format '-boot @var{drives}' is still supported but its
327 use is discouraged as it may be removed from future versions.
328 ETEXI
330 DEF("m", HAS_ARG, QEMU_OPTION_m,
331 "-m [size=]megs[,slots=n,maxmem=size]\n"
332 " configure guest RAM\n"
333 " size: initial amount of guest memory\n"
334 " slots: number of hotplug slots (default: none)\n"
335 " maxmem: maximum amount of guest memory (default: none)\n"
336 "NOTE: Some architectures might enforce a specific granularity\n",
337 QEMU_ARCH_ALL)
338 STEXI
339 @item -m [size=]@var{megs}[,slots=n,maxmem=size]
340 @findex -m
341 Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
342 Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
343 megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
344 could be used to set amount of hotpluggable memory slots and maximum amount of
345 memory. Note that @var{maxmem} must be aligned to the page size.
347 For example, the following command-line sets the guest startup RAM size to
348 1GB, creates 3 slots to hotplug additional memory and sets the maximum
349 memory the guest can reach to 4GB:
351 @example
352 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
353 @end example
355 If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
356 be enabled and the guest startup RAM will never increase.
357 ETEXI
359 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
360 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
361 STEXI
362 @item -mem-path @var{path}
363 @findex -mem-path
364 Allocate guest RAM from a temporarily created file in @var{path}.
365 ETEXI
367 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
368 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
369 QEMU_ARCH_ALL)
370 STEXI
371 @item -mem-prealloc
372 @findex -mem-prealloc
373 Preallocate memory when using -mem-path.
374 ETEXI
376 DEF("k", HAS_ARG, QEMU_OPTION_k,
377 "-k language use keyboard layout (for example 'fr' for French)\n",
378 QEMU_ARCH_ALL)
379 STEXI
380 @item -k @var{language}
381 @findex -k
382 Use keyboard layout @var{language} (for example @code{fr} for
383 French). This option is only needed where it is not easy to get raw PC
384 keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
385 display). You don't normally need to use it on PC/Linux or PC/Windows
386 hosts.
388 The available layouts are:
389 @example
390 ar de-ch es fo fr-ca hu ja mk no pt-br sv
391 da en-gb et fr fr-ch is lt nl pl ru th
392 de en-us fi fr-be hr it lv nl-be pt sl tr
393 @end example
395 The default is @code{en-us}.
396 ETEXI
399 DEF("audio-help", 0, QEMU_OPTION_audio_help,
400 "-audio-help print list of audio drivers and their options\n",
401 QEMU_ARCH_ALL)
402 STEXI
403 @item -audio-help
404 @findex -audio-help
405 Will show the audio subsystem help: list of drivers, tunable
406 parameters.
407 ETEXI
409 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
410 "-soundhw c1,... enable audio support\n"
411 " and only specified sound cards (comma separated list)\n"
412 " use '-soundhw help' to get the list of supported cards\n"
413 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
414 STEXI
415 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
416 @findex -soundhw
417 Enable audio and selected sound hardware. Use 'help' to print all
418 available sound hardware.
420 @example
421 qemu-system-i386 -soundhw sb16,adlib disk.img
422 qemu-system-i386 -soundhw es1370 disk.img
423 qemu-system-i386 -soundhw ac97 disk.img
424 qemu-system-i386 -soundhw hda disk.img
425 qemu-system-i386 -soundhw all disk.img
426 qemu-system-i386 -soundhw help
427 @end example
429 Note that Linux's i810_audio OSS kernel (for AC97) module might
430 require manually specifying clocking.
432 @example
433 modprobe i810_audio clocking=48000
434 @end example
435 ETEXI
437 DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
438 "-balloon none disable balloon device\n"
439 "-balloon virtio[,addr=str]\n"
440 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
441 STEXI
442 @item -balloon none
443 @findex -balloon
444 Disable balloon device.
445 @item -balloon virtio[,addr=@var{addr}]
446 Enable virtio balloon device (default), optionally with PCI address
447 @var{addr}.
448 ETEXI
450 DEF("device", HAS_ARG, QEMU_OPTION_device,
451 "-device driver[,prop[=value][,...]]\n"
452 " add device (based on driver)\n"
453 " prop=value,... sets driver properties\n"
454 " use '-device help' to print all possible drivers\n"
455 " use '-device driver,help' to print all possible properties\n",
456 QEMU_ARCH_ALL)
457 STEXI
458 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
459 @findex -device
460 Add device @var{driver}. @var{prop}=@var{value} sets driver
461 properties. Valid properties depend on the driver. To get help on
462 possible drivers and properties, use @code{-device help} and
463 @code{-device @var{driver},help}.
465 Some drivers are:
466 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
468 Add an IPMI BMC. This is a simulation of a hardware management
469 interface processor that normally sits on a system. It provides
470 a watchdog and the ability to reset and power control the system.
471 You need to connect this to an IPMI interface to make it useful
473 The IPMI slave address to use for the BMC. The default is 0x20.
474 This address is the BMC's address on the I2C network of management
475 controllers. If you don't know what this means, it is safe to ignore
478 @table @option
479 @item bmc=@var{id}
480 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
481 @item slave_addr=@var{val}
482 Define slave address to use for the BMC. The default is 0x20.
483 @item sdrfile=@var{file}
484 file containing raw Sensor Data Records (SDR) data. The default is none.
485 @item fruareasize=@var{val}
486 size of a Field Replaceable Unit (FRU) area. The default is 1024.
487 @item frudatafile=@var{file}
488 file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
489 @end table
491 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
493 Add a connection to an external IPMI BMC simulator. Instead of
494 locally emulating the BMC like the above item, instead connect
495 to an external entity that provides the IPMI services.
497 A connection is made to an external BMC simulator. If you do this, it
498 is strongly recommended that you use the "reconnect=" chardev option
499 to reconnect to the simulator if the connection is lost. Note that if
500 this is not used carefully, it can be a security issue, as the
501 interface has the ability to send resets, NMIs, and power off the VM.
502 It's best if QEMU makes a connection to an external simulator running
503 on a secure port on localhost, so neither the simulator nor QEMU is
504 exposed to any outside network.
506 See the "lanserv/README.vm" file in the OpenIPMI library for more
507 details on the external interface.
509 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
511 Add a KCS IPMI interafce on the ISA bus. This also adds a
512 corresponding ACPI and SMBIOS entries, if appropriate.
514 @table @option
515 @item bmc=@var{id}
516 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
517 @item ioport=@var{val}
518 Define the I/O address of the interface. The default is 0xca0 for KCS.
519 @item irq=@var{val}
520 Define the interrupt to use. The default is 5. To disable interrupts,
521 set this to 0.
522 @end table
524 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
526 Like the KCS interface, but defines a BT interface. The default port is
527 0xe4 and the default interrupt is 5.
529 ETEXI
531 DEF("name", HAS_ARG, QEMU_OPTION_name,
532 "-name string1[,process=string2][,debug-threads=on|off]\n"
533 " set the name of the guest\n"
534 " string1 sets the window title and string2 the process name (on Linux)\n"
535 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
536 " NOTE: The thread names are for debugging and not a stable API.\n",
537 QEMU_ARCH_ALL)
538 STEXI
539 @item -name @var{name}
540 @findex -name
541 Sets the @var{name} of the guest.
542 This name will be displayed in the SDL window caption.
543 The @var{name} will also be used for the VNC server.
544 Also optionally set the top visible process name in Linux.
545 Naming of individual threads can also be enabled on Linux to aid debugging.
546 ETEXI
548 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
549 "-uuid %08x-%04x-%04x-%04x-%012x\n"
550 " specify machine UUID\n", QEMU_ARCH_ALL)
551 STEXI
552 @item -uuid @var{uuid}
553 @findex -uuid
554 Set system UUID.
555 ETEXI
557 STEXI
558 @end table
559 ETEXI
560 DEFHEADING()
562 DEFHEADING(Block device options)
563 STEXI
564 @table @option
565 ETEXI
567 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
568 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
569 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
570 STEXI
571 @item -fda @var{file}
572 @itemx -fdb @var{file}
573 @findex -fda
574 @findex -fdb
575 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
576 ETEXI
578 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
579 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
580 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
581 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
582 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
583 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
584 STEXI
585 @item -hda @var{file}
586 @itemx -hdb @var{file}
587 @itemx -hdc @var{file}
588 @itemx -hdd @var{file}
589 @findex -hda
590 @findex -hdb
591 @findex -hdc
592 @findex -hdd
593 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
594 ETEXI
596 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
597 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
598 QEMU_ARCH_ALL)
599 STEXI
600 @item -cdrom @var{file}
601 @findex -cdrom
602 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
603 @option{-cdrom} at the same time). You can use the host CD-ROM by
604 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
605 ETEXI
607 DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
608 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
609 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
610 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
611 " [,driver specific parameters...]\n"
612 " configure a block backend\n", QEMU_ARCH_ALL)
613 STEXI
614 @item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
615 @findex -blockdev
617 Define a new block driver node. Some of the options apply to all block drivers,
618 other options are only accepted for a specific block driver. See below for a
619 list of generic options and options for the most common block drivers.
621 Options that expect a reference to another node (e.g. @code{file}) can be
622 given in two ways. Either you specify the node name of an already existing node
623 (file=@var{node-name}), or you define a new node inline, adding options
624 for the referenced node after a dot (file.filename=@var{path},file.aio=native).
626 A block driver node created with @option{-blockdev} can be used for a guest
627 device by specifying its node name for the @code{drive} property in a
628 @option{-device} argument that defines a block device.
630 @table @option
631 @item Valid options for any block driver node:
633 @table @code
634 @item driver
635 Specifies the block driver to use for the given node.
636 @item node-name
637 This defines the name of the block driver node by which it will be referenced
638 later. The name must be unique, i.e. it must not match the name of a different
639 block driver node, or (if you use @option{-drive} as well) the ID of a drive.
641 If no node name is specified, it is automatically generated. The generated node
642 name is not intended to be predictable and changes between QEMU invocations.
643 For the top level, an explicit node name must be specified.
644 @item read-only
645 Open the node read-only. Guest write attempts will fail.
646 @item cache.direct
647 The host page cache can be avoided with @option{cache.direct=on}. This will
648 attempt to do disk IO directly to the guest's memory. QEMU may still perform an
649 internal copy of the data.
650 @item cache.no-flush
651 In case you don't care about data integrity over host failures, you can use
652 @option{cache.no-flush=on}. This option tells QEMU that it never needs to write
653 any data to the disk but can instead keep things in cache. If anything goes
654 wrong, like your host losing power, the disk storage getting disconnected
655 accidentally, etc. your image will most probably be rendered unusable.
656 @item discard=@var{discard}
657 @var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
658 whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
659 ignored or passed to the filesystem. Some machine types may not support
660 discard requests.
661 @item detect-zeroes=@var{detect-zeroes}
662 @var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
663 conversion of plain zero writes by the OS to driver specific optimized
664 zero write commands. You may even choose "unmap" if @var{discard} is set
665 to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
666 @end table
668 @item Driver-specific options for @code{file}
670 This is the protocol-level block driver for accessing regular files.
672 @table @code
673 @item filename
674 The path to the image file in the local filesystem
675 @item aio
676 Specifies the AIO backend (threads/native, default: threads)
677 @end table
678 Example:
679 @example
680 -blockdev driver=file,node-name=disk,filename=disk.img
681 @end example
683 @item Driver-specific options for @code{raw}
685 This is the image format block driver for raw images. It is usually
686 stacked on top of a protocol level block driver such as @code{file}.
688 @table @code
689 @item file
690 Reference to or definition of the data source block driver node
691 (e.g. a @code{file} driver node)
692 @end table
693 Example 1:
694 @example
695 -blockdev driver=file,node-name=disk_file,filename=disk.img
696 -blockdev driver=raw,node-name=disk,file=disk_file
697 @end example
698 Example 2:
699 @example
700 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
701 @end example
703 @item Driver-specific options for @code{qcow2}
705 This is the image format block driver for qcow2 images. It is usually
706 stacked on top of a protocol level block driver such as @code{file}.
708 @table @code
709 @item file
710 Reference to or definition of the data source block driver node
711 (e.g. a @code{file} driver node)
713 @item backing
714 Reference to or definition of the backing file block device (default is taken
715 from the image file). It is allowed to pass an empty string here in order to
716 disable the default backing file.
718 @item lazy-refcounts
719 Whether to enable the lazy refcounts feature (on/off; default is taken from the
720 image file)
722 @item cache-size
723 The maximum total size of the L2 table and refcount block caches in bytes
724 (default: 1048576 bytes or 8 clusters, whichever is larger)
726 @item l2-cache-size
727 The maximum size of the L2 table cache in bytes
728 (default: 4/5 of the total cache size)
730 @item refcount-cache-size
731 The maximum size of the refcount block cache in bytes
732 (default: 1/5 of the total cache size)
734 @item cache-clean-interval
735 Clean unused entries in the L2 and refcount caches. The interval is in seconds.
736 The default value is 0 and it disables this feature.
738 @item pass-discard-request
739 Whether discard requests to the qcow2 device should be forwarded to the data
740 source (on/off; default: on if discard=unmap is specified, off otherwise)
742 @item pass-discard-snapshot
743 Whether discard requests for the data source should be issued when a snapshot
744 operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
745 default: on)
747 @item pass-discard-other
748 Whether discard requests for the data source should be issued on other
749 occasions where a cluster gets freed (on/off; default: off)
751 @item overlap-check
752 Which overlap checks to perform for writes to the image
753 (none/constant/cached/all; default: cached). For details or finer
754 granularity control refer to the QAPI documentation of @code{blockdev-add}.
755 @end table
757 Example 1:
758 @example
759 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
760 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
761 @end example
762 Example 2:
763 @example
764 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
765 @end example
767 @item Driver-specific options for other drivers
768 Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
770 @end table
772 ETEXI
774 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
775 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
776 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
777 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
778 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
779 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
780 " [,readonly=on|off][,copy-on-read=on|off]\n"
781 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
782 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
783 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
784 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
785 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
786 " [[,iops_size=is]]\n"
787 " [[,group=g]]\n"
788 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
789 STEXI
790 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
791 @findex -drive
793 Define a new drive. This includes creating a block driver node (the backend) as
794 well as a guest device, and is mostly a shortcut for defining the corresponding
795 @option{-blockdev} and @option{-device} options.
797 @option{-drive} accepts all options that are accepted by @option{-blockdev}. In
798 addition, it knows the following options:
800 @table @option
801 @item file=@var{file}
802 This option defines which disk image (@pxref{disk_images}) to use with
803 this drive. If the filename contains comma, you must double it
804 (for instance, "file=my,,file" to use file "my,file").
806 Special files such as iSCSI devices can be specified using protocol
807 specific URLs. See the section for "Device URL Syntax" for more information.
808 @item if=@var{interface}
809 This option defines on which type on interface the drive is connected.
810 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
811 @item bus=@var{bus},unit=@var{unit}
812 These options define where is connected the drive by defining the bus number and
813 the unit id.
814 @item index=@var{index}
815 This option defines where is connected the drive by using an index in the list
816 of available connectors of a given interface type.
817 @item media=@var{media}
818 This option defines the type of the media: disk or cdrom.
819 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
820 These options have the same definition as they have in @option{-hdachs}.
821 These parameters are deprecated, use the corresponding parameters
822 of @code{-device} instead.
823 @item snapshot=@var{snapshot}
824 @var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
825 (see @option{-snapshot}).
826 @item cache=@var{cache}
827 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
828 and controls how the host cache is used to access block data. This is a
829 shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
830 options (as in @option{-blockdev}), and additionally @option{cache.writeback},
831 which provides a default for the @option{write-cache} option of block guest
832 devices (as in @option{-device}). The modes correspond to the following
833 settings:
835 @c Our texi2pod.pl script doesn't support @multitable, so fall back to using
836 @c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
837 @c and the HTML output.
838 @example
839 @ │ cache.writeback cache.direct cache.no-flush
840 ─────────────┼─────────────────────────────────────────────────
841 writeback │ on off off
842 none │ on on off
843 writethrough │ off off off
844 directsync │ off on off
845 unsafe │ on off on
846 @end example
848 The default mode is @option{cache=writeback}.
850 @item aio=@var{aio}
851 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
852 @item format=@var{format}
853 Specify which disk @var{format} will be used rather than detecting
854 the format. Can be used to specify format=raw to avoid interpreting
855 an untrusted format header.
856 @item serial=@var{serial}
857 This option specifies the serial number to assign to the device. This
858 parameter is deprecated, use the corresponding parameter of @code{-device}
859 instead.
860 @item addr=@var{addr}
861 Specify the controller's PCI address (if=virtio only). This parameter is
862 deprecated, use the corresponding parameter of @code{-device} instead.
863 @item werror=@var{action},rerror=@var{action}
864 Specify which @var{action} to take on write and read errors. Valid actions are:
865 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
866 "report" (report the error to the guest), "enospc" (pause QEMU only if the
867 host disk is full; report the error to the guest otherwise).
868 The default setting is @option{werror=enospc} and @option{rerror=report}.
869 @item copy-on-read=@var{copy-on-read}
870 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
871 file sectors into the image file.
872 @item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
873 Specify bandwidth throttling limits in bytes per second, either for all request
874 types or for reads or writes only. Small values can lead to timeouts or hangs
875 inside the guest. A safe minimum for disks is 2 MB/s.
876 @item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
877 Specify bursts in bytes per second, either for all request types or for reads
878 or writes only. Bursts allow the guest I/O to spike above the limit
879 temporarily.
880 @item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
881 Specify request rate limits in requests per second, either for all request
882 types or for reads or writes only.
883 @item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
884 Specify bursts in requests per second, either for all request types or for reads
885 or writes only. Bursts allow the guest I/O to spike above the limit
886 temporarily.
887 @item iops_size=@var{is}
888 Let every @var{is} bytes of a request count as a new request for iops
889 throttling purposes. Use this option to prevent guests from circumventing iops
890 limits by sending fewer but larger requests.
891 @item group=@var{g}
892 Join a throttling quota group with given name @var{g}. All drives that are
893 members of the same group are accounted for together. Use this option to
894 prevent guests from circumventing throttling limits by using many small disks
895 instead of a single larger disk.
896 @end table
898 By default, the @option{cache.writeback=on} mode is used. It will report data
899 writes as completed as soon as the data is present in the host page cache.
900 This is safe as long as your guest OS makes sure to correctly flush disk caches
901 where needed. If your guest OS does not handle volatile disk write caches
902 correctly and your host crashes or loses power, then the guest may experience
903 data corruption.
905 For such guests, you should consider using @option{cache.writeback=off}. This
906 means that the host page cache will be used to read and write data, but write
907 notification will be sent to the guest only after QEMU has made sure to flush
908 each write to the disk. Be aware that this has a major impact on performance.
910 When using the @option{-snapshot} option, unsafe caching is always used.
912 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
913 useful when the backing file is over a slow network. By default copy-on-read
914 is off.
916 Instead of @option{-cdrom} you can use:
917 @example
918 qemu-system-i386 -drive file=file,index=2,media=cdrom
919 @end example
921 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
922 use:
923 @example
924 qemu-system-i386 -drive file=file,index=0,media=disk
925 qemu-system-i386 -drive file=file,index=1,media=disk
926 qemu-system-i386 -drive file=file,index=2,media=disk
927 qemu-system-i386 -drive file=file,index=3,media=disk
928 @end example
930 You can open an image using pre-opened file descriptors from an fd set:
931 @example
932 qemu-system-i386
933 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
934 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
935 -drive file=/dev/fdset/2,index=0,media=disk
936 @end example
938 You can connect a CDROM to the slave of ide0:
939 @example
940 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
941 @end example
943 If you don't specify the "file=" argument, you define an empty drive:
944 @example
945 qemu-system-i386 -drive if=ide,index=1,media=cdrom
946 @end example
948 Instead of @option{-fda}, @option{-fdb}, you can use:
949 @example
950 qemu-system-i386 -drive file=file,index=0,if=floppy
951 qemu-system-i386 -drive file=file,index=1,if=floppy
952 @end example
954 By default, @var{interface} is "ide" and @var{index} is automatically
955 incremented:
956 @example
957 qemu-system-i386 -drive file=a -drive file=b"
958 @end example
959 is interpreted like:
960 @example
961 qemu-system-i386 -hda a -hdb b
962 @end example
963 ETEXI
965 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
966 "-mtdblock file use 'file' as on-board Flash memory image\n",
967 QEMU_ARCH_ALL)
968 STEXI
969 @item -mtdblock @var{file}
970 @findex -mtdblock
971 Use @var{file} as on-board Flash memory image.
972 ETEXI
974 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
975 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
976 STEXI
977 @item -sd @var{file}
978 @findex -sd
979 Use @var{file} as SecureDigital card image.
980 ETEXI
982 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
983 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
984 STEXI
985 @item -pflash @var{file}
986 @findex -pflash
987 Use @var{file} as a parallel flash image.
988 ETEXI
990 DEF("snapshot", 0, QEMU_OPTION_snapshot,
991 "-snapshot write to temporary files instead of disk image files\n",
992 QEMU_ARCH_ALL)
993 STEXI
994 @item -snapshot
995 @findex -snapshot
996 Write to temporary files instead of disk image files. In this case,
997 the raw disk image you use is not written back. You can however force
998 the write back by pressing @key{C-a s} (@pxref{disk_images}).
999 ETEXI
1001 DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
1002 "-hdachs c,h,s[,t]\n" \
1003 " force hard disk 0 physical geometry and the optional BIOS\n" \
1004 " translation (t=none or lba) (usually QEMU can guess them)\n",
1005 QEMU_ARCH_ALL)
1006 STEXI
1007 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
1008 @findex -hdachs
1009 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
1010 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
1011 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
1012 all those parameters. This option is deprecated, please use
1013 @code{-device ide-hd,cyls=c,heads=h,secs=s,...} instead.
1014 ETEXI
1016 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
1017 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
1018 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
1019 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1020 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1021 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1022 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1023 " [[,throttling.iops-size=is]]\n",
1024 QEMU_ARCH_ALL)
1026 STEXI
1028 @item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}]
1029 @findex -fsdev
1030 Define a new file system device. Valid options are:
1031 @table @option
1032 @item @var{fsdriver}
1033 This option specifies the fs driver backend to use.
1034 Currently "local", "handle" and "proxy" file system drivers are supported.
1035 @item id=@var{id}
1036 Specifies identifier for this device
1037 @item path=@var{path}
1038 Specifies the export path for the file system device. Files under
1039 this path will be available to the 9p client on the guest.
1040 @item security_model=@var{security_model}
1041 Specifies the security model to be used for this export path.
1042 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
1043 In "passthrough" security model, files are stored using the same
1044 credentials as they are created on the guest. This requires QEMU
1045 to run as root. In "mapped-xattr" security model, some of the file
1046 attributes like uid, gid, mode bits and link target are stored as
1047 file attributes. For "mapped-file" these attributes are stored in the
1048 hidden .virtfs_metadata directory. Directories exported by this security model cannot
1049 interact with other unix tools. "none" security model is same as
1050 passthrough except the sever won't report failures if it fails to
1051 set file attributes like ownership. Security model is mandatory
1052 only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
1053 security model as a parameter.
1054 @item writeout=@var{writeout}
1055 This is an optional argument. The only supported value is "immediate".
1056 This means that host page cache will be used to read and write data but
1057 write notification will be sent to the guest only when the data has been
1058 reported as written by the storage subsystem.
1059 @item readonly
1060 Enables exporting 9p share as a readonly mount for guests. By default
1061 read-write access is given.
1062 @item socket=@var{socket}
1063 Enables proxy filesystem driver to use passed socket file for communicating
1064 with virtfs-proxy-helper
1065 @item sock_fd=@var{sock_fd}
1066 Enables proxy filesystem driver to use passed socket descriptor for
1067 communicating with virtfs-proxy-helper. Usually a helper like libvirt
1068 will create socketpair and pass one of the fds as sock_fd
1069 @item fmode=@var{fmode}
1070 Specifies the default mode for newly created files on the host. Works only
1071 with security models "mapped-xattr" and "mapped-file".
1072 @item dmode=@var{dmode}
1073 Specifies the default mode for newly created directories on the host. Works
1074 only with security models "mapped-xattr" and "mapped-file".
1075 @end table
1077 -fsdev option is used along with -device driver "virtio-9p-pci".
1078 @item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1079 Options for virtio-9p-pci driver are:
1080 @table @option
1081 @item fsdev=@var{id}
1082 Specifies the id value specified along with -fsdev option
1083 @item mount_tag=@var{mount_tag}
1084 Specifies the tag name to be used by the guest to mount this export point
1085 @end table
1087 ETEXI
1089 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
1090 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
1091 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
1092 QEMU_ARCH_ALL)
1094 STEXI
1096 @item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}][,fmode=@var{fmode}][,dmode=@var{dmode}]
1097 @findex -virtfs
1099 The general form of a Virtual File system pass-through options are:
1100 @table @option
1101 @item @var{fsdriver}
1102 This option specifies the fs driver backend to use.
1103 Currently "local", "handle" and "proxy" file system drivers are supported.
1104 @item id=@var{id}
1105 Specifies identifier for this device
1106 @item path=@var{path}
1107 Specifies the export path for the file system device. Files under
1108 this path will be available to the 9p client on the guest.
1109 @item security_model=@var{security_model}
1110 Specifies the security model to be used for this export path.
1111 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
1112 In "passthrough" security model, files are stored using the same
1113 credentials as they are created on the guest. This requires QEMU
1114 to run as root. In "mapped-xattr" security model, some of the file
1115 attributes like uid, gid, mode bits and link target are stored as
1116 file attributes. For "mapped-file" these attributes are stored in the
1117 hidden .virtfs_metadata directory. Directories exported by this security model cannot
1118 interact with other unix tools. "none" security model is same as
1119 passthrough except the sever won't report failures if it fails to
1120 set file attributes like ownership. Security model is mandatory only
1121 for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
1122 model as a parameter.
1123 @item writeout=@var{writeout}
1124 This is an optional argument. The only supported value is "immediate".
1125 This means that host page cache will be used to read and write data but
1126 write notification will be sent to the guest only when the data has been
1127 reported as written by the storage subsystem.
1128 @item readonly
1129 Enables exporting 9p share as a readonly mount for guests. By default
1130 read-write access is given.
1131 @item socket=@var{socket}
1132 Enables proxy filesystem driver to use passed socket file for
1133 communicating with virtfs-proxy-helper. Usually a helper like libvirt
1134 will create socketpair and pass one of the fds as sock_fd
1135 @item sock_fd
1136 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1137 descriptor for interfacing with virtfs-proxy-helper
1138 @item fmode=@var{fmode}
1139 Specifies the default mode for newly created files on the host. Works only
1140 with security models "mapped-xattr" and "mapped-file".
1141 @item dmode=@var{dmode}
1142 Specifies the default mode for newly created directories on the host. Works
1143 only with security models "mapped-xattr" and "mapped-file".
1144 @end table
1145 ETEXI
1147 DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1148 "-virtfs_synth Create synthetic file system image\n",
1149 QEMU_ARCH_ALL)
1150 STEXI
1151 @item -virtfs_synth
1152 @findex -virtfs_synth
1153 Create synthetic file system image
1154 ETEXI
1156 STEXI
1157 @end table
1158 ETEXI
1159 DEFHEADING()
1161 DEFHEADING(USB options)
1162 STEXI
1163 @table @option
1164 ETEXI
1166 DEF("usb", 0, QEMU_OPTION_usb,
1167 "-usb enable the USB driver (if it is not used by default yet)\n",
1168 QEMU_ARCH_ALL)
1169 STEXI
1170 @item -usb
1171 @findex -usb
1172 Enable the USB driver (if it is not used by default yet).
1173 ETEXI
1175 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1176 "-usbdevice name add the host or guest USB device 'name'\n",
1177 QEMU_ARCH_ALL)
1178 STEXI
1180 @item -usbdevice @var{devname}
1181 @findex -usbdevice
1182 Add the USB device @var{devname}. Note that this option is deprecated,
1183 please use @code{-device usb-...} instead. @xref{usb_devices}.
1185 @table @option
1187 @item mouse
1188 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1190 @item tablet
1191 Pointer device that uses absolute coordinates (like a touchscreen). This
1192 means QEMU is able to report the mouse position without having to grab the
1193 mouse. Also overrides the PS/2 mouse emulation when activated.
1195 @item disk:[format=@var{format}]:@var{file}
1196 Mass storage device based on file. The optional @var{format} argument
1197 will be used rather than detecting the format. Can be used to specify
1198 @code{format=raw} to avoid interpreting an untrusted format header.
1200 @item host:@var{bus}.@var{addr}
1201 Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
1203 @item host:@var{vendor_id}:@var{product_id}
1204 Pass through the host device identified by @var{vendor_id}:@var{product_id}
1205 (Linux only).
1207 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
1208 Serial converter to host character device @var{dev}, see @code{-serial} for the
1209 available devices.
1211 @item braille
1212 Braille device. This will use BrlAPI to display the braille output on a real
1213 or fake device.
1215 @item net:@var{options}
1216 Network adapter that supports CDC ethernet and RNDIS protocols.
1218 @end table
1219 ETEXI
1221 STEXI
1222 @end table
1223 ETEXI
1224 DEFHEADING()
1226 DEFHEADING(Display options)
1227 STEXI
1228 @table @option
1229 ETEXI
1231 DEF("display", HAS_ARG, QEMU_OPTION_display,
1232 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
1233 " [,window_close=on|off][,gl=on|off]\n"
1234 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1235 "-display vnc=<display>[,<optargs>]\n"
1236 "-display curses\n"
1237 "-display none"
1238 " select display type\n"
1239 "The default display is equivalent to\n"
1240 #if defined(CONFIG_GTK)
1241 "\t\"-display gtk\"\n"
1242 #elif defined(CONFIG_SDL)
1243 "\t\"-display sdl\"\n"
1244 #elif defined(CONFIG_COCOA)
1245 "\t\"-display cocoa\"\n"
1246 #elif defined(CONFIG_VNC)
1247 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1248 #else
1249 "\t\"-display none\"\n"
1250 #endif
1251 , QEMU_ARCH_ALL)
1252 STEXI
1253 @item -display @var{type}
1254 @findex -display
1255 Select type of display to use. This option is a replacement for the
1256 old style -sdl/-curses/... options. Valid values for @var{type} are
1257 @table @option
1258 @item sdl
1259 Display video output via SDL (usually in a separate graphics
1260 window; see the SDL documentation for other possibilities).
1261 @item curses
1262 Display video output via curses. For graphics device models which
1263 support a text mode, QEMU can display this output using a
1264 curses/ncurses interface. Nothing is displayed when the graphics
1265 device is in graphical mode or if the graphics device does not support
1266 a text mode. Generally only the VGA device models support text mode.
1267 @item none
1268 Do not display video output. The guest will still see an emulated
1269 graphics card, but its output will not be displayed to the QEMU
1270 user. This option differs from the -nographic option in that it
1271 only affects what is done with video output; -nographic also changes
1272 the destination of the serial and parallel port data.
1273 @item gtk
1274 Display video output in a GTK window. This interface provides drop-down
1275 menus and other UI elements to configure and control the VM during
1276 runtime.
1277 @item vnc
1278 Start a VNC server on display <arg>
1279 @end table
1280 ETEXI
1282 DEF("nographic", 0, QEMU_OPTION_nographic,
1283 "-nographic disable graphical output and redirect serial I/Os to console\n",
1284 QEMU_ARCH_ALL)
1285 STEXI
1286 @item -nographic
1287 @findex -nographic
1288 Normally, if QEMU is compiled with graphical window support, it displays
1289 output such as guest graphics, guest console, and the QEMU monitor in a
1290 window. With this option, you can totally disable graphical output so
1291 that QEMU is a simple command line application. The emulated serial port
1292 is redirected on the console and muxed with the monitor (unless
1293 redirected elsewhere explicitly). Therefore, you can still use QEMU to
1294 debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1295 switching between the console and monitor.
1296 ETEXI
1298 DEF("curses", 0, QEMU_OPTION_curses,
1299 "-curses shorthand for -display curses\n",
1300 QEMU_ARCH_ALL)
1301 STEXI
1302 @item -curses
1303 @findex -curses
1304 Normally, if QEMU is compiled with graphical window support, it displays
1305 output such as guest graphics, guest console, and the QEMU monitor in a
1306 window. With this option, QEMU can display the VGA output when in text
1307 mode using a curses/ncurses interface. Nothing is displayed in graphical
1308 mode.
1309 ETEXI
1311 DEF("no-frame", 0, QEMU_OPTION_no_frame,
1312 "-no-frame open SDL window without a frame and window decorations\n",
1313 QEMU_ARCH_ALL)
1314 STEXI
1315 @item -no-frame
1316 @findex -no-frame
1317 Do not use decorations for SDL windows and start them using the whole
1318 available screen space. This makes the using QEMU in a dedicated desktop
1319 workspace more convenient.
1320 ETEXI
1322 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
1323 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1324 QEMU_ARCH_ALL)
1325 STEXI
1326 @item -alt-grab
1327 @findex -alt-grab
1328 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1329 affects the special keys (for fullscreen, monitor-mode switching, etc).
1330 ETEXI
1332 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
1333 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1334 QEMU_ARCH_ALL)
1335 STEXI
1336 @item -ctrl-grab
1337 @findex -ctrl-grab
1338 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1339 affects the special keys (for fullscreen, monitor-mode switching, etc).
1340 ETEXI
1342 DEF("no-quit", 0, QEMU_OPTION_no_quit,
1343 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
1344 STEXI
1345 @item -no-quit
1346 @findex -no-quit
1347 Disable SDL window close capability.
1348 ETEXI
1350 DEF("sdl", 0, QEMU_OPTION_sdl,
1351 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
1352 STEXI
1353 @item -sdl
1354 @findex -sdl
1355 Enable SDL.
1356 ETEXI
1358 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
1359 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1360 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1361 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
1362 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
1363 " [,tls-ciphers=<list>]\n"
1364 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1365 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1366 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1367 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1368 " [,jpeg-wan-compression=[auto|never|always]]\n"
1369 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1370 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
1371 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1372 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
1373 " [,gl=[on|off]][,rendernode=<file>]\n"
1374 " enable spice\n"
1375 " at least one of {port, tls-port} is mandatory\n",
1376 QEMU_ARCH_ALL)
1377 STEXI
1378 @item -spice @var{option}[,@var{option}[,...]]
1379 @findex -spice
1380 Enable the spice remote desktop protocol. Valid options are
1382 @table @option
1384 @item port=<nr>
1385 Set the TCP port spice is listening on for plaintext channels.
1387 @item addr=<addr>
1388 Set the IP address spice is listening on. Default is any address.
1390 @item ipv4
1391 @itemx ipv6
1392 @itemx unix
1393 Force using the specified IP version.
1395 @item password=<secret>
1396 Set the password you need to authenticate.
1398 @item sasl
1399 Require that the client use SASL to authenticate with the spice.
1400 The exact choice of authentication method used is controlled from the
1401 system / user's SASL configuration file for the 'qemu' service. This
1402 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1403 unprivileged user, an environment variable SASL_CONF_PATH can be used
1404 to make it search alternate locations for the service config.
1405 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1406 it is recommended that SASL always be combined with the 'tls' and
1407 'x509' settings to enable use of SSL and server certificates. This
1408 ensures a data encryption preventing compromise of authentication
1409 credentials.
1411 @item disable-ticketing
1412 Allow client connects without authentication.
1414 @item disable-copy-paste
1415 Disable copy paste between the client and the guest.
1417 @item disable-agent-file-xfer
1418 Disable spice-vdagent based file-xfer between the client and the guest.
1420 @item tls-port=<nr>
1421 Set the TCP port spice is listening on for encrypted channels.
1423 @item x509-dir=<dir>
1424 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1426 @item x509-key-file=<file>
1427 @itemx x509-key-password=<file>
1428 @itemx x509-cert-file=<file>
1429 @itemx x509-cacert-file=<file>
1430 @itemx x509-dh-key-file=<file>
1431 The x509 file names can also be configured individually.
1433 @item tls-ciphers=<list>
1434 Specify which ciphers to use.
1436 @item tls-channel=[main|display|cursor|inputs|record|playback]
1437 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
1438 Force specific channel to be used with or without TLS encryption. The
1439 options can be specified multiple times to configure multiple
1440 channels. The special name "default" can be used to set the default
1441 mode. For channels which are not explicitly forced into one mode the
1442 spice client is allowed to pick tls/plaintext as he pleases.
1444 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1445 Configure image compression (lossless).
1446 Default is auto_glz.
1448 @item jpeg-wan-compression=[auto|never|always]
1449 @itemx zlib-glz-wan-compression=[auto|never|always]
1450 Configure wan image compression (lossy for slow links).
1451 Default is auto.
1453 @item streaming-video=[off|all|filter]
1454 Configure video stream detection. Default is off.
1456 @item agent-mouse=[on|off]
1457 Enable/disable passing mouse events via vdagent. Default is on.
1459 @item playback-compression=[on|off]
1460 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1462 @item seamless-migration=[on|off]
1463 Enable/disable spice seamless migration. Default is off.
1465 @item gl=[on|off]
1466 Enable/disable OpenGL context. Default is off.
1468 @item rendernode=<file>
1469 DRM render node for OpenGL rendering. If not specified, it will pick
1470 the first available. (Since 2.9)
1472 @end table
1473 ETEXI
1475 DEF("portrait", 0, QEMU_OPTION_portrait,
1476 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1477 QEMU_ARCH_ALL)
1478 STEXI
1479 @item -portrait
1480 @findex -portrait
1481 Rotate graphical output 90 deg left (only PXA LCD).
1482 ETEXI
1484 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1485 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1486 QEMU_ARCH_ALL)
1487 STEXI
1488 @item -rotate @var{deg}
1489 @findex -rotate
1490 Rotate graphical output some deg left (only PXA LCD).
1491 ETEXI
1493 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
1494 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
1495 " select video card type\n", QEMU_ARCH_ALL)
1496 STEXI
1497 @item -vga @var{type}
1498 @findex -vga
1499 Select type of VGA card to emulate. Valid values for @var{type} are
1500 @table @option
1501 @item cirrus
1502 Cirrus Logic GD5446 Video card. All Windows versions starting from
1503 Windows 95 should recognize and use this graphic card. For optimal
1504 performances, use 16 bit color depth in the guest and the host OS.
1505 (This card was the default before QEMU 2.2)
1506 @item std
1507 Standard VGA card with Bochs VBE extensions. If your guest OS
1508 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1509 to use high resolution modes (>= 1280x1024x16) then you should use
1510 this option. (This card is the default since QEMU 2.2)
1511 @item vmware
1512 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1513 recent XFree86/XOrg server or Windows guest with a driver for this
1514 card.
1515 @item qxl
1516 QXL paravirtual graphic card. It is VGA compatible (including VESA
1517 2.0 VBE support). Works best with qxl guest drivers installed though.
1518 Recommended choice when using the spice protocol.
1519 @item tcx
1520 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1521 sun4m machines and offers both 8-bit and 24-bit colour depths at a
1522 fixed resolution of 1024x768.
1523 @item cg3
1524 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1525 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1526 resolutions aimed at people wishing to run older Solaris versions.
1527 @item virtio
1528 Virtio VGA card.
1529 @item none
1530 Disable VGA card.
1531 @end table
1532 ETEXI
1534 DEF("full-screen", 0, QEMU_OPTION_full_screen,
1535 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
1536 STEXI
1537 @item -full-screen
1538 @findex -full-screen
1539 Start in full screen.
1540 ETEXI
1542 DEF("g", 1, QEMU_OPTION_g ,
1543 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1544 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
1545 STEXI
1546 @item -g @var{width}x@var{height}[x@var{depth}]
1547 @findex -g
1548 Set the initial graphical resolution and depth (PPC, SPARC only).
1549 ETEXI
1551 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1552 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
1553 STEXI
1554 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1555 @findex -vnc
1556 Normally, if QEMU is compiled with graphical window support, it displays
1557 output such as guest graphics, guest console, and the QEMU monitor in a
1558 window. With this option, you can have QEMU listen on VNC display
1559 @var{display} and redirect the VGA display over the VNC session. It is
1560 very useful to enable the usb tablet device when using this option
1561 (option @option{-device usb-tablet}). When using the VNC display, you
1562 must use the @option{-k} parameter to set the keyboard layout if you are
1563 not using en-us. Valid syntax for the @var{display} is
1565 @table @option
1567 @item to=@var{L}
1569 With this option, QEMU will try next available VNC @var{display}s, until the
1570 number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1571 available, e.g. port 5900+@var{display} is already used by another
1572 application. By default, to=0.
1574 @item @var{host}:@var{d}
1576 TCP connections will only be allowed from @var{host} on display @var{d}.
1577 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1578 be omitted in which case the server will accept connections from any host.
1580 @item unix:@var{path}
1582 Connections will be allowed over UNIX domain sockets where @var{path} is the
1583 location of a unix socket to listen for connections on.
1585 @item none
1587 VNC is initialized but not started. The monitor @code{change} command
1588 can be used to later start the VNC server.
1590 @end table
1592 Following the @var{display} value there may be one or more @var{option} flags
1593 separated by commas. Valid options are
1595 @table @option
1597 @item reverse
1599 Connect to a listening VNC client via a ``reverse'' connection. The
1600 client is specified by the @var{display}. For reverse network
1601 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1602 is a TCP port number, not a display number.
1604 @item websocket
1606 Opens an additional TCP listening port dedicated to VNC Websocket connections.
1607 If a bare @var{websocket} option is given, the Websocket port is
1608 5700+@var{display}. An alternative port can be specified with the
1609 syntax @code{websocket}=@var{port}.
1611 If @var{host} is specified connections will only be allowed from this host.
1612 It is possible to control the websocket listen address independently, using
1613 the syntax @code{websocket}=@var{host}:@var{port}.
1615 If no TLS credentials are provided, the websocket connection runs in
1616 unencrypted mode. If TLS credentials are provided, the websocket connection
1617 requires encrypted client connections.
1619 @item password
1621 Require that password based authentication is used for client connections.
1623 The password must be set separately using the @code{set_password} command in
1624 the @ref{pcsys_monitor}. The syntax to change your password is:
1625 @code{set_password <protocol> <password>} where <protocol> could be either
1626 "vnc" or "spice".
1628 If you would like to change <protocol> password expiration, you should use
1629 @code{expire_password <protocol> <expiration-time>} where expiration time could
1630 be one of the following options: now, never, +seconds or UNIX time of
1631 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1632 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1633 date and time).
1635 You can also use keywords "now" or "never" for the expiration time to
1636 allow <protocol> password to expire immediately or never expire.
1638 @item tls-creds=@var{ID}
1640 Provides the ID of a set of TLS credentials to use to secure the
1641 VNC server. They will apply to both the normal VNC server socket
1642 and the websocket socket (if enabled). Setting TLS credentials
1643 will cause the VNC server socket to enable the VeNCrypt auth
1644 mechanism. The credentials should have been previously created
1645 using the @option{-object tls-creds} argument.
1647 The @option{tls-creds} parameter obsoletes the @option{tls},
1648 @option{x509}, and @option{x509verify} options, and as such
1649 it is not permitted to set both new and old type options at
1650 the same time.
1652 @item tls
1654 Require that client use TLS when communicating with the VNC server. This
1655 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1656 attack. It is recommended that this option be combined with either the
1657 @option{x509} or @option{x509verify} options.
1659 This option is now deprecated in favor of using the @option{tls-creds}
1660 argument.
1662 @item x509=@var{/path/to/certificate/dir}
1664 Valid if @option{tls} is specified. Require that x509 credentials are used
1665 for negotiating the TLS session. The server will send its x509 certificate
1666 to the client. It is recommended that a password be set on the VNC server
1667 to provide authentication of the client when this is used. The path following
1668 this option specifies where the x509 certificates are to be loaded from.
1669 See the @ref{vnc_security} section for details on generating certificates.
1671 This option is now deprecated in favour of using the @option{tls-creds}
1672 argument.
1674 @item x509verify=@var{/path/to/certificate/dir}
1676 Valid if @option{tls} is specified. Require that x509 credentials are used
1677 for negotiating the TLS session. The server will send its x509 certificate
1678 to the client, and request that the client send its own x509 certificate.
1679 The server will validate the client's certificate against the CA certificate,
1680 and reject clients when validation fails. If the certificate authority is
1681 trusted, this is a sufficient authentication mechanism. You may still wish
1682 to set a password on the VNC server as a second authentication layer. The
1683 path following this option specifies where the x509 certificates are to
1684 be loaded from. See the @ref{vnc_security} section for details on generating
1685 certificates.
1687 This option is now deprecated in favour of using the @option{tls-creds}
1688 argument.
1690 @item sasl
1692 Require that the client use SASL to authenticate with the VNC server.
1693 The exact choice of authentication method used is controlled from the
1694 system / user's SASL configuration file for the 'qemu' service. This
1695 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1696 unprivileged user, an environment variable SASL_CONF_PATH can be used
1697 to make it search alternate locations for the service config.
1698 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1699 it is recommended that SASL always be combined with the 'tls' and
1700 'x509' settings to enable use of SSL and server certificates. This
1701 ensures a data encryption preventing compromise of authentication
1702 credentials. See the @ref{vnc_security} section for details on using
1703 SASL authentication.
1705 @item acl
1707 Turn on access control lists for checking of the x509 client certificate
1708 and SASL party. For x509 certs, the ACL check is made against the
1709 certificate's distinguished name. This is something that looks like
1710 @code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1711 made against the username, which depending on the SASL plugin, may
1712 include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1713 When the @option{acl} flag is set, the initial access list will be
1714 empty, with a @code{deny} policy. Thus no one will be allowed to
1715 use the VNC server until the ACLs have been loaded. This can be
1716 achieved using the @code{acl} monitor command.
1718 @item lossy
1720 Enable lossy compression methods (gradient, JPEG, ...). If this
1721 option is set, VNC client may receive lossy framebuffer updates
1722 depending on its encoding settings. Enabling this option can save
1723 a lot of bandwidth at the expense of quality.
1725 @item non-adaptive
1727 Disable adaptive encodings. Adaptive encodings are enabled by default.
1728 An adaptive encoding will try to detect frequently updated screen regions,
1729 and send updates in these regions using a lossy encoding (like JPEG).
1730 This can be really helpful to save bandwidth when playing videos. Disabling
1731 adaptive encodings restores the original static behavior of encodings
1732 like Tight.
1734 @item share=[allow-exclusive|force-shared|ignore]
1736 Set display sharing policy. 'allow-exclusive' allows clients to ask
1737 for exclusive access. As suggested by the rfb spec this is
1738 implemented by dropping other connections. Connecting multiple
1739 clients in parallel requires all clients asking for a shared session
1740 (vncviewer: -shared switch). This is the default. 'force-shared'
1741 disables exclusive client access. Useful for shared desktop sessions,
1742 where you don't want someone forgetting specify -shared disconnect
1743 everybody else. 'ignore' completely ignores the shared flag and
1744 allows everybody connect unconditionally. Doesn't conform to the rfb
1745 spec but is traditional QEMU behavior.
1747 @item key-delay-ms
1749 Set keyboard delay, for key down and key up events, in milliseconds.
1750 Default is 1. Keyboards are low-bandwidth devices, so this slowdown
1751 can help the device and guest to keep up and not lose events in case
1752 events are arriving in bulk. Possible causes for the latter are flaky
1753 network connections, or scripts for automated testing.
1755 @end table
1756 ETEXI
1758 STEXI
1759 @end table
1760 ETEXI
1761 ARCHHEADING(, QEMU_ARCH_I386)
1763 ARCHHEADING(i386 target only, QEMU_ARCH_I386)
1764 STEXI
1765 @table @option
1766 ETEXI
1768 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1769 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1770 QEMU_ARCH_I386)
1771 STEXI
1772 @item -win2k-hack
1773 @findex -win2k-hack
1774 Use it when installing Windows 2000 to avoid a disk full bug. After
1775 Windows 2000 is installed, you no longer need this option (this option
1776 slows down the IDE transfers).
1777 ETEXI
1779 HXCOMM Deprecated by -rtc
1780 DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1782 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1783 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1784 QEMU_ARCH_I386)
1785 STEXI
1786 @item -no-fd-bootchk
1787 @findex -no-fd-bootchk
1788 Disable boot signature checking for floppy disks in BIOS. May
1789 be needed to boot from old floppy disks.
1790 ETEXI
1792 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1793 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1794 STEXI
1795 @item -no-acpi
1796 @findex -no-acpi
1797 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1798 it if your guest OS complains about ACPI problems (PC target machine
1799 only).
1800 ETEXI
1802 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1803 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
1804 STEXI
1805 @item -no-hpet
1806 @findex -no-hpet
1807 Disable HPET support.
1808 ETEXI
1810 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1811 "-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"
1812 " ACPI table description\n", QEMU_ARCH_I386)
1813 STEXI
1814 @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}]...]
1815 @findex -acpitable
1816 Add ACPI table with specified header fields and context from specified files.
1817 For file=, take whole ACPI table from the specified files, including all
1818 ACPI headers (possible overridden by other options).
1819 For data=, only data
1820 portion of the table is used, all header information is specified in the
1821 command line.
1822 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1823 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1824 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1825 spec.
1826 ETEXI
1828 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1829 "-smbios file=binary\n"
1830 " load SMBIOS entry from binary file\n"
1831 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1832 " [,uefi=on|off]\n"
1833 " specify SMBIOS type 0 fields\n"
1834 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1835 " [,uuid=uuid][,sku=str][,family=str]\n"
1836 " specify SMBIOS type 1 fields\n"
1837 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1838 " [,asset=str][,location=str]\n"
1839 " specify SMBIOS type 2 fields\n"
1840 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1841 " [,sku=str]\n"
1842 " specify SMBIOS type 3 fields\n"
1843 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1844 " [,asset=str][,part=str]\n"
1845 " specify SMBIOS type 4 fields\n"
1846 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
1847 " [,asset=str][,part=str][,speed=%d]\n"
1848 " specify SMBIOS type 17 fields\n",
1849 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1850 STEXI
1851 @item -smbios file=@var{binary}
1852 @findex -smbios
1853 Load SMBIOS entry from binary file.
1855 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
1856 Specify SMBIOS type 0 fields
1858 @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}]
1859 Specify SMBIOS type 1 fields
1861 @item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}]
1862 Specify SMBIOS type 2 fields
1864 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1865 Specify SMBIOS type 3 fields
1867 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1868 Specify SMBIOS type 4 fields
1870 @item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}]
1871 Specify SMBIOS type 17 fields
1872 ETEXI
1874 STEXI
1875 @end table
1876 ETEXI
1877 DEFHEADING()
1879 DEFHEADING(Network options)
1880 STEXI
1881 @table @option
1882 ETEXI
1884 HXCOMM Legacy slirp options (now moved to -net user):
1885 #ifdef CONFIG_SLIRP
1886 DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1887 DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1888 DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1889 #ifndef _WIN32
1890 DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1891 #endif
1892 #endif
1894 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1895 #ifdef CONFIG_SLIRP
1896 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1897 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1898 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
1899 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n"
1900 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
1901 #ifndef _WIN32
1902 "[,smb=dir[,smbserver=addr]]\n"
1903 #endif
1904 " configure a user mode network backend with ID 'str',\n"
1905 " its DHCP server and optional services\n"
1906 #endif
1907 #ifdef _WIN32
1908 "-netdev tap,id=str,ifname=name\n"
1909 " configure a host TAP network backend with ID 'str'\n"
1910 #else
1911 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
1912 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
1913 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
1914 " [,poll-us=n]\n"
1915 " configure a host TAP network backend with ID 'str'\n"
1916 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1917 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1918 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1919 " to deconfigure it\n"
1920 " use '[down]script=no' to disable script execution\n"
1921 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1922 " configure it\n"
1923 " use 'fd=h' to connect to an already opened TAP interface\n"
1924 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
1925 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1926 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1927 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1928 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1929 " use vhost=on to enable experimental in kernel accelerator\n"
1930 " (only has effect for virtio guests which use MSIX)\n"
1931 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1932 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
1933 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
1934 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
1935 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
1936 " spent on busy polling for vhost net\n"
1937 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1938 " configure a host TAP network backend with ID 'str' that is\n"
1939 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1940 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
1941 #endif
1942 #ifdef __linux__
1943 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1944 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1945 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1946 " [,rxcookie=rxcookie][,offset=offset]\n"
1947 " configure a network backend with ID 'str' connected to\n"
1948 " an Ethernet over L2TPv3 pseudowire.\n"
1949 " Linux kernel 3.3+ as well as most routers can talk\n"
1950 " L2TPv3. This transport allows connecting a VM to a VM,\n"
1951 " VM to a router and even VM to Host. It is a nearly-universal\n"
1952 " standard (RFC3391). Note - this implementation uses static\n"
1953 " pre-configured tunnels (same as the Linux kernel).\n"
1954 " use 'src=' to specify source address\n"
1955 " use 'dst=' to specify destination address\n"
1956 " use 'udp=on' to specify udp encapsulation\n"
1957 " use 'srcport=' to specify source udp port\n"
1958 " use 'dstport=' to specify destination udp port\n"
1959 " use 'ipv6=on' to force v6\n"
1960 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1961 " well as a weak security measure\n"
1962 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
1963 " use 'txcookie=0x012345678' to specify a txcookie\n"
1964 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
1965 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
1966 " use 'pincounter=on' to work around broken counter handling in peer\n"
1967 " use 'offset=X' to add an extra offset between header and data\n"
1968 #endif
1969 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1970 " configure a network backend to connect to another network\n"
1971 " using a socket connection\n"
1972 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1973 " configure a network backend to connect to a multicast maddr and port\n"
1974 " use 'localaddr=addr' to specify the host address to send packets from\n"
1975 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1976 " configure a network backend to connect to another network\n"
1977 " using an UDP tunnel\n"
1978 #ifdef CONFIG_VDE
1979 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1980 " configure a network backend to connect to port 'n' of a vde switch\n"
1981 " running on host and listening for incoming connections on 'socketpath'.\n"
1982 " Use group 'groupname' and mode 'octalmode' to change default\n"
1983 " ownership and permissions for communication port.\n"
1984 #endif
1985 #ifdef CONFIG_NETMAP
1986 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
1987 " attach to the existing netmap-enabled network interface 'name', or to a\n"
1988 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
1989 " netmap device, defaults to '/dev/netmap')\n"
1990 #endif
1991 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1992 " configure a vhost-user network, backed by a chardev 'dev'\n"
1993 "-netdev hubport,id=str,hubid=n\n"
1994 " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL)
1995 DEF("net", HAS_ARG, QEMU_OPTION_net,
1996 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1997 " old way to create a new NIC and connect it to VLAN 'n'\n"
1998 " (use the '-device devtype,netdev=str' option if possible instead)\n"
1999 "-net dump[,vlan=n][,file=f][,len=n]\n"
2000 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
2001 "-net none use it alone to have zero network devices. If no -net option\n"
2002 " is provided, the default is '-net nic -net user'\n"
2003 "-net ["
2004 #ifdef CONFIG_SLIRP
2005 "user|"
2006 #endif
2007 "tap|"
2008 "bridge|"
2009 #ifdef CONFIG_VDE
2010 "vde|"
2011 #endif
2012 #ifdef CONFIG_NETMAP
2013 "netmap|"
2014 #endif
2015 "socket][,vlan=n][,option][,option][,...]\n"
2016 " old way to initialize a host network interface\n"
2017 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2018 STEXI
2019 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
2020 @findex -net
2021 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
2022 = 0 is the default). The NIC is an e1000 by default on the PC
2023 target. Optionally, the MAC address can be changed to @var{mac}, the
2024 device address set to @var{addr} (PCI cards only),
2025 and a @var{name} can be assigned for use in monitor commands.
2026 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2027 that the card should have; this option currently only affects virtio cards; set
2028 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2029 NIC is created. QEMU can emulate several different models of network card.
2030 Valid values for @var{type} are
2031 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
2032 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
2033 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
2034 Not all devices are supported on all targets. Use @code{-net nic,model=help}
2035 for a list of available devices for your target.
2037 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
2038 @findex -netdev
2039 @item -net user[,@var{option}][,@var{option}][,...]
2040 Use the user mode network stack which requires no administrator
2041 privilege to run. Valid options are:
2043 @table @option
2044 @item vlan=@var{n}
2045 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
2047 @item id=@var{id}
2048 @itemx name=@var{name}
2049 Assign symbolic name for use in monitor commands.
2051 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
2052 be enabled. If neither is specified both protocols are enabled.
2054 @item net=@var{addr}[/@var{mask}]
2055 Set IP network address the guest will see. Optionally specify the netmask,
2056 either in the form a.b.c.d or as number of valid top-most bits. Default is
2057 10.0.2.0/24.
2059 @item host=@var{addr}
2060 Specify the guest-visible address of the host. Default is the 2nd IP in the
2061 guest network, i.e. x.x.x.2.
2063 @item ipv6-net=@var{addr}[/@var{int}]
2064 Set IPv6 network address the guest will see (default is fec0::/64). The
2065 network prefix is given in the usual hexadecimal IPv6 address
2066 notation. The prefix size is optional, and is given as the number of
2067 valid top-most bits (default is 64).
2069 @item ipv6-host=@var{addr}
2070 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2071 the guest network, i.e. xxxx::2.
2073 @item restrict=on|off
2074 If this option is enabled, the guest will be isolated, i.e. it will not be
2075 able to contact the host and no guest IP packets will be routed over the host
2076 to the outside. This option does not affect any explicitly set forwarding rules.
2078 @item hostname=@var{name}
2079 Specifies the client hostname reported by the built-in DHCP server.
2081 @item dhcpstart=@var{addr}
2082 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
2083 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
2085 @item dns=@var{addr}
2086 Specify the guest-visible address of the virtual nameserver. The address must
2087 be different from the host address. Default is the 3rd IP in the guest network,
2088 i.e. x.x.x.3.
2090 @item ipv6-dns=@var{addr}
2091 Specify the guest-visible address of the IPv6 virtual nameserver. The address
2092 must be different from the host address. Default is the 3rd IP in the guest
2093 network, i.e. xxxx::3.
2095 @item dnssearch=@var{domain}
2096 Provides an entry for the domain-search list sent by the built-in
2097 DHCP server. More than one domain suffix can be transmitted by specifying
2098 this option multiple times. If supported, this will cause the guest to
2099 automatically try to append the given domain suffix(es) in case a domain name
2100 can not be resolved.
2102 Example:
2103 @example
2104 qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
2105 @end example
2107 @item tftp=@var{dir}
2108 When using the user mode network stack, activate a built-in TFTP
2109 server. The files in @var{dir} will be exposed as the root of a TFTP server.
2110 The TFTP client on the guest must be configured in binary mode (use the command
2111 @code{bin} of the Unix TFTP client).
2113 @item bootfile=@var{file}
2114 When using the user mode network stack, broadcast @var{file} as the BOOTP
2115 filename. In conjunction with @option{tftp}, this can be used to network boot
2116 a guest from a local directory.
2118 Example (using pxelinux):
2119 @example
2120 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2121 @end example
2123 @item smb=@var{dir}[,smbserver=@var{addr}]
2124 When using the user mode network stack, activate a built-in SMB
2125 server so that Windows OSes can access to the host files in @file{@var{dir}}
2126 transparently. The IP address of the SMB server can be set to @var{addr}. By
2127 default the 4th IP in the guest network is used, i.e. x.x.x.4.
2129 In the guest Windows OS, the line:
2130 @example
2131 10.0.2.4 smbserver
2132 @end example
2133 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2134 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2136 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2138 Note that a SAMBA server must be installed on the host OS.
2139 QEMU was tested successfully with smbd versions from Red Hat 9,
2140 Fedora Core 3 and OpenSUSE 11.x.
2142 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
2143 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2144 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2145 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
2146 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2147 be bound to a specific host interface. If no connection type is set, TCP is
2148 used. This option can be given multiple times.
2150 For example, to redirect host X11 connection from screen 1 to guest
2151 screen 0, use the following:
2153 @example
2154 # on the host
2155 qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
2156 # this host xterm should open in the guest X11 server
2157 xterm -display :1
2158 @end example
2160 To redirect telnet connections from host port 5555 to telnet port on
2161 the guest, use the following:
2163 @example
2164 # on the host
2165 qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
2166 telnet localhost 5555
2167 @end example
2169 Then when you use on the host @code{telnet localhost 5555}, you
2170 connect to the guest telnet server.
2172 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
2173 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
2174 Forward guest TCP connections to the IP address @var{server} on port @var{port}
2175 to the character device @var{dev} or to a program executed by @var{cmd:command}
2176 which gets spawned for each connection. This option can be given multiple times.
2178 You can either use a chardev directly and have that one used throughout QEMU's
2179 lifetime, like in the following example:
2181 @example
2182 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2183 # the guest accesses it
2184 qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
2185 @end example
2187 Or you can execute a command on every TCP connection established by the guest,
2188 so that QEMU behaves similar to an inetd process for that virtual server:
2190 @example
2191 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2192 # and connect the TCP stream to its stdin/stdout
2193 qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2194 @end example
2196 @end table
2198 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
2199 processed and applied to -net user. Mixing them with the new configuration
2200 syntax gives undefined results. Their use for new applications is discouraged
2201 as they will be removed from future versions.
2203 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2204 @itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
2205 Connect the host TAP network interface @var{name} to VLAN @var{n}.
2207 Use the network script @var{file} to configure it and the network script
2208 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
2209 automatically provides one. The default network configure script is
2210 @file{/etc/qemu-ifup} and the default network deconfigure script is
2211 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2212 to disable script execution.
2214 If running QEMU as an unprivileged user, use the network helper
2215 @var{helper} to configure the TAP interface and attach it to the bridge.
2216 The default network helper executable is @file{/path/to/qemu-bridge-helper}
2217 and the default bridge device is @file{br0}.
2219 @option{fd}=@var{h} can be used to specify the handle of an already
2220 opened host TAP interface.
2222 Examples:
2224 @example
2225 #launch a QEMU instance with the default network script
2226 qemu-system-i386 linux.img -net nic -net tap
2227 @end example
2229 @example
2230 #launch a QEMU instance with two NICs, each one connected
2231 #to a TAP device
2232 qemu-system-i386 linux.img \
2233 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
2234 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
2235 @end example
2237 @example
2238 #launch a QEMU instance with the default network helper to
2239 #connect a TAP device to bridge br0
2240 qemu-system-i386 linux.img \
2241 -net nic -net tap,"helper=/path/to/qemu-bridge-helper"
2242 @end example
2244 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
2245 @itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
2246 Connect a host TAP network interface to a host bridge device.
2248 Use the network helper @var{helper} to configure the TAP interface and
2249 attach it to the bridge. The default network helper executable is
2250 @file{/path/to/qemu-bridge-helper} and the default bridge
2251 device is @file{br0}.
2253 Examples:
2255 @example
2256 #launch a QEMU instance with the default network helper to
2257 #connect a TAP device to bridge br0
2258 qemu-system-i386 linux.img -net bridge -net nic,model=virtio
2259 @end example
2261 @example
2262 #launch a QEMU instance with the default network helper to
2263 #connect a TAP device to bridge qemubr0
2264 qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
2265 @end example
2267 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
2268 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
2270 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
2271 machine using a TCP socket connection. If @option{listen} is
2272 specified, QEMU waits for incoming connections on @var{port}
2273 (@var{host} is optional). @option{connect} is used to connect to
2274 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2275 specifies an already opened TCP socket.
2277 Example:
2278 @example
2279 # launch a first QEMU instance
2280 qemu-system-i386 linux.img \
2281 -net nic,macaddr=52:54:00:12:34:56 \
2282 -net socket,listen=:1234
2283 # connect the VLAN 0 of this instance to the VLAN 0
2284 # of the first instance
2285 qemu-system-i386 linux.img \
2286 -net nic,macaddr=52:54:00:12:34:57 \
2287 -net socket,connect=127.0.0.1:1234
2288 @end example
2290 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
2291 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
2293 Create a VLAN @var{n} shared with another QEMU virtual
2294 machines using a UDP multicast socket, effectively making a bus for
2295 every QEMU with same multicast address @var{maddr} and @var{port}.
2296 NOTES:
2297 @enumerate
2298 @item
2299 Several QEMU can be running on different hosts and share same bus (assuming
2300 correct multicast setup for these hosts).
2301 @item
2302 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2303 @url{http://user-mode-linux.sf.net}.
2304 @item
2305 Use @option{fd=h} to specify an already opened UDP multicast socket.
2306 @end enumerate
2308 Example:
2309 @example
2310 # launch one QEMU instance
2311 qemu-system-i386 linux.img \
2312 -net nic,macaddr=52:54:00:12:34:56 \
2313 -net socket,mcast=230.0.0.1:1234
2314 # launch another QEMU instance on same "bus"
2315 qemu-system-i386 linux.img \
2316 -net nic,macaddr=52:54:00:12:34:57 \
2317 -net socket,mcast=230.0.0.1:1234
2318 # launch yet another QEMU instance on same "bus"
2319 qemu-system-i386 linux.img \
2320 -net nic,macaddr=52:54:00:12:34:58 \
2321 -net socket,mcast=230.0.0.1:1234
2322 @end example
2324 Example (User Mode Linux compat.):
2325 @example
2326 # launch QEMU instance (note mcast address selected
2327 # is UML's default)
2328 qemu-system-i386 linux.img \
2329 -net nic,macaddr=52:54:00:12:34:56 \
2330 -net socket,mcast=239.192.168.1:1102
2331 # launch UML
2332 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2333 @end example
2335 Example (send packets from host's 1.2.3.4):
2336 @example
2337 qemu-system-i386 linux.img \
2338 -net nic,macaddr=52:54:00:12:34:56 \
2339 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2340 @end example
2342 @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}]
2343 @itemx -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
2344 Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
2345 protocol to transport Ethernet (and other Layer 2) data frames between
2346 two systems. It is present in routers, firewalls and the Linux kernel
2347 (from version 3.3 onwards).
2349 This transport allows a VM to communicate to another VM, router or firewall directly.
2351 @item src=@var{srcaddr}
2352 source address (mandatory)
2353 @item dst=@var{dstaddr}
2354 destination address (mandatory)
2355 @item udp
2356 select udp encapsulation (default is ip).
2357 @item srcport=@var{srcport}
2358 source udp port.
2359 @item dstport=@var{dstport}
2360 destination udp port.
2361 @item ipv6
2362 force v6, otherwise defaults to v4.
2363 @item rxcookie=@var{rxcookie}
2364 @itemx txcookie=@var{txcookie}
2365 Cookies are a weak form of security in the l2tpv3 specification.
2366 Their function is mostly to prevent misconfiguration. By default they are 32
2367 bit.
2368 @item cookie64
2369 Set cookie size to 64 bit instead of the default 32
2370 @item counter=off
2371 Force a 'cut-down' L2TPv3 with no counter as in
2372 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2373 @item pincounter=on
2374 Work around broken counter handling in peer. This may also help on
2375 networks which have packet reorder.
2376 @item offset=@var{offset}
2377 Add an extra offset between header and data
2379 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2380 on the remote Linux host 1.2.3.4:
2381 @example
2382 # Setup tunnel on linux host using raw ip as encapsulation
2383 # on 1.2.3.4
2384 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2385 encap udp udp_sport 16384 udp_dport 16384
2386 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2387 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2388 ifconfig vmtunnel0 mtu 1500
2389 ifconfig vmtunnel0 up
2390 brctl addif br-lan vmtunnel0
2393 # on 4.3.2.1
2394 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2396 qemu-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
2399 @end example
2401 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2402 @itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2403 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2404 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2405 and MODE @var{octalmode} to change default ownership and permissions for
2406 communication port. This option is only available if QEMU has been compiled
2407 with vde support enabled.
2409 Example:
2410 @example
2411 # launch vde switch
2412 vde_switch -F -sock /tmp/myswitch
2413 # launch QEMU instance
2414 qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
2415 @end example
2417 @item -netdev hubport,id=@var{id},hubid=@var{hubid}
2419 Create a hub port on QEMU "vlan" @var{hubid}.
2421 The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single
2422 netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2423 required hub automatically.
2425 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2427 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2428 be a unix domain socket backed one. The vhost-user uses a specifically defined
2429 protocol to pass vhost ioctl replacement messages to an application on the other
2430 end of the socket. On non-MSIX guests, the feature can be forced with
2431 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2432 be created for multiqueue vhost-user.
2434 Example:
2435 @example
2436 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2437 -numa node,memdev=mem \
2438 -chardev socket,id=chr0,path=/path/to/socket \
2439 -netdev type=vhost-user,id=net0,chardev=chr0 \
2440 -device virtio-net-pci,netdev=net0
2441 @end example
2443 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2444 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2445 At most @var{len} bytes (64k by default) per packet are stored. The file format is
2446 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
2447 Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
2449 @item -net none
2450 Indicate that no network devices should be configured. It is used to
2451 override the default configuration (@option{-net nic -net user}) which
2452 is activated if no @option{-net} options are provided.
2453 ETEXI
2455 STEXI
2456 @end table
2457 ETEXI
2458 DEFHEADING()
2460 DEFHEADING(Character device options)
2461 STEXI
2463 The general form of a character device option is:
2464 @table @option
2465 ETEXI
2467 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
2468 "-chardev help\n"
2469 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2470 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2471 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
2472 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
2473 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2474 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
2475 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
2476 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
2477 " [,logfile=PATH][,logappend=on|off]\n"
2478 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2479 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
2480 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2481 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2482 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2483 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2484 #ifdef _WIN32
2485 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2486 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2487 #else
2488 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2489 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
2490 #endif
2491 #ifdef CONFIG_BRLAPI
2492 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2493 #endif
2494 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2495 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2496 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2497 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2498 #endif
2499 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2500 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2501 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2502 #endif
2503 #if defined(CONFIG_SPICE)
2504 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2505 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2506 #endif
2507 , QEMU_ARCH_ALL
2510 STEXI
2511 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
2512 @findex -chardev
2513 Backend is one of:
2514 @option{null},
2515 @option{socket},
2516 @option{udp},
2517 @option{msmouse},
2518 @option{vc},
2519 @option{ringbuf},
2520 @option{file},
2521 @option{pipe},
2522 @option{console},
2523 @option{serial},
2524 @option{pty},
2525 @option{stdio},
2526 @option{braille},
2527 @option{tty},
2528 @option{parallel},
2529 @option{parport},
2530 @option{spicevmc}.
2531 @option{spiceport}.
2532 The specific backend will determine the applicable options.
2534 Use "-chardev help" to print all available chardev backend types.
2536 All devices must have an id, which can be any string up to 127 characters long.
2537 It is used to uniquely identify this device in other command line directives.
2539 A character device may be used in multiplexing mode by multiple front-ends.
2540 Specify @option{mux=on} to enable this mode.
2541 A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2542 backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2543 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2544 create a multiplexer with your specified ID, and you can then configure multiple
2545 front ends to use that chardev ID for their input/output. Up to four different
2546 front ends can be connected to a single multiplexed chardev. (Without
2547 multiplexing enabled, a chardev can only be used by a single front end.)
2548 For instance you could use this to allow a single stdio chardev to be used by
2549 two serial ports and the QEMU monitor:
2551 @example
2552 -chardev stdio,mux=on,id=char0 \
2553 -mon chardev=char0,mode=readline \
2554 -serial chardev:char0 \
2555 -serial chardev:char0
2556 @end example
2558 You can have more than one multiplexer in a system configuration; for instance
2559 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2560 multiplexed between the QEMU monitor and a parallel port:
2562 @example
2563 -chardev stdio,mux=on,id=char0 \
2564 -mon chardev=char0,mode=readline \
2565 -parallel chardev:char0 \
2566 -chardev tcp,...,mux=on,id=char1 \
2567 -serial chardev:char1 \
2568 -serial chardev:char1
2569 @end example
2571 When you're using a multiplexed character device, some escape sequences are
2572 interpreted in the input. @xref{mux_keys, Keys in the character backend
2573 multiplexer}.
2575 Note that some other command line options may implicitly create multiplexed
2576 character backends; for instance @option{-serial mon:stdio} creates a
2577 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2578 and @option{-nographic} also multiplexes the console and the monitor to
2579 stdio.
2581 There is currently no support for multiplexing in the other direction
2582 (where a single QEMU front end takes input and output from multiple chardevs).
2584 Every backend supports the @option{logfile} option, which supplies the path
2585 to a file to record all data transmitted via the backend. The @option{logappend}
2586 option controls whether the log file will be truncated or appended to when
2587 opened.
2589 Further options to each backend are described below.
2591 @item -chardev null ,id=@var{id}
2592 A void device. This device will not emit any data, and will drop any data it
2593 receives. The null backend does not take any options.
2595 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
2597 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2598 unix socket will be created if @option{path} is specified. Behaviour is
2599 undefined if TCP options are specified for a unix socket.
2601 @option{server} specifies that the socket shall be a listening socket.
2603 @option{nowait} specifies that QEMU should not block waiting for a client to
2604 connect to a listening socket.
2606 @option{telnet} specifies that traffic on the socket should interpret telnet
2607 escape sequences.
2609 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2610 the remote end goes away. qemu will delay this many seconds and then attempt
2611 to reconnect. Zero disables reconnecting, and is the default.
2613 @option{tls-creds} requests enablement of the TLS protocol for encryption,
2614 and specifies the id of the TLS credentials to use for the handshake. The
2615 credentials must be previously created with the @option{-object tls-creds}
2616 argument.
2618 TCP and unix socket options are given below:
2620 @table @option
2622 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
2624 @option{host} for a listening socket specifies the local address to be bound.
2625 For a connecting socket species the remote host to connect to. @option{host} is
2626 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2628 @option{port} for a listening socket specifies the local port to be bound. For a
2629 connecting socket specifies the port on the remote host to connect to.
2630 @option{port} can be given as either a port number or a service name.
2631 @option{port} is required.
2633 @option{to} is only relevant to listening sockets. If it is specified, and
2634 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2635 to and including @option{to} until it succeeds. @option{to} must be specified
2636 as a port number.
2638 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2639 If neither is specified the socket may use either protocol.
2641 @option{nodelay} disables the Nagle algorithm.
2643 @item unix options: path=@var{path}
2645 @option{path} specifies the local path of the unix socket. @option{path} is
2646 required.
2648 @end table
2650 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2652 Sends all traffic from the guest to a remote host over UDP.
2654 @option{host} specifies the remote host to connect to. If not specified it
2655 defaults to @code{localhost}.
2657 @option{port} specifies the port on the remote host to connect to. @option{port}
2658 is required.
2660 @option{localaddr} specifies the local address to bind to. If not specified it
2661 defaults to @code{0.0.0.0}.
2663 @option{localport} specifies the local port to bind to. If not specified any
2664 available local port will be used.
2666 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2667 If neither is specified the device may use either protocol.
2669 @item -chardev msmouse ,id=@var{id}
2671 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2672 take any options.
2674 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2676 Connect to a QEMU text console. @option{vc} may optionally be given a specific
2677 size.
2679 @option{width} and @option{height} specify the width and height respectively of
2680 the console, in pixels.
2682 @option{cols} and @option{rows} specify that the console be sized to fit a text
2683 console with the given dimensions.
2685 @item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
2687 Create a ring buffer with fixed size @option{size}.
2688 @var{size} must be a power of two and defaults to @code{64K}.
2690 @item -chardev file ,id=@var{id} ,path=@var{path}
2692 Log all traffic received from the guest to a file.
2694 @option{path} specifies the path of the file to be opened. This file will be
2695 created if it does not already exist, and overwritten if it does. @option{path}
2696 is required.
2698 @item -chardev pipe ,id=@var{id} ,path=@var{path}
2700 Create a two-way connection to the guest. The behaviour differs slightly between
2701 Windows hosts and other hosts:
2703 On Windows, a single duplex pipe will be created at
2704 @file{\\.pipe\@option{path}}.
2706 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2707 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2708 received by the guest. Data written by the guest can be read from
2709 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2710 be present.
2712 @option{path} forms part of the pipe path as described above. @option{path} is
2713 required.
2715 @item -chardev console ,id=@var{id}
2717 Send traffic from the guest to QEMU's standard output. @option{console} does not
2718 take any options.
2720 @option{console} is only available on Windows hosts.
2722 @item -chardev serial ,id=@var{id} ,path=@option{path}
2724 Send traffic from the guest to a serial device on the host.
2726 On Unix hosts serial will actually accept any tty device,
2727 not only serial lines.
2729 @option{path} specifies the name of the serial device to open.
2731 @item -chardev pty ,id=@var{id}
2733 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2734 not take any options.
2736 @option{pty} is not available on Windows hosts.
2738 @item -chardev stdio ,id=@var{id} [,signal=on|off]
2739 Connect to standard input and standard output of the QEMU process.
2741 @option{signal} controls if signals are enabled on the terminal, that includes
2742 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2743 default, use @option{signal=off} to disable it.
2745 @item -chardev braille ,id=@var{id}
2747 Connect to a local BrlAPI server. @option{braille} does not take any options.
2749 @item -chardev tty ,id=@var{id} ,path=@var{path}
2751 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2752 DragonFlyBSD hosts. It is an alias for @option{serial}.
2754 @option{path} specifies the path to the tty. @option{path} is required.
2756 @item -chardev parallel ,id=@var{id} ,path=@var{path}
2757 @itemx -chardev parport ,id=@var{id} ,path=@var{path}
2759 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2761 Connect to a local parallel port.
2763 @option{path} specifies the path to the parallel port device. @option{path} is
2764 required.
2766 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2768 @option{spicevmc} is only available when spice support is built in.
2770 @option{debug} debug level for spicevmc
2772 @option{name} name of spice channel to connect to
2774 Connect to a spice virtual machine channel, such as vdiport.
2776 @item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2778 @option{spiceport} is only available when spice support is built in.
2780 @option{debug} debug level for spicevmc
2782 @option{name} name of spice port to connect to
2784 Connect to a spice port, allowing a Spice client to handle the traffic
2785 identified by a name (preferably a fqdn).
2786 ETEXI
2788 STEXI
2789 @end table
2790 ETEXI
2791 DEFHEADING()
2793 DEFHEADING(Device URL Syntax)
2794 STEXI
2796 In addition to using normal file images for the emulated storage devices,
2797 QEMU can also use networked resources such as iSCSI devices. These are
2798 specified using a special URL syntax.
2800 @table @option
2801 @item iSCSI
2802 iSCSI support allows QEMU to access iSCSI resources directly and use as
2803 images for the guest storage. Both disk and cdrom images are supported.
2805 Syntax for specifying iSCSI LUNs is
2806 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2808 By default qemu will use the iSCSI initiator-name
2809 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2810 line or a configuration file.
2812 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2813 stalled requests and force a reestablishment of the session. The timeout
2814 is specified in seconds. The default is 0 which means no timeout. Libiscsi
2815 1.15.0 or greater is required for this feature.
2817 Example (without authentication):
2818 @example
2819 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2820 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2821 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2822 @end example
2824 Example (CHAP username/password via URL):
2825 @example
2826 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
2827 @end example
2829 Example (CHAP username/password via environment variables):
2830 @example
2831 LIBISCSI_CHAP_USERNAME="user" \
2832 LIBISCSI_CHAP_PASSWORD="password" \
2833 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2834 @end example
2836 iSCSI support is an optional feature of QEMU and only available when
2837 compiled and linked against libiscsi.
2838 ETEXI
2839 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2840 "-iscsi [user=user][,password=password]\n"
2841 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
2842 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
2843 " [,timeout=timeout]\n"
2844 " iSCSI session parameters\n", QEMU_ARCH_ALL)
2845 STEXI
2847 iSCSI parameters such as username and password can also be specified via
2848 a configuration file. See qemu-doc for more information and examples.
2850 @item NBD
2851 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2852 as Unix Domain Sockets.
2854 Syntax for specifying a NBD device using TCP
2855 ``nbd:<server-ip>:<port>[:exportname=<export>]''
2857 Syntax for specifying a NBD device using Unix Domain Sockets
2858 ``nbd:unix:<domain-socket>[:exportname=<export>]''
2861 Example for TCP
2862 @example
2863 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
2864 @end example
2866 Example for Unix Domain Sockets
2867 @example
2868 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
2869 @end example
2871 @item SSH
2872 QEMU supports SSH (Secure Shell) access to remote disks.
2874 Examples:
2875 @example
2876 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2877 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2878 @end example
2880 Currently authentication must be done using ssh-agent. Other
2881 authentication methods may be supported in future.
2883 @item Sheepdog
2884 Sheepdog is a distributed storage system for QEMU.
2885 QEMU supports using either local sheepdog devices or remote networked
2886 devices.
2888 Syntax for specifying a sheepdog device
2889 @example
2890 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
2891 @end example
2893 Example
2894 @example
2895 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
2896 @end example
2898 See also @url{https://sheepdog.github.io/sheepdog/}.
2900 @item GlusterFS
2901 GlusterFS is a user space distributed file system.
2902 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2903 TCP, Unix Domain Sockets and RDMA transport protocols.
2905 Syntax for specifying a VM disk image on GlusterFS volume is
2906 @example
2908 URI:
2909 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
2911 JSON:
2912 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
2913 @ "server":[@{"type":"tcp","host":"...","port":"..."@},
2914 @ @{"type":"unix","socket":"..."@}]@}@}'
2915 @end example
2918 Example
2919 @example
2920 URI:
2921 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
2922 @ file.debug=9,file.logfile=/var/log/qemu-gluster.log
2924 JSON:
2925 qemu-system-x86_64 'json:@{"driver":"qcow2",
2926 @ "file":@{"driver":"gluster",
2927 @ "volume":"testvol","path":"a.img",
2928 @ "debug":9,"logfile":"/var/log/qemu-gluster.log",
2929 @ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
2930 @ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
2931 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
2932 @ file.debug=9,file.logfile=/var/log/qemu-gluster.log,
2933 @ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
2934 @ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
2935 @end example
2937 See also @url{http://www.gluster.org}.
2939 @item HTTP/HTTPS/FTP/FTPS
2940 QEMU supports read-only access to files accessed over http(s) and ftp(s).
2942 Syntax using a single filename:
2943 @example
2944 <protocol>://[<username>[:<password>]@@]<host>/<path>
2945 @end example
2947 where:
2948 @table @option
2949 @item protocol
2950 'http', 'https', 'ftp', or 'ftps'.
2952 @item username
2953 Optional username for authentication to the remote server.
2955 @item password
2956 Optional password for authentication to the remote server.
2958 @item host
2959 Address of the remote server.
2961 @item path
2962 Path on the remote server, including any query string.
2963 @end table
2965 The following options are also supported:
2966 @table @option
2967 @item url
2968 The full URL when passing options to the driver explicitly.
2970 @item readahead
2971 The amount of data to read ahead with each range request to the remote server.
2972 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2973 does not have a suffix, it will be assumed to be in bytes. The value must be a
2974 multiple of 512 bytes. It defaults to 256k.
2976 @item sslverify
2977 Whether to verify the remote server's certificate when connecting over SSL. It
2978 can have the value 'on' or 'off'. It defaults to 'on'.
2980 @item cookie
2981 Send this cookie (it can also be a list of cookies separated by ';') with
2982 each outgoing request. Only supported when using protocols such as HTTP
2983 which support cookies, otherwise ignored.
2985 @item timeout
2986 Set the timeout in seconds of the CURL connection. This timeout is the time
2987 that CURL waits for a response from the remote server to get the size of the
2988 image to be downloaded. If not set, the default timeout of 5 seconds is used.
2989 @end table
2991 Note that when passing options to qemu explicitly, @option{driver} is the value
2992 of <protocol>.
2994 Example: boot from a remote Fedora 20 live ISO image
2995 @example
2996 qemu-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
2998 qemu-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
2999 @end example
3001 Example: boot from a remote Fedora 20 cloud image using a local overlay for
3002 writes, copy-on-read, and a readahead of 64k
3003 @example
3004 qemu-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
3006 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
3007 @end example
3009 Example: boot from an image stored on a VMware vSphere server with a self-signed
3010 certificate using a local overlay for writes, a readahead of 64k and a timeout
3011 of 10 seconds.
3012 @example
3013 qemu-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
3015 qemu-system-x86_64 -drive file=/tmp/test.qcow2
3016 @end example
3017 ETEXI
3019 STEXI
3020 @end table
3021 ETEXI
3023 DEFHEADING(Bluetooth(R) options)
3024 STEXI
3025 @table @option
3026 ETEXI
3028 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
3029 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
3030 "-bt hci,host[:id]\n" \
3031 " use host's HCI with the given name\n" \
3032 "-bt hci[,vlan=n]\n" \
3033 " emulate a standard HCI in virtual scatternet 'n'\n" \
3034 "-bt vhci[,vlan=n]\n" \
3035 " add host computer to virtual scatternet 'n' using VHCI\n" \
3036 "-bt device:dev[,vlan=n]\n" \
3037 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
3038 QEMU_ARCH_ALL)
3039 STEXI
3040 @item -bt hci[...]
3041 @findex -bt
3042 Defines the function of the corresponding Bluetooth HCI. -bt options
3043 are matched with the HCIs present in the chosen machine type. For
3044 example when emulating a machine with only one HCI built into it, only
3045 the first @code{-bt hci[...]} option is valid and defines the HCI's
3046 logic. The Transport Layer is decided by the machine type. Currently
3047 the machines @code{n800} and @code{n810} have one HCI and all other
3048 machines have none.
3050 @anchor{bt-hcis}
3051 The following three types are recognized:
3053 @table @option
3054 @item -bt hci,null
3055 (default) The corresponding Bluetooth HCI assumes no internal logic
3056 and will not respond to any HCI commands or emit events.
3058 @item -bt hci,host[:@var{id}]
3059 (@code{bluez} only) The corresponding HCI passes commands / events
3060 to / from the physical HCI identified by the name @var{id} (default:
3061 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
3062 capable systems like Linux.
3064 @item -bt hci[,vlan=@var{n}]
3065 Add a virtual, standard HCI that will participate in the Bluetooth
3066 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
3067 VLANs, devices inside a bluetooth network @var{n} can only communicate
3068 with other devices in the same network (scatternet).
3069 @end table
3071 @item -bt vhci[,vlan=@var{n}]
3072 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
3073 to the host bluetooth stack instead of to the emulated target. This
3074 allows the host and target machines to participate in a common scatternet
3075 and communicate. Requires the Linux @code{vhci} driver installed. Can
3076 be used as following:
3078 @example
3079 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
3080 @end example
3082 @item -bt device:@var{dev}[,vlan=@var{n}]
3083 Emulate a bluetooth device @var{dev} and place it in network @var{n}
3084 (default @code{0}). QEMU can only emulate one type of bluetooth devices
3085 currently:
3087 @table @option
3088 @item keyboard
3089 Virtual wireless keyboard implementing the HIDP bluetooth profile.
3090 @end table
3091 ETEXI
3093 STEXI
3094 @end table
3095 ETEXI
3096 DEFHEADING()
3098 #ifdef CONFIG_TPM
3099 DEFHEADING(TPM device options)
3101 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3102 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3103 " use path to provide path to a character device; default is /dev/tpm0\n"
3104 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3105 " not provided it will be searched for in /sys/class/misc/tpm?/device\n",
3106 QEMU_ARCH_ALL)
3107 STEXI
3109 The general form of a TPM device option is:
3110 @table @option
3112 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
3113 @findex -tpmdev
3114 Backend type must be:
3115 @option{passthrough}.
3117 The specific backend type will determine the applicable options.
3118 The @code{-tpmdev} option creates the TPM backend and requires a
3119 @code{-device} option that specifies the TPM frontend interface model.
3121 Options to each backend are described below.
3123 Use 'help' to print all available TPM backend types.
3124 @example
3125 qemu -tpmdev help
3126 @end example
3128 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
3130 (Linux-host only) Enable access to the host's TPM using the passthrough
3131 driver.
3133 @option{path} specifies the path to the host's TPM device, i.e., on
3134 a Linux host this would be @code{/dev/tpm0}.
3135 @option{path} is optional and by default @code{/dev/tpm0} is used.
3137 @option{cancel-path} specifies the path to the host TPM device's sysfs
3138 entry allowing for cancellation of an ongoing TPM command.
3139 @option{cancel-path} is optional and by default QEMU will search for the
3140 sysfs entry to use.
3142 Some notes about using the host's TPM with the passthrough driver:
3144 The TPM device accessed by the passthrough driver must not be
3145 used by any other application on the host.
3147 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3148 the VM's firmware (BIOS/UEFI) will not be able to initialize the
3149 TPM again and may therefore not show a TPM-specific menu that would
3150 otherwise allow the user to configure the TPM, e.g., allow the user to
3151 enable/disable or activate/deactivate the TPM.
3152 Further, if TPM ownership is released from within a VM then the host's TPM
3153 will get disabled and deactivated. To enable and activate the
3154 TPM again afterwards, the host has to be rebooted and the user is
3155 required to enter the firmware's menu to enable and activate the TPM.
3156 If the TPM is left disabled and/or deactivated most TPM commands will fail.
3158 To create a passthrough TPM use the following two options:
3159 @example
3160 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3161 @end example
3162 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3163 @code{tpmdev=tpm0} in the device option.
3165 @end table
3167 ETEXI
3169 DEFHEADING()
3171 #endif
3173 DEFHEADING(Linux/Multiboot boot specific)
3174 STEXI
3176 When using these options, you can use a given Linux or Multiboot
3177 kernel without installing it in the disk image. It can be useful
3178 for easier testing of various kernels.
3180 @table @option
3181 ETEXI
3183 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3184 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3185 STEXI
3186 @item -kernel @var{bzImage}
3187 @findex -kernel
3188 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3189 or in multiboot format.
3190 ETEXI
3192 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3193 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3194 STEXI
3195 @item -append @var{cmdline}
3196 @findex -append
3197 Use @var{cmdline} as kernel command line
3198 ETEXI
3200 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3201 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3202 STEXI
3203 @item -initrd @var{file}
3204 @findex -initrd
3205 Use @var{file} as initial ram disk.
3207 @item -initrd "@var{file1} arg=foo,@var{file2}"
3209 This syntax is only available with multiboot.
3211 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3212 first module.
3213 ETEXI
3215 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3216 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
3217 STEXI
3218 @item -dtb @var{file}
3219 @findex -dtb
3220 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3221 on boot.
3222 ETEXI
3224 STEXI
3225 @end table
3226 ETEXI
3227 DEFHEADING()
3229 DEFHEADING(Debug/Expert options)
3230 STEXI
3231 @table @option
3232 ETEXI
3234 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3235 "-fw_cfg [name=]<name>,file=<file>\n"
3236 " add named fw_cfg entry with contents from file\n"
3237 "-fw_cfg [name=]<name>,string=<str>\n"
3238 " add named fw_cfg entry with contents from string\n",
3239 QEMU_ARCH_ALL)
3240 STEXI
3242 @item -fw_cfg [name=]@var{name},file=@var{file}
3243 @findex -fw_cfg
3244 Add named fw_cfg entry with contents from file @var{file}.
3246 @item -fw_cfg [name=]@var{name},string=@var{str}
3247 Add named fw_cfg entry with contents from string @var{str}.
3249 The terminating NUL character of the contents of @var{str} will not be
3250 included as part of the fw_cfg item data. To insert contents with
3251 embedded NUL characters, you have to use the @var{file} parameter.
3253 The fw_cfg entries are passed by QEMU through to the guest.
3255 Example:
3256 @example
3257 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3258 @end example
3259 creates an fw_cfg entry named opt/com.mycompany/blob with contents
3260 from ./my_blob.bin.
3262 ETEXI
3264 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3265 "-serial dev redirect the serial port to char device 'dev'\n",
3266 QEMU_ARCH_ALL)
3267 STEXI
3268 @item -serial @var{dev}
3269 @findex -serial
3270 Redirect the virtual serial port to host character device
3271 @var{dev}. The default device is @code{vc} in graphical mode and
3272 @code{stdio} in non graphical mode.
3274 This option can be used several times to simulate up to 4 serial
3275 ports.
3277 Use @code{-serial none} to disable all serial ports.
3279 Available character devices are:
3280 @table @option
3281 @item vc[:@var{W}x@var{H}]
3282 Virtual console. Optionally, a width and height can be given in pixel with
3283 @example
3284 vc:800x600
3285 @end example
3286 It is also possible to specify width or height in characters:
3287 @example
3288 vc:80Cx24C
3289 @end example
3290 @item pty
3291 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3292 @item none
3293 No device is allocated.
3294 @item null
3295 void device
3296 @item chardev:@var{id}
3297 Use a named character device defined with the @code{-chardev} option.
3298 @item /dev/XXX
3299 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3300 parameters are set according to the emulated ones.
3301 @item /dev/parport@var{N}
3302 [Linux only, parallel port only] Use host parallel port
3303 @var{N}. Currently SPP and EPP parallel port features can be used.
3304 @item file:@var{filename}
3305 Write output to @var{filename}. No character can be read.
3306 @item stdio
3307 [Unix only] standard input/output
3308 @item pipe:@var{filename}
3309 name pipe @var{filename}
3310 @item COM@var{n}
3311 [Windows only] Use host serial port @var{n}
3312 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3313 This implements UDP Net Console.
3314 When @var{remote_host} or @var{src_ip} are not specified
3315 they default to @code{0.0.0.0}.
3316 When not using a specified @var{src_port} a random port is automatically chosen.
3318 If you just want a simple readonly console you can use @code{netcat} or
3319 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3320 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
3321 will appear in the netconsole session.
3323 If you plan to send characters back via netconsole or you want to stop
3324 and start QEMU a lot of times, you should have QEMU use the same
3325 source port each time by using something like @code{-serial
3326 udp::4555@@:4556} to QEMU. Another approach is to use a patched
3327 version of netcat which can listen to a TCP port and send and receive
3328 characters via udp. If you have a patched version of netcat which
3329 activates telnet remote echo and single char transfer, then you can
3330 use the following options to set up a netcat redirector to allow
3331 telnet on port 5555 to access the QEMU port.
3332 @table @code
3333 @item QEMU Options:
3334 -serial udp::4555@@:4556
3335 @item netcat options:
3336 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3337 @item telnet options:
3338 localhost 5555
3339 @end table
3341 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3342 The TCP Net Console has two modes of operation. It can send the serial
3343 I/O to a location or wait for a connection from a location. By default
3344 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3345 the @var{server} option QEMU will wait for a client socket application
3346 to connect to the port before continuing, unless the @code{nowait}
3347 option was specified. The @code{nodelay} option disables the Nagle buffering
3348 algorithm. The @code{reconnect} option only applies if @var{noserver} is
3349 set, if the connection goes down it will attempt to reconnect at the
3350 given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
3351 one TCP connection at a time is accepted. You can use @code{telnet} to
3352 connect to the corresponding character device.
3353 @table @code
3354 @item Example to send tcp console to 192.168.0.2 port 4444
3355 -serial tcp:192.168.0.2:4444
3356 @item Example to listen and wait on port 4444 for connection
3357 -serial tcp::4444,server
3358 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3359 -serial tcp:192.168.0.100:4444,server,nowait
3360 @end table
3362 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3363 The telnet protocol is used instead of raw tcp sockets. The options
3364 work the same as if you had specified @code{-serial tcp}. The
3365 difference is that the port acts like a telnet server or client using
3366 telnet option negotiation. This will also allow you to send the
3367 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3368 sequence. Typically in unix telnet you do it with Control-] and then
3369 type "send break" followed by pressing the enter key.
3371 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3372 A unix domain socket is used instead of a tcp socket. The option works the
3373 same as if you had specified @code{-serial tcp} except the unix domain socket
3374 @var{path} is used for connections.
3376 @item mon:@var{dev_string}
3377 This is a special option to allow the monitor to be multiplexed onto
3378 another serial port. The monitor is accessed with key sequence of
3379 @key{Control-a} and then pressing @key{c}.
3380 @var{dev_string} should be any one of the serial devices specified
3381 above. An example to multiplex the monitor onto a telnet server
3382 listening on port 4444 would be:
3383 @table @code
3384 @item -serial mon:telnet::4444,server,nowait
3385 @end table
3386 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3387 QEMU any more but will be passed to the guest instead.
3389 @item braille
3390 Braille device. This will use BrlAPI to display the braille output on a real
3391 or fake device.
3393 @item msmouse
3394 Three button serial mouse. Configure the guest to use Microsoft protocol.
3395 @end table
3396 ETEXI
3398 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3399 "-parallel dev redirect the parallel port to char device 'dev'\n",
3400 QEMU_ARCH_ALL)
3401 STEXI
3402 @item -parallel @var{dev}
3403 @findex -parallel
3404 Redirect the virtual parallel port to host device @var{dev} (same
3405 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3406 be used to use hardware devices connected on the corresponding host
3407 parallel port.
3409 This option can be used several times to simulate up to 3 parallel
3410 ports.
3412 Use @code{-parallel none} to disable all parallel ports.
3413 ETEXI
3415 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3416 "-monitor dev redirect the monitor to char device 'dev'\n",
3417 QEMU_ARCH_ALL)
3418 STEXI
3419 @item -monitor @var{dev}
3420 @findex -monitor
3421 Redirect the monitor to host device @var{dev} (same devices as the
3422 serial port).
3423 The default device is @code{vc} in graphical mode and @code{stdio} in
3424 non graphical mode.
3425 Use @code{-monitor none} to disable the default monitor.
3426 ETEXI
3427 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3428 "-qmp dev like -monitor but opens in 'control' mode\n",
3429 QEMU_ARCH_ALL)
3430 STEXI
3431 @item -qmp @var{dev}
3432 @findex -qmp
3433 Like -monitor but opens in 'control' mode.
3434 ETEXI
3435 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3436 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3437 QEMU_ARCH_ALL)
3438 STEXI
3439 @item -qmp-pretty @var{dev}
3440 @findex -qmp-pretty
3441 Like -qmp but uses pretty JSON formatting.
3442 ETEXI
3444 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
3445 "-mon [chardev=]name[,mode=readline|control]\n", QEMU_ARCH_ALL)
3446 STEXI
3447 @item -mon [chardev=]name[,mode=readline|control]
3448 @findex -mon
3449 Setup monitor on chardev @var{name}.
3450 ETEXI
3452 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
3453 "-debugcon dev redirect the debug console to char device 'dev'\n",
3454 QEMU_ARCH_ALL)
3455 STEXI
3456 @item -debugcon @var{dev}
3457 @findex -debugcon
3458 Redirect the debug console to host device @var{dev} (same devices as the
3459 serial port). The debug console is an I/O port which is typically port
3460 0xe9; writing to that I/O port sends output to this device.
3461 The default device is @code{vc} in graphical mode and @code{stdio} in
3462 non graphical mode.
3463 ETEXI
3465 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
3466 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
3467 STEXI
3468 @item -pidfile @var{file}
3469 @findex -pidfile
3470 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3471 from a script.
3472 ETEXI
3474 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
3475 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
3476 STEXI
3477 @item -singlestep
3478 @findex -singlestep
3479 Run the emulation in single step mode.
3480 ETEXI
3482 DEF("S", 0, QEMU_OPTION_S, \
3483 "-S freeze CPU at startup (use 'c' to start execution)\n",
3484 QEMU_ARCH_ALL)
3485 STEXI
3486 @item -S
3487 @findex -S
3488 Do not start CPU at startup (you must type 'c' in the monitor).
3489 ETEXI
3491 DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3492 "-realtime [mlock=on|off]\n"
3493 " run qemu with realtime features\n"
3494 " mlock=on|off controls mlock support (default: on)\n",
3495 QEMU_ARCH_ALL)
3496 STEXI
3497 @item -realtime mlock=on|off
3498 @findex -realtime
3499 Run qemu with realtime features.
3500 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3501 (enabled by default).
3502 ETEXI
3504 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
3505 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
3506 STEXI
3507 @item -gdb @var{dev}
3508 @findex -gdb
3509 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3510 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3511 stdio are reasonable use case. The latter is allowing to start QEMU from
3512 within gdb and establish the connection via a pipe:
3513 @example
3514 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3515 @end example
3516 ETEXI
3518 DEF("s", 0, QEMU_OPTION_s, \
3519 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3520 QEMU_ARCH_ALL)
3521 STEXI
3522 @item -s
3523 @findex -s
3524 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3525 (@pxref{gdb_usage}).
3526 ETEXI
3528 DEF("d", HAS_ARG, QEMU_OPTION_d, \
3529 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
3530 QEMU_ARCH_ALL)
3531 STEXI
3532 @item -d @var{item1}[,...]
3533 @findex -d
3534 Enable logging of specified items. Use '-d help' for a list of log items.
3535 ETEXI
3537 DEF("D", HAS_ARG, QEMU_OPTION_D, \
3538 "-D logfile output log to logfile (default stderr)\n",
3539 QEMU_ARCH_ALL)
3540 STEXI
3541 @item -D @var{logfile}
3542 @findex -D
3543 Output log in @var{logfile} instead of to stderr
3544 ETEXI
3546 DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3547 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3548 QEMU_ARCH_ALL)
3549 STEXI
3550 @item -dfilter @var{range1}[,...]
3551 @findex -dfilter
3552 Filter debug output to that relevant to a range of target addresses. The filter
3553 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3554 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3555 addresses and sizes required. For example:
3556 @example
3557 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3558 @end example
3559 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3560 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3561 block starting at 0xffffffc00005f000.
3562 ETEXI
3564 DEF("L", HAS_ARG, QEMU_OPTION_L, \
3565 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3566 QEMU_ARCH_ALL)
3567 STEXI
3568 @item -L @var{path}
3569 @findex -L
3570 Set the directory for the BIOS, VGA BIOS and keymaps.
3572 To list all the data directories, use @code{-L help}.
3573 ETEXI
3575 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
3576 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
3577 STEXI
3578 @item -bios @var{file}
3579 @findex -bios
3580 Set the filename for the BIOS.
3581 ETEXI
3583 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
3584 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
3585 STEXI
3586 @item -enable-kvm
3587 @findex -enable-kvm
3588 Enable KVM full virtualization support. This option is only available
3589 if KVM support is enabled when compiling.
3590 ETEXI
3592 DEF("enable-hax", 0, QEMU_OPTION_enable_hax, \
3593 "-enable-hax enable HAX virtualization support\n", QEMU_ARCH_I386)
3594 STEXI
3595 @item -enable-hax
3596 @findex -enable-hax
3597 Enable HAX (Hardware-based Acceleration eXecution) support. This option
3598 is only available if HAX support is enabled when compiling. HAX is only
3599 applicable to MAC and Windows platform, and thus does not conflict with
3600 KVM.
3601 ETEXI
3603 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
3604 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
3605 DEF("xen-create", 0, QEMU_OPTION_xen_create,
3606 "-xen-create create domain using xen hypercalls, bypassing xend\n"
3607 " warning: should not be used when xend is in use\n",
3608 QEMU_ARCH_ALL)
3609 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3610 "-xen-attach attach to existing xen domain\n"
3611 " xend will use this when starting QEMU\n",
3612 QEMU_ARCH_ALL)
3613 DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3614 "-xen-domid-restrict restrict set of available xen operations\n"
3615 " to specified domain id. (Does not affect\n"
3616 " xenpv machine type).\n",
3617 QEMU_ARCH_ALL)
3618 STEXI
3619 @item -xen-domid @var{id}
3620 @findex -xen-domid
3621 Specify xen guest domain @var{id} (XEN only).
3622 @item -xen-create
3623 @findex -xen-create
3624 Create domain using xen hypercalls, bypassing xend.
3625 Warning: should not be used when xend is in use (XEN only).
3626 @item -xen-attach
3627 @findex -xen-attach
3628 Attach to existing xen domain.
3629 xend will use this when starting QEMU (XEN only).
3630 @findex -xen-domid-restrict
3631 Restrict set of available xen operations to specified domain id (XEN only).
3632 ETEXI
3634 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
3635 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
3636 STEXI
3637 @item -no-reboot
3638 @findex -no-reboot
3639 Exit instead of rebooting.
3640 ETEXI
3642 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
3643 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
3644 STEXI
3645 @item -no-shutdown
3646 @findex -no-shutdown
3647 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3648 This allows for instance switching to monitor to commit changes to the
3649 disk image.
3650 ETEXI
3652 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3653 "-loadvm [tag|id]\n" \
3654 " start right away with a saved state (loadvm in monitor)\n",
3655 QEMU_ARCH_ALL)
3656 STEXI
3657 @item -loadvm @var{file}
3658 @findex -loadvm
3659 Start right away with a saved state (@code{loadvm} in monitor)
3660 ETEXI
3662 #ifndef _WIN32
3663 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
3664 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
3665 #endif
3666 STEXI
3667 @item -daemonize
3668 @findex -daemonize
3669 Daemonize the QEMU process after initialization. QEMU will not detach from
3670 standard IO until it is ready to receive connections on any of its devices.
3671 This option is a useful way for external programs to launch QEMU without having
3672 to cope with initialization race conditions.
3673 ETEXI
3675 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
3676 "-option-rom rom load a file, rom, into the option ROM space\n",
3677 QEMU_ARCH_ALL)
3678 STEXI
3679 @item -option-rom @var{file}
3680 @findex -option-rom
3681 Load the contents of @var{file} as an option ROM.
3682 This option is useful to load things like EtherBoot.
3683 ETEXI
3685 HXCOMM Silently ignored for compatibility
3686 DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
3688 HXCOMM Options deprecated by -rtc
3689 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3690 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
3692 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
3693 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \
3694 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3695 QEMU_ARCH_ALL)
3697 STEXI
3699 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3700 @findex -rtc
3701 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3702 UTC or local time, respectively. @code{localtime} is required for correct date in
3703 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3704 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3706 By default the RTC is driven by the host system time. This allows using of the
3707 RTC as accurate reference clock inside the guest, specifically if the host
3708 time is smoothly following an accurate external reference clock, e.g. via NTP.
3709 If you want to isolate the guest time from the host, you can set @option{clock}
3710 to @code{rt} instead. To even prevent it from progressing during suspension,
3711 you can set it to @code{vm}.
3713 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3714 specifically with Windows' ACPI HAL. This option will try to figure out how
3715 many timer interrupts were not processed by the Windows guest and will
3716 re-inject them.
3717 ETEXI
3719 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
3720 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
3721 " enable virtual instruction counter with 2^N clock ticks per\n" \
3722 " instruction, enable aligning the host and virtual clocks\n" \
3723 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
3724 STEXI
3725 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
3726 @findex -icount
3727 Enable virtual instruction counter. The virtual cpu will execute one
3728 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
3729 then the virtual cpu speed will be automatically adjusted to keep virtual
3730 time within a few seconds of real time.
3732 When the virtual cpu is sleeping, the virtual time will advance at default
3733 speed unless @option{sleep=on|off} is specified.
3734 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3735 instantly whenever the virtual cpu goes to sleep mode and will not advance
3736 if no timer is enabled. This behavior give deterministic execution times from
3737 the guest point of view.
3739 Note that while this option can give deterministic behavior, it does not
3740 provide cycle accurate emulation. Modern CPUs contain superscalar out of
3741 order cores with complex cache hierarchies. The number of instructions
3742 executed often has little or no correlation with actual performance.
3744 @option{align=on} will activate the delay algorithm which will try
3745 to synchronise the host clock and the virtual clock. The goal is to
3746 have a guest running at the real frequency imposed by the shift option.
3747 Whenever the guest clock is behind the host clock and if
3748 @option{align=on} is specified then we print a message to the user
3749 to inform about the delay.
3750 Currently this option does not work when @option{shift} is @code{auto}.
3751 Note: The sync algorithm will work for those shift values for which
3752 the guest clock runs ahead of the host clock. Typically this happens
3753 when the shift value is high (how high depends on the host machine).
3755 When @option{rr} option is specified deterministic record/replay is enabled.
3756 Replay log is written into @var{filename} file in record mode and
3757 read from this file in replay mode.
3759 Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3760 at the start of execution recording. In replay mode this option is used
3761 to load the initial VM state.
3762 ETEXI
3764 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
3765 "-watchdog model\n" \
3766 " enable virtual hardware watchdog [default=none]\n",
3767 QEMU_ARCH_ALL)
3768 STEXI
3769 @item -watchdog @var{model}
3770 @findex -watchdog
3771 Create a virtual hardware watchdog device. Once enabled (by a guest
3772 action), the watchdog must be periodically polled by an agent inside
3773 the guest or else the guest will be restarted. Choose a model for
3774 which your guest has drivers.
3776 The @var{model} is the model of hardware watchdog to emulate. Use
3777 @code{-watchdog help} to list available hardware models. Only one
3778 watchdog can be enabled for a guest.
3780 The following models may be available:
3781 @table @option
3782 @item ib700
3783 iBASE 700 is a very simple ISA watchdog with a single timer.
3784 @item i6300esb
3785 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3786 dual-timer watchdog.
3787 @item diag288
3788 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3789 (currently KVM only).
3790 @end table
3791 ETEXI
3793 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
3794 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
3795 " action when watchdog fires [default=reset]\n",
3796 QEMU_ARCH_ALL)
3797 STEXI
3798 @item -watchdog-action @var{action}
3799 @findex -watchdog-action
3801 The @var{action} controls what QEMU will do when the watchdog timer
3802 expires.
3803 The default is
3804 @code{reset} (forcefully reset the guest).
3805 Other possible actions are:
3806 @code{shutdown} (attempt to gracefully shutdown the guest),
3807 @code{poweroff} (forcefully poweroff the guest),
3808 @code{pause} (pause the guest),
3809 @code{debug} (print a debug message and continue), or
3810 @code{none} (do nothing).
3812 Note that the @code{shutdown} action requires that the guest responds
3813 to ACPI signals, which it may not be able to do in the sort of
3814 situations where the watchdog would have expired, and thus
3815 @code{-watchdog-action shutdown} is not recommended for production use.
3817 Examples:
3819 @table @code
3820 @item -watchdog i6300esb -watchdog-action pause
3821 @itemx -watchdog ib700
3822 @end table
3823 ETEXI
3825 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
3826 "-echr chr set terminal escape character instead of ctrl-a\n",
3827 QEMU_ARCH_ALL)
3828 STEXI
3830 @item -echr @var{numeric_ascii_value}
3831 @findex -echr
3832 Change the escape character used for switching to the monitor when using
3833 monitor and serial sharing. The default is @code{0x01} when using the
3834 @code{-nographic} option. @code{0x01} is equal to pressing
3835 @code{Control-a}. You can select a different character from the ascii
3836 control keys where 1 through 26 map to Control-a through Control-z. For
3837 instance you could use the either of the following to change the escape
3838 character to Control-t.
3839 @table @code
3840 @item -echr 0x14
3841 @itemx -echr 20
3842 @end table
3843 ETEXI
3845 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
3846 "-virtioconsole c\n" \
3847 " set virtio console\n", QEMU_ARCH_ALL)
3848 STEXI
3849 @item -virtioconsole @var{c}
3850 @findex -virtioconsole
3851 Set virtio console.
3853 This option is maintained for backward compatibility.
3855 Please use @code{-device virtconsole} for the new way of invocation.
3856 ETEXI
3858 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
3859 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
3860 STEXI
3861 @item -show-cursor
3862 @findex -show-cursor
3863 Show cursor.
3864 ETEXI
3866 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
3867 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
3868 STEXI
3869 @item -tb-size @var{n}
3870 @findex -tb-size
3871 Set TB size.
3872 ETEXI
3874 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
3875 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3876 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3877 "-incoming unix:socketpath\n" \
3878 " prepare for incoming migration, listen on\n" \
3879 " specified protocol and socket address\n" \
3880 "-incoming fd:fd\n" \
3881 "-incoming exec:cmdline\n" \
3882 " accept incoming migration on given file descriptor\n" \
3883 " or from given external command\n" \
3884 "-incoming defer\n" \
3885 " wait for the URI to be specified via migrate_incoming\n",
3886 QEMU_ARCH_ALL)
3887 STEXI
3888 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3889 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3890 @findex -incoming
3891 Prepare for incoming migration, listen on a given tcp port.
3893 @item -incoming unix:@var{socketpath}
3894 Prepare for incoming migration, listen on a given unix socket.
3896 @item -incoming fd:@var{fd}
3897 Accept incoming migration from a given filedescriptor.
3899 @item -incoming exec:@var{cmdline}
3900 Accept incoming migration as an output from specified external command.
3902 @item -incoming defer
3903 Wait for the URI to be specified via migrate_incoming. The monitor can
3904 be used to change settings (such as migration parameters) prior to issuing
3905 the migrate_incoming to allow the migration to begin.
3906 ETEXI
3908 DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3909 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3910 STEXI
3911 @item -only-migratable
3912 @findex -only-migratable
3913 Only allow migratable devices. Devices will not be allowed to enter an
3914 unmigratable state.
3915 ETEXI
3917 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
3918 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
3919 STEXI
3920 @item -nodefaults
3921 @findex -nodefaults
3922 Don't create default devices. Normally, QEMU sets the default devices like serial
3923 port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3924 CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3925 default devices.
3926 ETEXI
3928 #ifndef _WIN32
3929 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
3930 "-chroot dir chroot to dir just before starting the VM\n",
3931 QEMU_ARCH_ALL)
3932 #endif
3933 STEXI
3934 @item -chroot @var{dir}
3935 @findex -chroot
3936 Immediately before starting guest execution, chroot to the specified
3937 directory. Especially useful in combination with -runas.
3938 ETEXI
3940 #ifndef _WIN32
3941 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
3942 "-runas user change to user id user just before starting the VM\n",
3943 QEMU_ARCH_ALL)
3944 #endif
3945 STEXI
3946 @item -runas @var{user}
3947 @findex -runas
3948 Immediately before starting guest execution, drop root privileges, switching
3949 to the specified user.
3950 ETEXI
3952 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3953 "-prom-env variable=value\n"
3954 " set OpenBIOS nvram variables\n",
3955 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
3956 STEXI
3957 @item -prom-env @var{variable}=@var{value}
3958 @findex -prom-env
3959 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3960 ETEXI
3961 DEF("semihosting", 0, QEMU_OPTION_semihosting,
3962 "-semihosting semihosting mode\n",
3963 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3964 QEMU_ARCH_MIPS)
3965 STEXI
3966 @item -semihosting
3967 @findex -semihosting
3968 Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
3969 ETEXI
3970 DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
3971 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3972 " semihosting configuration\n",
3973 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3974 QEMU_ARCH_MIPS)
3975 STEXI
3976 @item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
3977 @findex -semihosting-config
3978 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
3979 @table @option
3980 @item target=@code{native|gdb|auto}
3981 Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3982 or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3983 during debug sessions and @code{native} otherwise.
3984 @item arg=@var{str1},arg=@var{str2},...
3985 Allows the user to pass input arguments, and can be used multiple times to build
3986 up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3987 command line is still supported for backward compatibility. If both the
3988 @code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3989 specified, the former is passed to semihosting as it always takes precedence.
3990 @end table
3991 ETEXI
3992 DEF("old-param", 0, QEMU_OPTION_old_param,
3993 "-old-param old param mode\n", QEMU_ARCH_ARM)
3994 STEXI
3995 @item -old-param
3996 @findex -old-param (ARM)
3997 Old param mode (ARM only).
3998 ETEXI
4000 DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
4001 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
4002 QEMU_ARCH_ALL)
4003 STEXI
4004 @item -sandbox @var{arg}
4005 @findex -sandbox
4006 Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
4007 disable it. The default is 'off'.
4008 ETEXI
4010 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
4011 "-readconfig <file>\n", QEMU_ARCH_ALL)
4012 STEXI
4013 @item -readconfig @var{file}
4014 @findex -readconfig
4015 Read device configuration from @var{file}. This approach is useful when you want to spawn
4016 QEMU process with many command line options but you don't want to exceed the command line
4017 character limit.
4018 ETEXI
4019 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
4020 "-writeconfig <file>\n"
4021 " read/write config file\n", QEMU_ARCH_ALL)
4022 STEXI
4023 @item -writeconfig @var{file}
4024 @findex -writeconfig
4025 Write device configuration to @var{file}. The @var{file} can be either filename to save
4026 command line and device configuration into file or dash @code{-}) character to print the
4027 output to stdout. This can be later used as input file for @code{-readconfig} option.
4028 ETEXI
4029 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
4030 "-nodefconfig\n"
4031 " do not load default config files at startup\n",
4032 QEMU_ARCH_ALL)
4033 STEXI
4034 @item -nodefconfig
4035 @findex -nodefconfig
4036 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
4037 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
4038 ETEXI
4039 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
4040 "-no-user-config\n"
4041 " do not load user-provided config files at startup\n",
4042 QEMU_ARCH_ALL)
4043 STEXI
4044 @item -no-user-config
4045 @findex -no-user-config
4046 The @code{-no-user-config} option makes QEMU not load any of the user-provided
4047 config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config
4048 files from @var{datadir}.
4049 ETEXI
4050 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
4051 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
4052 " specify tracing options\n",
4053 QEMU_ARCH_ALL)
4054 STEXI
4055 HXCOMM This line is not accurate, as some sub-options are backend-specific but
4056 HXCOMM HX does not support conditional compilation of text.
4057 @item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
4058 @findex -trace
4059 @include qemu-option-trace.texi
4060 ETEXI
4062 HXCOMM Internal use
4063 DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
4064 DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
4066 #ifdef __linux__
4067 DEF("enable-fips", 0, QEMU_OPTION_enablefips,
4068 "-enable-fips enable FIPS 140-2 compliance\n",
4069 QEMU_ARCH_ALL)
4070 #endif
4071 STEXI
4072 @item -enable-fips
4073 @findex -enable-fips
4074 Enable FIPS 140-2 compliance mode.
4075 ETEXI
4077 HXCOMM Deprecated by -machine accel=tcg property
4078 DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
4080 HXCOMM Deprecated by kvm-pit driver properties
4081 DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection,
4082 "", QEMU_ARCH_I386)
4084 HXCOMM Deprecated (ignored)
4085 DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386)
4087 HXCOMM Deprecated by -machine kernel_irqchip=on|off property
4088 DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386)
4090 HXCOMM Deprecated (ignored)
4091 DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL)
4093 DEF("msg", HAS_ARG, QEMU_OPTION_msg,
4094 "-msg timestamp[=on|off]\n"
4095 " change the format of messages\n"
4096 " on|off controls leading timestamps (default:on)\n",
4097 QEMU_ARCH_ALL)
4098 STEXI
4099 @item -msg timestamp[=on|off]
4100 @findex -msg
4101 prepend a timestamp to each log message.(default:on)
4102 ETEXI
4104 DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
4105 "-dump-vmstate <file>\n"
4106 " Output vmstate information in JSON format to file.\n"
4107 " Use the scripts/vmstate-static-checker.py file to\n"
4108 " check for possible regressions in migration code\n"
4109 " by comparing two such vmstate dumps.\n",
4110 QEMU_ARCH_ALL)
4111 STEXI
4112 @item -dump-vmstate @var{file}
4113 @findex -dump-vmstate
4114 Dump json-encoded vmstate information for current machine type to file
4115 in @var{file}
4116 ETEXI
4118 STEXI
4119 @end table
4120 ETEXI
4121 DEFHEADING()
4122 DEFHEADING(Generic object creation)
4123 STEXI
4124 @table @option
4125 ETEXI
4127 DEF("object", HAS_ARG, QEMU_OPTION_object,
4128 "-object TYPENAME[,PROP1=VALUE1,...]\n"
4129 " create a new object of type TYPENAME setting properties\n"
4130 " in the order they are specified. Note that the 'id'\n"
4131 " property must be set. These objects are placed in the\n"
4132 " '/objects' path.\n",
4133 QEMU_ARCH_ALL)
4134 STEXI
4135 @item -object @var{typename}[,@var{prop1}=@var{value1},...]
4136 @findex -object
4137 Create a new object of type @var{typename} setting properties
4138 in the order they are specified. Note that the 'id'
4139 property must be set. These objects are placed in the
4140 '/objects' path.
4142 @table @option
4144 @item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off}
4146 Creates a memory file backend object, which can be used to back
4147 the guest RAM with huge pages. The @option{id} parameter is a
4148 unique ID that will be used to reference this memory region
4149 when configuring the @option{-numa} argument. The @option{size}
4150 option provides the size of the memory region, and accepts
4151 common suffixes, eg @option{500M}. The @option{mem-path} provides
4152 the path to either a shared memory or huge page filesystem mount.
4153 The @option{share} boolean option determines whether the memory
4154 region is marked as private to QEMU, or shared. The latter allows
4155 a co-operating external process to access the QEMU memory region.
4157 @item -object rng-random,id=@var{id},filename=@var{/dev/random}
4159 Creates a random number generator backend which obtains entropy from
4160 a device on the host. The @option{id} parameter is a unique ID that
4161 will be used to reference this entropy backend from the @option{virtio-rng}
4162 device. The @option{filename} parameter specifies which file to obtain
4163 entropy from and if omitted defaults to @option{/dev/random}.
4165 @item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4167 Creates a random number generator backend which obtains entropy from
4168 an external daemon running on the host. The @option{id} parameter is
4169 a unique ID that will be used to reference this entropy backend from
4170 the @option{virtio-rng} device. The @option{chardev} parameter is
4171 the unique ID of a character device backend that provides the connection
4172 to the RNG daemon.
4174 @item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4176 Creates a TLS anonymous credentials object, which can be used to provide
4177 TLS support on network backends. The @option{id} parameter is a unique
4178 ID which network backends will use to access the credentials. The
4179 @option{endpoint} is either @option{server} or @option{client} depending
4180 on whether the QEMU network backend that uses the credentials will be
4181 acting as a client or as a server. If @option{verify-peer} is enabled
4182 (the default) then once the handshake is completed, the peer credentials
4183 will be verified, though this is a no-op for anonymous credentials.
4185 The @var{dir} parameter tells QEMU where to find the credential
4186 files. For server endpoints, this directory may contain a file
4187 @var{dh-params.pem} providing diffie-hellman parameters to use
4188 for the TLS server. If the file is missing, QEMU will generate
4189 a set of DH parameters at startup. This is a computationally
4190 expensive operation that consumes random pool entropy, so it is
4191 recommended that a persistent set of parameters be generated
4192 upfront and saved.
4194 @item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off},passwordid=@var{id}
4196 Creates a TLS anonymous credentials object, which can be used to provide
4197 TLS support on network backends. The @option{id} parameter is a unique
4198 ID which network backends will use to access the credentials. The
4199 @option{endpoint} is either @option{server} or @option{client} depending
4200 on whether the QEMU network backend that uses the credentials will be
4201 acting as a client or as a server. If @option{verify-peer} is enabled
4202 (the default) then once the handshake is completed, the peer credentials
4203 will be verified. With x509 certificates, this implies that the clients
4204 must be provided with valid client certificates too.
4206 The @var{dir} parameter tells QEMU where to find the credential
4207 files. For server endpoints, this directory may contain a file
4208 @var{dh-params.pem} providing diffie-hellman parameters to use
4209 for the TLS server. If the file is missing, QEMU will generate
4210 a set of DH parameters at startup. This is a computationally
4211 expensive operation that consumes random pool entropy, so it is
4212 recommended that a persistent set of parameters be generated
4213 upfront and saved.
4215 For x509 certificate credentials the directory will contain further files
4216 providing the x509 certificates. The certificates must be stored
4217 in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4218 @var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4219 @var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4221 For the @var{server-key.pem} and @var{client-key.pem} files which
4222 contain sensitive private keys, it is possible to use an encrypted
4223 version by providing the @var{passwordid} parameter. This provides
4224 the ID of a previously created @code{secret} object containing the
4225 password for decryption.
4227 @item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
4229 Interval @var{t} can't be 0, this filter batches the packet delivery: all
4230 packets arriving in a given interval on netdev @var{netdevid} are delayed
4231 until the end of the interval. Interval is in microseconds.
4232 @option{status} is optional that indicate whether the netfilter is
4233 on (enabled) or off (disabled), the default status for netfilter will be 'on'.
4235 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4237 @option{all}: the filter is attached both to the receive and the transmit
4238 queue of the netdev (default).
4240 @option{rx}: the filter is attached to the receive queue of the netdev,
4241 where it will receive packets sent to the netdev.
4243 @option{tx}: the filter is attached to the transmit queue of the netdev,
4244 where it will receive packets sent by the netdev.
4246 @item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
4248 filter-mirror on netdev @var{netdevid},mirror net packet to chardev
4249 @var{chardevid}
4251 @item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},
4252 outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
4254 filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
4255 @var{chardevid},and redirect indev's packet to filter.
4256 Create a filter-redirector we need to differ outdev id from indev id, id can not
4257 be the same. we can just use indev or outdev, but at least one of indev or outdev
4258 need to be specified.
4260 @item -object filter-rewriter,id=@var{id},netdev=@var{netdevid}[,queue=@var{all|rx|tx}]
4262 Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4263 secondary from primary to keep secondary tcp connection,and rewrite
4264 tcp packet to primary from secondary make tcp packet can be handled by
4265 client.
4267 usage:
4268 colo secondary:
4269 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4270 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4271 -object filter-rewriter,id=rew0,netdev=hn0,queue=all
4273 @item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
4275 Dump the network traffic on netdev @var{dev} to the file specified by
4276 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4277 The file format is libpcap, so it can be analyzed with tools such as tcpdump
4278 or Wireshark.
4280 @item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},
4281 outdev=@var{chardevid}
4283 Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4284 secondary packet. If the packets are same, we will output primary
4285 packet to outdev@var{chardevid}, else we will notify colo-frame
4286 do checkpoint and send primary packet to outdev@var{chardevid}.
4288 we must use it with the help of filter-mirror and filter-redirector.
4290 @example
4292 primary:
4293 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4294 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4295 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4296 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4297 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4298 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4299 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4300 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4301 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4302 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4303 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4304 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4306 secondary:
4307 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4308 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4309 -chardev socket,id=red0,host=3.3.3.3,port=9003
4310 -chardev socket,id=red1,host=3.3.3.3,port=9004
4311 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4312 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4314 @end example
4316 If you want to know the detail of above command line, you can read
4317 the colo-compare git log.
4319 @item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4321 Creates a cryptodev backend which executes crypto opreation from
4322 the QEMU cipher APIS. The @var{id} parameter is
4323 a unique ID that will be used to reference this cryptodev backend from
4324 the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4325 which specify the queue number of cryptodev backend, the default of
4326 @var{queues} is 1.
4328 @example
4330 # qemu-system-x86_64 \
4331 [...] \
4332 -object cryptodev-backend-builtin,id=cryptodev0 \
4333 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4334 [...]
4335 @end example
4337 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4338 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4340 Defines a secret to store a password, encryption key, or some other sensitive
4341 data. The sensitive data can either be passed directly via the @var{data}
4342 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4343 parameter is insecure unless the sensitive data is encrypted.
4345 The sensitive data can be provided in raw format (the default), or base64.
4346 When encoded as JSON, the raw format only supports valid UTF-8 characters,
4347 so base64 is recommended for sending binary data. QEMU will convert from
4348 which ever format is provided to the format it needs internally. eg, an
4349 RBD password can be provided in raw format, even though it will be base64
4350 encoded when passed onto the RBD sever.
4352 For added protection, it is possible to encrypt the data associated with
4353 a secret using the AES-256-CBC cipher. Use of encryption is indicated
4354 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4355 parameter provides the ID of a previously defined secret that contains
4356 the AES-256 decryption key. This key should be 32-bytes long and be
4357 base64 encoded. The @var{iv} parameter provides the random initialization
4358 vector used for encryption of this particular secret and should be a
4359 base64 encrypted string of the 16-byte IV.
4361 The simplest (insecure) usage is to provide the secret inline
4363 @example
4365 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4367 @end example
4369 The simplest secure usage is to provide the secret via a file
4371 # echo -n "letmein" > mypasswd.txt
4372 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4374 For greater security, AES-256-CBC should be used. To illustrate usage,
4375 consider the openssl command line tool which can encrypt the data. Note
4376 that when encrypting, the plaintext must be padded to the cipher block
4377 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4379 First a master key needs to be created in base64 encoding:
4381 @example
4382 # openssl rand -base64 32 > key.b64
4383 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4384 @end example
4386 Each secret to be encrypted needs to have a random initialization vector
4387 generated. These do not need to be kept secret
4389 @example
4390 # openssl rand -base64 16 > iv.b64
4391 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4392 @end example
4394 The secret to be defined can now be encrypted, in this case we're
4395 telling openssl to base64 encode the result, but it could be left
4396 as raw bytes if desired.
4398 @example
4399 # SECRET=$(echo -n "letmein" |
4400 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4401 @end example
4403 When launching QEMU, create a master secret pointing to @code{key.b64}
4404 and specify that to be used to decrypt the user password. Pass the
4405 contents of @code{iv.b64} to the second secret
4407 @example
4408 # $QEMU \
4409 -object secret,id=secmaster0,format=base64,file=key.b64 \
4410 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4411 data=$SECRET,iv=$(<iv.b64)
4412 @end example
4414 @end table
4416 ETEXI
4419 HXCOMM This is the last statement. Insert new options before this line!
4420 STEXI
4421 @end table
4422 ETEXI