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