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