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