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
7 HXCOMM HXCOMM can be used
for comments
, discarded from both texi and C
9 DEFHEADING(Standard options
)
14 DEF("help", 0, QEMU_OPTION_h
,
15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL
)
22 DEF("version", 0, QEMU_OPTION_version
,
23 "-version display version information and exit\n", QEMU_ARCH_ALL
)
27 Display version information and exit
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",
48 @item
-machine
[type
=]@
var{name
}[,prop
=@
var{value
}[,...]]
50 Select the emulated machine by @
var{name
}. Use @code
{-machine help
} to list
51 available machines
. Supported machine properties are
:
53 @item accel
=@
var{accels1
}[:@
var{accels2
}[:...]]
54 This is used to enable an accelerator
. Depending on the target architecture
,
55 kvm
, xen
, hax or tcg can be available
. By
default, tcg is used
. If there is
56 more than one accelerator specified
, the next one is used
if the previous one
58 @item kernel_irqchip
=on|off
59 Controls
in-kernel irqchip support
for the chosen accelerator when available
.
60 @item gfx_passthru
=on|off
61 Enables IGD GFX passthrough support
for the chosen machine when available
.
62 @item vmport
=on|off|auto
63 Enables emulation of VMWare IO port
, for vmmouse etc
. auto says to select the
64 value based on accel
. For accel
=xen the
default is off otherwise the
default
66 @item kvm_shadow_mem
=size
67 Defines the size of the KVM shadow MMU
.
68 @item dump
-guest
-core
=on|off
69 Include guest memory
in a core dump
. The
default is on
.
70 @item mem
-merge
=on|off
71 Enables or disables memory merge support
. This feature
, when supported by
72 the host
, de
-duplicates identical memory pages among VMs instances
74 @item aes
-key
-wrap
=on|off
75 Enables or disables AES key wrapping support on s390
-ccw hosts
. This feature
76 controls whether AES wrapping keys will be created to allow
77 execution of AES cryptographic functions
. The
default is on
.
78 @item dea
-key
-wrap
=on|off
79 Enables or disables DEA key wrapping support on s390
-ccw hosts
. This feature
80 controls whether DEA wrapping keys will be created to allow
81 execution of DEA cryptographic functions
. The
default is on
.
83 Enables or disables NVDIMM support
. The
default is off
.
87 HXCOMM Deprecated by
-machine
88 DEF("M", HAS_ARG
, QEMU_OPTION_M
, "", QEMU_ARCH_ALL
)
90 DEF("cpu", HAS_ARG
, QEMU_OPTION_cpu
,
91 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL
)
93 @item
-cpu @
var{model
}
95 Select CPU
model (@code
{-cpu help
} for list and additional feature selection
)
98 DEF("accel", HAS_ARG
, QEMU_OPTION_accel
,
99 "-accel [accel=]accelerator[,thread=single|multi]\n"
100 " select accelerator (kvm, xen, hax or tcg; use 'help' for a list)\n"
101 " thread=single|multi (enable multi-threaded TCG)", QEMU_ARCH_ALL
)
103 @item
-accel @
var{name
}[,prop
=@
var{value
}[,...]]
105 This is used to enable an accelerator
. Depending on the target architecture
,
106 kvm
, xen
, hax or tcg can be available
. By
default, tcg is used
. If there is
107 more than one accelerator specified
, the next one is used
if the previous one
110 @item thread
=single|multi
111 Controls number of TCG threads
. When the TCG is multi
-threaded there will be one
112 thread per vCPU therefor taking advantage of additional host cores
. The
default
113 is to enable multi
-threading where both the back
-end and front
-ends support it and
114 no incompatible TCG features have been
enabled (e
.g
. icount
/replay
).
118 DEF("smp", HAS_ARG
, QEMU_OPTION_smp
,
119 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
120 " set the number of CPUs to 'n' [default=1]\n"
121 " maxcpus= maximum number of total cpus, including\n"
122 " offline CPUs for hotplug, etc\n"
123 " cores= number of CPU cores on one socket\n"
124 " threads= number of threads on one CPU core\n"
125 " sockets= number of discrete sockets in the system\n",
128 @item
-smp
[cpus
=]@
var{n
}[,cores
=@
var{cores
}][,threads
=@
var{threads
}][,sockets
=@
var{sockets
}][,maxcpus
=@
var{maxcpus
}]
130 Simulate an SMP system with @
var{n
} CPUs
. On the PC target
, up to
255
131 CPUs are supported
. On Sparc32 target
, Linux limits the number of usable CPUs
133 For the PC target
, the number of @
var{cores
} per socket
, the number
134 of @
var{threads
} per cores and the total number of @
var{sockets
} can be
135 specified
. Missing values will be computed
. If any on the three values is
136 given
, the total number of CPUs @
var{n
} can be omitted
. @
var{maxcpus
}
137 specifies the maximum number of hotpluggable CPUs
.
140 DEF("numa", HAS_ARG
, QEMU_OPTION_numa
,
141 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
142 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
143 "-numa dist,src=source,dst=destination,val=distance\n", QEMU_ARCH_ALL
)
145 @item
-numa node
[,mem
=@
var{size
}][,cpus
=@
var{firstcpu
}[-@
var{lastcpu
}]][,nodeid
=@
var{node
}]
146 @itemx
-numa node
[,memdev
=@
var{id
}][,cpus
=@
var{firstcpu
}[-@
var{lastcpu
}]][,nodeid
=@
var{node
}]
147 @itemx
-numa dist
,src
=@
var{source
},dst
=@
var{destination
},val
=@
var{distance
}
148 @itemx
-numa cpu
,node
-id
=@
var{node
}[,socket
-id
=@
var{x
}][,core
-id
=@
var{y
}][,thread
-id
=@
var{z
}]
150 Define a NUMA node and assign RAM and VCPUs to it
.
151 Set the NUMA distance from a source node to a destination node
.
153 Legacy VCPU assignment uses @samp
{cpus
} option where
154 @
var{firstcpu
} and @
var{lastcpu
} are CPU indexes
. Each
155 @samp
{cpus
} option represent a contiguous range of CPU indexes
156 (or a single VCPU
if @
var{lastcpu
} is omitted
). A non
-contiguous
157 set of VCPUs can be represented by providing multiple @samp
{cpus
}
158 options
. If @samp
{cpus
} is omitted on all nodes
, VCPUs are automatically
161 For example
, the following option assigns VCPUs
0, 1, 2 and
5 to
164 -numa node
,cpus
=0-2,cpus
=5
167 @samp
{cpu
} option is a
new alternative to @samp
{cpus
} option
168 which uses @samp
{socket
-id|core
-id|thread
-id
} properties to assign
169 CPU objects to a @
var{node
} using topology layout properties of CPU
.
170 The set of properties is machine specific
, and depends on used
171 machine type
/@samp
{smp
} options
. It could be queried with
172 @samp
{hotpluggable
-cpus
} monitor command
.
173 @samp
{node
-id
} property specifies @
var{node
} to which CPU object
174 will be assigned
, it
's required for @var{node} to be declared
175 with @samp{node} option before it's used with @samp
{cpu
} option
.
180 -smp
1,sockets
=2,maxcpus
=2 \
181 -numa node
,nodeid
=0 -numa node
,nodeid
=1 \
182 -numa cpu
,node
-id
=0,socket
-id
=0 -numa cpu
,node
-id
=1,socket
-id
=1
185 @samp
{mem
} assigns a given RAM amount to a node
. @samp
{memdev
}
186 assigns RAM from a given memory backend device to a node
. If
187 @samp
{mem
} and @samp
{memdev
} are omitted
in all nodes
, RAM is
188 split equally between them
.
190 @samp
{mem
} and @samp
{memdev
} are mutually exclusive
. Furthermore
,
191 if one node uses @samp
{memdev
}, all of them have to use it
.
193 @
var{source
} and @
var{destination
} are NUMA node IDs
.
194 @
var{distance
} is the NUMA distance from @
var{source
} to @
var{destination
}.
195 The distance from a node to itself is always
10. If any pair of nodes is
196 given a distance
, then all pairs must be given distances
. Although
, when
197 distances are only given
in one direction
for each pair of nodes
, then
198 the distances
in the opposite directions are assumed to be the same
. If
,
199 however
, an asymmetrical pair of distances is given
for even one node
200 pair
, then all node pairs must be provided distance values
for both
201 directions
, even when they are symmetrical
. When a node is unreachable
202 from another node
, set the pair
's distance to 255.
204 Note that the -@option{numa} option doesn't allocate any of the
205 specified resources
, it just assigns existing resources to NUMA
206 nodes
. This means that one still has to use the @option
{-m
},
207 @option
{-smp
} options to allocate RAM and VCPUs respectively
.
211 DEF("add-fd", HAS_ARG
, QEMU_OPTION_add_fd
,
212 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
213 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL
)
215 @item
-add
-fd fd
=@
var{fd
},set
=@
var{set
}[,opaque
=@
var{opaque
}]
218 Add a file descriptor to an fd set
. Valid options are
:
222 This option defines the file descriptor of which a duplicate is added to fd set
.
223 The file descriptor cannot be stdin
, stdout
, or stderr
.
225 This option defines the ID of the fd set to add the file descriptor to
.
226 @item opaque
=@
var{opaque
}
227 This option defines a free
-form string that can be used to describe @
var{fd
}.
230 You can open an image
using pre
-opened file descriptors from an fd set
:
233 -add
-fd fd
=3,set
=2,opaque
="rdwr:/path/to/file"
234 -add
-fd fd
=4,set
=2,opaque
="rdonly:/path/to/file"
235 -drive file
=/dev
/fdset
/2,index
=0,media
=disk
239 DEF("set", HAS_ARG
, QEMU_OPTION_set
,
240 "-set group.id.arg=value\n"
241 " set <arg> parameter for item <id> of type <group>\n"
242 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL
)
244 @item
-set @
var{group
}.@
var{id
}.@
var{arg
}=@
var{value
}
246 Set parameter @
var{arg
} for item @
var{id
} of type @
var{group
}
249 DEF("global", HAS_ARG
, QEMU_OPTION_global
,
250 "-global driver.property=value\n"
251 "-global driver=driver,property=property,value=value\n"
252 " set a global default for a driver property\n",
255 @item
-global @
var{driver
}.@
var{prop
}=@
var{value
}
256 @itemx
-global driver
=@
var{driver
},property
=@
var{property
},value
=@
var{value
}
258 Set
default value of @
var{driver
}'s property @var{prop} to @var{value}, e.g.:
261 qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
264 In particular, you can use this to set driver properties for devices which are
265 created automatically by the machine model. To create a device which is not
266 created automatically and set properties on it, use -@option{device}.
268 -global @var{driver}.@var{prop}=@var{value} is shorthand for -global
269 driver=@var{driver},property=@var{prop},value=@var{value}. The
270 longhand syntax works even when @var{driver} contains a dot.
273 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
274 "-boot [order=drives][,once=drives][,menu=on|off]\n"
275 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
276 " 'drives
': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
277 " 'sp_name
': the file's name that would be passed to bios as logo picture
, if menu
=on
\n"
278 " 'sp_time': the period that splash picture last
if menu
=on
, unit is ms
\n"
279 " 'rb_timeout': the timeout before guest reboot when boot failed
, unit is ms
\n",
282 @item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}][,strict=on|off]
284 Specify boot order @var{drives} as a string of drive letters. Valid
285 drive letters depend on the target architecture. The x86 PC uses: a, b
286 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
287 from network adapter 1-4), hard disk boot is the default. To apply a
288 particular boot order only on the first startup, specify it via
289 @option{once}. Note that the @option{order} or @option{once} parameter
290 should not be used together with the @option{bootindex} property of
291 devices, since the firmware implementations normally do not support both
294 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
295 as firmware/BIOS supports them. The default is non-interactive boot.
297 A splash picture could be passed to bios, enabling user to show it as logo,
298 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
299 supports them. Currently Seabios for X86 system support it.
300 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
301 format(true color). The resolution should be supported by the SVGA mode, so
302 the recommended is 320x240, 640x480, 800x640.
304 A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
305 when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
306 reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
309 Do strict boot via @option{strict=on} as far as firmware/BIOS
310 supports it. This only effects when boot priority is changed by
311 bootindex options. The default is non-strict boot.
314 # try to boot from network first, then from hard disk
315 qemu-system-i386 -boot order=nc
316 # boot from CD-ROM first, switch back to default order after reboot
317 qemu-system-i386 -boot once=d
318 # boot with a splash picture for 5 seconds.
319 qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
322 Note: The legacy format '-boot @var{drives}' is still supported but its
323 use is discouraged as it may be removed from future versions.
326 DEF("m
", HAS_ARG, QEMU_OPTION_m,
327 "-m
[size
=]megs
[,slots
=n
,maxmem
=size
]\n"
328 " configure guest RAM
\n"
329 " size
: initial amount of guest memory
\n"
330 " slots
: number of hotplug
slots (default: none
)\n"
331 " maxmem
: maximum amount of guest
memory (default: none
)\n"
332 "NOTE
: Some architectures might enforce a specific granularity
\n",
335 @item -m [size=]@var{megs}[,slots=n,maxmem=size]
337 Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
338 Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
339 megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
340 could be used to set amount of hotpluggable memory slots and maximum amount of
341 memory. Note that @var{maxmem} must be aligned to the page size.
343 For example, the following command-line sets the guest startup RAM size to
344 1GB, creates 3 slots to hotplug additional memory and sets the maximum
345 memory the guest can reach to 4GB:
348 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
351 If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
352 be enabled and the guest startup RAM will never increase.
355 DEF("mem
-path
", HAS_ARG, QEMU_OPTION_mempath,
356 "-mem
-path FILE provide backing storage
for guest RAM
\n", QEMU_ARCH_ALL)
358 @item -mem-path @var{path}
360 Allocate guest RAM from a temporarily created file in @var{path}.
363 DEF("mem
-prealloc
", 0, QEMU_OPTION_mem_prealloc,
364 "-mem
-prealloc preallocate guest
memory (use with
-mem
-path
)\n",
368 @findex -mem-prealloc
369 Preallocate memory when using -mem-path.
372 DEF("k
", HAS_ARG, QEMU_OPTION_k,
373 "-k language use keyboard
layout (for example
'fr' for French
)\n",
376 @item -k @var{language}
378 Use keyboard layout @var{language} (for example @code{fr} for
379 French). This option is only needed where it is not easy to get raw PC
380 keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
381 display). You don't normally need to use it on PC/Linux or PC/Windows
384 The available layouts are:
386 ar de-ch es fo fr-ca hu ja mk no pt-br sv
387 da en-gb et fr fr-ch is lt nl pl ru th
388 de en-us fi fr-be hr it lv nl-be pt sl tr
391 The default is @code{en-us}.
395 DEF("audio
-help
", 0, QEMU_OPTION_audio_help,
396 "-audio
-help print list of audio drivers and their options
\n",
401 Will show the audio subsystem help: list of drivers, tunable
405 DEF("soundhw
", HAS_ARG, QEMU_OPTION_soundhw,
406 "-soundhw c1
,... enable audio support
\n"
407 " and only specified sound
cards (comma separated list
)\n"
408 " use
'-soundhw help' to get the list of supported cards
\n"
409 " use
'-soundhw all' to enable all of them
\n", QEMU_ARCH_ALL)
411 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
413 Enable audio and selected sound hardware. Use 'help' to print all
414 available sound hardware.
417 qemu-system-i386 -soundhw sb16,adlib disk.img
418 qemu-system-i386 -soundhw es1370 disk.img
419 qemu-system-i386 -soundhw ac97 disk.img
420 qemu-system-i386 -soundhw hda disk.img
421 qemu-system-i386 -soundhw all disk.img
422 qemu-system-i386 -soundhw help
425 Note that Linux's i810_audio OSS kernel (for AC97) module might
426 require manually specifying clocking.
429 modprobe i810_audio clocking=48000
433 DEF("balloon
", HAS_ARG, QEMU_OPTION_balloon,
434 "-balloon none disable balloon device
\n"
435 "-balloon virtio
[,addr
=str
]\n"
436 " enable virtio balloon
device (default)\n", QEMU_ARCH_ALL)
440 Disable balloon device.
441 @item -balloon virtio[,addr=@var{addr}]
442 Enable virtio balloon device (default), optionally with PCI address
446 DEF("device
", HAS_ARG, QEMU_OPTION_device,
447 "-device driver
[,prop
[=value
][,...]]\n"
448 " add
device (based on driver
)\n"
449 " prop
=value
,... sets driver properties
\n"
450 " use
'-device help' to print all possible drivers
\n"
451 " use
'-device driver,help' to print all possible properties
\n",
454 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
456 Add device @var{driver}. @var{prop}=@var{value} sets driver
457 properties. Valid properties depend on the driver. To get help on
458 possible drivers and properties, use @code{-device help} and
459 @code{-device @var{driver},help}.
462 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
464 Add an IPMI BMC. This is a simulation of a hardware management
465 interface processor that normally sits on a system. It provides
466 a watchdog and the ability to reset and power control the system.
467 You need to connect this to an IPMI interface to make it useful
469 The IPMI slave address to use for the BMC. The default is 0x20.
470 This address is the BMC's address on the I2C network of management
471 controllers. If you don't know what this means, it is safe to ignore
476 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
477 @item slave_addr=@var{val}
478 Define slave address to use for the BMC. The default is 0x20.
479 @item sdrfile=@var{file}
480 file containing raw Sensor Data Records (SDR) data. The default is none.
481 @item fruareasize=@var{val}
482 size of a Field Replaceable Unit (FRU) area. The default is 1024.
483 @item frudatafile=@var{file}
484 file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
487 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
489 Add a connection to an external IPMI BMC simulator. Instead of
490 locally emulating the BMC like the above item, instead connect
491 to an external entity that provides the IPMI services.
493 A connection is made to an external BMC simulator. If you do this, it
494 is strongly recommended that you use the "reconnect
=" chardev option
495 to reconnect to the simulator if the connection is lost. Note that if
496 this is not used carefully, it can be a security issue, as the
497 interface has the ability to send resets, NMIs, and power off the VM.
498 It's best if QEMU makes a connection to an external simulator running
499 on a secure port on localhost, so neither the simulator nor QEMU is
500 exposed to any outside network.
502 See the "lanserv
/README
.vm
" file in the OpenIPMI library for more
503 details on the external interface.
505 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
507 Add a KCS IPMI interafce on the ISA bus. This also adds a
508 corresponding ACPI and SMBIOS entries, if appropriate.
512 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
513 @item ioport=@var{val}
514 Define the I/O address of the interface. The default is 0xca0 for KCS.
516 Define the interrupt to use. The default is 5. To disable interrupts,
520 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
522 Like the KCS interface, but defines a BT interface. The default port is
523 0xe4 and the default interrupt is 5.
527 DEF("name
", HAS_ARG, QEMU_OPTION_name,
528 "-name string1
[,process
=string2
][,debug
-threads
=on|off
]\n"
529 " set the name of the guest
\n"
530 " string1 sets the window title and string2 the process
name (on Linux
)\n"
531 " When debug
-threads is enabled
, individual threads are given a separate
name (on Linux
)\n"
532 " NOTE
: The thread names are
for debugging and not a stable API
.\n",
535 @item -name @var{name}
537 Sets the @var{name} of the guest.
538 This name will be displayed in the SDL window caption.
539 The @var{name} will also be used for the VNC server.
540 Also optionally set the top visible process name in Linux.
541 Naming of individual threads can also be enabled on Linux to aid debugging.
544 DEF("uuid
", HAS_ARG, QEMU_OPTION_uuid,
545 "-uuid
%08x
-%04x
-%04x
-%04x
-%012x
\n"
546 " specify machine UUID
\n", QEMU_ARCH_ALL)
548 @item -uuid @var{uuid}
558 DEFHEADING(Block device options)
563 DEF("fda
", HAS_ARG, QEMU_OPTION_fda,
564 "-fda
/-fdb file use
'file' as floppy disk
0/1 image
\n", QEMU_ARCH_ALL)
565 DEF("fdb
", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
567 @item -fda @var{file}
568 @itemx -fdb @var{file}
571 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
574 DEF("hda
", HAS_ARG, QEMU_OPTION_hda,
575 "-hda
/-hdb file use
'file' as IDE hard disk
0/1 image
\n", QEMU_ARCH_ALL)
576 DEF("hdb
", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
577 DEF("hdc
", HAS_ARG, QEMU_OPTION_hdc,
578 "-hdc
/-hdd file use
'file' as IDE hard disk
2/3 image
\n", QEMU_ARCH_ALL)
579 DEF("hdd
", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
581 @item -hda @var{file}
582 @itemx -hdb @var{file}
583 @itemx -hdc @var{file}
584 @itemx -hdd @var{file}
589 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
592 DEF("cdrom
", HAS_ARG, QEMU_OPTION_cdrom,
593 "-cdrom file use
'file' as IDE cdrom
image (cdrom is ide1 master
)\n",
596 @item -cdrom @var{file}
598 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
599 @option{-cdrom} at the same time). You can use the host CD-ROM by
600 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
603 DEF("blockdev
", HAS_ARG, QEMU_OPTION_blockdev,
604 "-blockdev
[driver
=]driver
[,node
-name
=N
][,discard
=ignore|unmap
]\n"
605 " [,cache
.direct
=on|off
][,cache
.no
-flush
=on|off
]\n"
606 " [,read
-only
=on|off
][,detect
-zeroes
=on|off|unmap
]\n"
607 " [,driver specific parameters
...]\n"
608 " configure a block backend
\n", QEMU_ARCH_ALL)
610 DEF("drive
", HAS_ARG, QEMU_OPTION_drive,
611 "-drive
[file
=file
][,if=type
][,bus
=n
][,unit
=m
][,media
=d
][,index
=i
]\n"
612 " [,cyls
=c
,heads
=h
,secs
=s
[,trans
=t
]][,snapshot
=on|off
]\n"
613 " [,cache
=writethrough|writeback|none|directsync|unsafe
][,format
=f
]\n"
614 " [,serial
=s
][,addr
=A
][,rerror
=ignore|stop|report
]\n"
615 " [,werror
=ignore|stop|report|enospc
][,id
=name
][,aio
=threads|native
]\n"
616 " [,readonly
=on|off
][,copy
-on
-read
=on|off
]\n"
617 " [,discard
=ignore|unmap
][,detect
-zeroes
=on|off|unmap
]\n"
618 " [[,bps
=b
]|
[[,bps_rd
=r
][,bps_wr
=w
]]]\n"
619 " [[,iops
=i
]|
[[,iops_rd
=r
][,iops_wr
=w
]]]\n"
620 " [[,bps_max
=bm
]|
[[,bps_rd_max
=rm
][,bps_wr_max
=wm
]]]\n"
621 " [[,iops_max
=im
]|
[[,iops_rd_max
=irm
][,iops_wr_max
=iwm
]]]\n"
622 " [[,iops_size
=is
]]\n"
624 " use
'file' as a drive image
\n", QEMU_ARCH_ALL)
626 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
629 Define a new drive. Valid options are:
632 @item file=@var{file}
633 This option defines which disk image (@pxref{disk_images}) to use with
634 this drive. If the filename contains comma, you must double it
635 (for instance, "file
=my
,,file
" to use file "my
,file
").
637 Special files such as iSCSI devices can be specified using protocol
638 specific URLs. See the section for "Device URL Syntax
" for more information.
639 @item if=@var{interface}
640 This option defines on which type on interface the drive is connected.
641 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
642 @item bus=@var{bus},unit=@var{unit}
643 These options define where is connected the drive by defining the bus number and
645 @item index=@var{index}
646 This option defines where is connected the drive by using an index in the list
647 of available connectors of a given interface type.
648 @item media=@var{media}
649 This option defines the type of the media: disk or cdrom.
650 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
651 These options have the same definition as they have in @option{-hdachs}.
652 @item snapshot=@var{snapshot}
653 @var{snapshot} is "on
" or "off
" and controls snapshot mode for the given drive
654 (see @option{-snapshot}).
655 @item cache=@var{cache}
656 @var{cache} is "none
", "writeback
", "unsafe
", "directsync
" or "writethrough
" and controls how the host cache is used to access block data.
658 @var{aio} is "threads
", or "native
" and selects between pthread based disk I/O and native Linux AIO.
659 @item discard=@var{discard}
660 @var{discard} is one of "ignore
" (or "off
") or "unmap
" (or "on
") and controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are ignored or passed to the filesystem. Some machine types may not support discard requests.
661 @item format=@var{format}
662 Specify which disk @var{format} will be used rather than detecting
663 the format. Can be used to specify format=raw to avoid interpreting
664 an untrusted format header.
665 @item serial=@var{serial}
666 This option specifies the serial number to assign to the device.
667 @item addr=@var{addr}
668 Specify the controller's PCI address (if=virtio only).
669 @item werror=@var{action},rerror=@var{action}
670 Specify which @var{action} to take on write and read errors. Valid actions are:
671 "ignore
" (ignore the error and try to continue), "stop
" (pause QEMU),
672 "report
" (report the error to the guest), "enospc
" (pause QEMU only if the
673 host disk is full; report the error to the guest otherwise).
674 The default setting is @option{werror=enospc} and @option{rerror=report}.
676 Open drive @option{file} as read-only. Guest write attempts will fail.
677 @item copy-on-read=@var{copy-on-read}
678 @var{copy-on-read} is "on
" or "off
" and enables whether to copy read backing
679 file sectors into the image file.
680 @item detect-zeroes=@var{detect-zeroes}
681 @var{detect-zeroes} is "off
", "on
" or "unmap
" and enables the automatic
682 conversion of plain zero writes by the OS to driver specific optimized
683 zero write commands. You may even choose "unmap
" if @var{discard} is set
684 to "unmap
" to allow a zero write to be converted to an UNMAP operation.
685 @item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
686 Specify bandwidth throttling limits in bytes per second, either for all request
687 types or for reads or writes only. Small values can lead to timeouts or hangs
688 inside the guest. A safe minimum for disks is 2 MB/s.
689 @item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
690 Specify bursts in bytes per second, either for all request types or for reads
691 or writes only. Bursts allow the guest I/O to spike above the limit
693 @item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
694 Specify request rate limits in requests per second, either for all request
695 types or for reads or writes only.
696 @item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
697 Specify bursts in requests per second, either for all request types or for reads
698 or writes only. Bursts allow the guest I/O to spike above the limit
700 @item iops_size=@var{is}
701 Let every @var{is} bytes of a request count as a new request for iops
702 throttling purposes. Use this option to prevent guests from circumventing iops
703 limits by sending fewer but larger requests.
705 Join a throttling quota group with given name @var{g}. All drives that are
706 members of the same group are accounted for together. Use this option to
707 prevent guests from circumventing throttling limits by using many small disks
708 instead of a single larger disk.
711 By default, the @option{cache=writeback} mode is used. It will report data
712 writes as completed as soon as the data is present in the host page cache.
713 This is safe as long as your guest OS makes sure to correctly flush disk caches
714 where needed. If your guest OS does not handle volatile disk write caches
715 correctly and your host crashes or loses power, then the guest may experience
718 For such guests, you should consider using @option{cache=writethrough}. This
719 means that the host page cache will be used to read and write data, but write
720 notification will be sent to the guest only after QEMU has made sure to flush
721 each write to the disk. Be aware that this has a major impact on performance.
723 The host page cache can be avoided entirely with @option{cache=none}. This will
724 attempt to do disk IO directly to the guest's memory. QEMU may still perform
725 an internal copy of the data. Note that this is considered a writeback mode and
726 the guest OS must handle the disk write cache correctly in order to avoid data
727 corruption on host crashes.
729 The host page cache can be avoided while only sending write notifications to
730 the guest when the data has been flushed to the disk using
731 @option{cache=directsync}.
733 In case you don't care about data integrity over host failures, use
734 @option{cache=unsafe}. This option tells QEMU that it never needs to write any
735 data to the disk but can instead keep things in cache. If anything goes wrong,
736 like your host losing power, the disk storage getting disconnected accidentally,
737 etc. your image will most probably be rendered unusable. When using
738 the @option{-snapshot} option, unsafe caching is always used.
740 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
741 useful when the backing file is over a slow network. By default copy-on-read
744 Instead of @option{-cdrom} you can use:
746 qemu-system-i386 -drive file=file,index=2,media=cdrom
749 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
752 qemu-system-i386 -drive file=file,index=0,media=disk
753 qemu-system-i386 -drive file=file,index=1,media=disk
754 qemu-system-i386 -drive file=file,index=2,media=disk
755 qemu-system-i386 -drive file=file,index=3,media=disk
758 You can open an image using pre-opened file descriptors from an fd set:
761 -add-fd fd=3,set=2,opaque="rdwr
:/path
/to
/file
"
762 -add-fd fd=4,set=2,opaque="rdonly
:/path
/to
/file
"
763 -drive file=/dev/fdset/2,index=0,media=disk
766 You can connect a CDROM to the slave of ide0:
768 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
771 If you don't specify the "file
=" argument, you define an empty drive:
773 qemu-system-i386 -drive if=ide,index=1,media=cdrom
776 Instead of @option{-fda}, @option{-fdb}, you can use:
778 qemu-system-i386 -drive file=file,index=0,if=floppy
779 qemu-system-i386 -drive file=file,index=1,if=floppy
782 By default, @var{interface} is "ide
" and @var{index} is automatically
785 qemu-system-i386 -drive file=a -drive file=b"
789 qemu
-system
-i386
-hda a
-hdb b
793 DEF("mtdblock", HAS_ARG
, QEMU_OPTION_mtdblock
,
794 "-mtdblock file use 'file' as on-board Flash memory image\n",
797 @item
-mtdblock @
var{file
}
799 Use @
var{file
} as on
-board Flash memory image
.
802 DEF("sd", HAS_ARG
, QEMU_OPTION_sd
,
803 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL
)
807 Use @
var{file
} as SecureDigital card image
.
810 DEF("pflash", HAS_ARG
, QEMU_OPTION_pflash
,
811 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL
)
813 @item
-pflash @
var{file
}
815 Use @
var{file
} as a parallel flash image
.
818 DEF("snapshot", 0, QEMU_OPTION_snapshot
,
819 "-snapshot write to temporary files instead of disk image files\n",
824 Write to temporary files instead of disk image files
. In
this case,
825 the raw disk image you use is not written back
. You can however force
826 the write back by pressing @key
{C
-a s
} (@pxref
{disk_images
}).
829 DEF("hdachs", HAS_ARG
, QEMU_OPTION_hdachs
, \
830 "-hdachs c,h,s[,t]\n" \
831 " force hard disk 0 physical geometry and the optional BIOS\n" \
832 " translation (t=none or lba) (usually QEMU can guess them)\n",
835 @item
-hdachs @
var{c
},@
var{h
},@
var{s
},[,@
var{t
}]
837 Force hard disk
0 physical
geometry (1 <= @
var{c
} <= 16383, 1 <=
838 @
var{h
} <= 16, 1 <= @
var{s
} <= 63) and optionally force the BIOS
839 translation
mode (@
var{t
}=none
, lba or auto
). Usually QEMU can guess
840 all those parameters
. This option is deprecated
, please use
841 @code
{-device ide
-hd
,cyls
=c
,heads
=h
,secs
=s
,...} instead
.
844 DEF("fsdev", HAS_ARG
, QEMU_OPTION_fsdev
,
845 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
846 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n"
847 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
848 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
849 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
850 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
851 " [[,throttling.iops-size=is]]\n",
856 @item
-fsdev @
var{fsdriver
},id
=@
var{id
},path
=@
var{path
},[security_model
=@
var{security_model
}][,writeout
=@
var{writeout
}][,readonly
][,socket
=@
var{socket
}|sock_fd
=@
var{sock_fd
}]
858 Define a
new file system device
. Valid options are
:
861 This option specifies the fs driver backend to use
.
862 Currently
"local", "handle" and
"proxy" file system drivers are supported
.
864 Specifies identifier
for this device
865 @item path
=@
var{path
}
866 Specifies the export path
for the file system device
. Files under
867 this path will be available to the
9p client on the guest
.
868 @item security_model
=@
var{security_model
}
869 Specifies the security model to be used
for this export path
.
870 Supported security models are
"passthrough", "mapped-xattr", "mapped-file" and
"none".
871 In
"passthrough" security model
, files are stored
using the same
872 credentials as they are created on the guest
. This requires QEMU
873 to run as root
. In
"mapped-xattr" security model
, some of the file
874 attributes like uid
, gid
, mode bits and link target are stored as
875 file attributes
. For
"mapped-file" these attributes are stored
in the
876 hidden
.virtfs_metadata directory
. Directories exported by
this security model cannot
877 interact with other unix tools
. "none" security model is same as
878 passthrough except the sever won
't report failures if it fails to
879 set file attributes like ownership. Security model is mandatory
880 only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
881 security model as a parameter
.
882 @item writeout
=@
var{writeout
}
883 This is an optional argument
. The only supported value is
"immediate".
884 This means that host page cache will be used to read and write data but
885 write notification will be sent to the guest only when the data has been
886 reported as written by the storage subsystem
.
888 Enables exporting
9p share as a readonly mount
for guests
. By
default
889 read
-write access is given
.
890 @item socket
=@
var{socket
}
891 Enables proxy filesystem driver to use passed socket file
for communicating
892 with virtfs
-proxy
-helper
893 @item sock_fd
=@
var{sock_fd
}
894 Enables proxy filesystem driver to use passed socket descriptor
for
895 communicating with virtfs
-proxy
-helper
. Usually a helper like libvirt
896 will create socketpair and pass one of the fds as sock_fd
899 -fsdev option is used along with
-device driver
"virtio-9p-pci".
900 @item
-device virtio
-9p
-pci
,fsdev
=@
var{id
},mount_tag
=@
var{mount_tag
}
901 Options
for virtio
-9p
-pci driver are
:
904 Specifies the id value specified along with
-fsdev option
905 @item mount_tag
=@
var{mount_tag
}
906 Specifies the tag name to be used by the guest to mount
this export point
911 DEF("virtfs", HAS_ARG
, QEMU_OPTION_virtfs
,
912 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
913 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
918 @item
-virtfs @
var{fsdriver
}[,path
=@
var{path
}],mount_tag
=@
var{mount_tag
}[,security_model
=@
var{security_model
}][,writeout
=@
var{writeout
}][,readonly
][,socket
=@
var{socket
}|sock_fd
=@
var{sock_fd
}]
921 The general form of a Virtual File system pass
-through options are
:
924 This option specifies the fs driver backend to use
.
925 Currently
"local", "handle" and
"proxy" file system drivers are supported
.
927 Specifies identifier
for this device
928 @item path
=@
var{path
}
929 Specifies the export path
for the file system device
. Files under
930 this path will be available to the
9p client on the guest
.
931 @item security_model
=@
var{security_model
}
932 Specifies the security model to be used
for this export path
.
933 Supported security models are
"passthrough", "mapped-xattr", "mapped-file" and
"none".
934 In
"passthrough" security model
, files are stored
using the same
935 credentials as they are created on the guest
. This requires QEMU
936 to run as root
. In
"mapped-xattr" security model
, some of the file
937 attributes like uid
, gid
, mode bits and link target are stored as
938 file attributes
. For
"mapped-file" these attributes are stored
in the
939 hidden
.virtfs_metadata directory
. Directories exported by
this security model cannot
940 interact with other unix tools
. "none" security model is same as
941 passthrough except the sever won
't report failures if it fails to
942 set file attributes like ownership. Security model is mandatory only
943 for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
944 model as a parameter
.
945 @item writeout
=@
var{writeout
}
946 This is an optional argument
. The only supported value is
"immediate".
947 This means that host page cache will be used to read and write data but
948 write notification will be sent to the guest only when the data has been
949 reported as written by the storage subsystem
.
951 Enables exporting
9p share as a readonly mount
for guests
. By
default
952 read
-write access is given
.
953 @item socket
=@
var{socket
}
954 Enables proxy filesystem driver to use passed socket file
for
955 communicating with virtfs
-proxy
-helper
. Usually a helper like libvirt
956 will create socketpair and pass one of the fds as sock_fd
958 Enables proxy filesystem driver to use passed
'sock_fd' as the socket
959 descriptor
for interfacing with virtfs
-proxy
-helper
963 DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth
,
964 "-virtfs_synth Create synthetic file system image\n",
968 @findex
-virtfs_synth
969 Create synthetic file system image
977 DEFHEADING(USB options
)
982 DEF("usb", 0, QEMU_OPTION_usb
,
983 "-usb enable the USB driver (if it is not used by default yet)\n",
988 Enable the USB
driver (if it is not used by
default yet
).
991 DEF("usbdevice", HAS_ARG
, QEMU_OPTION_usbdevice
,
992 "-usbdevice name add the host or guest USB device 'name'\n",
996 @item
-usbdevice @
var{devname
}
998 Add the USB device @
var{devname
}. Note that
this option is deprecated
,
999 please use @code
{-device usb
-...} instead
. @xref
{usb_devices
}.
1004 Virtual Mouse
. This will
override the PS
/2 mouse emulation when activated
.
1007 Pointer device that uses absolute
coordinates (like a touchscreen
). This
1008 means QEMU is able to report the mouse position without having to grab the
1009 mouse
. Also overrides the PS
/2 mouse emulation when activated
.
1011 @item disk
:[format
=@
var{format
}]:@
var{file
}
1012 Mass storage device based on file
. The optional @
var{format
} argument
1013 will be used rather than detecting the format
. Can be used to specify
1014 @code
{format
=raw
} to avoid interpreting an untrusted format header
.
1016 @item host
:@
var{bus
}.@
var{addr
}
1017 Pass through the host device identified by @
var{bus
}.@
var{addr
} (Linux only
).
1019 @item host
:@
var{vendor_id
}:@
var{product_id
}
1020 Pass through the host device identified by @
var{vendor_id
}:@
var{product_id
}
1023 @item serial
:[vendorid
=@
var{vendor_id
}][,productid
=@
var{product_id
}]:@
var{dev
}
1024 Serial converter to host character device @
var{dev
}, see @code
{-serial
} for the
1028 Braille device
. This will use BrlAPI to display the braille output on a real
1031 @item net
:@
var{options
}
1032 Network adapter that supports CDC ethernet and RNDIS protocols
.
1042 DEFHEADING(Display options
)
1047 DEF("display", HAS_ARG
, QEMU_OPTION_display
,
1048 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
1049 " [,window_close=on|off][,gl=on|off]\n"
1050 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1051 "-display vnc=<display>[,<optargs>]\n"
1054 " select display type\n"
1055 "The default display is equivalent to\n"
1056 #
if defined(CONFIG_GTK
)
1057 "\t\"-display gtk\"\n"
1058 #elif
defined(CONFIG_SDL
)
1059 "\t\"-display sdl\"\n"
1060 #elif
defined(CONFIG_COCOA
)
1061 "\t\"-display cocoa\"\n"
1062 #elif
defined(CONFIG_VNC
)
1063 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1065 "\t\"-display none\"\n"
1069 @item
-display @
var{type
}
1071 Select type of display to use
. This option is a replacement
for the
1072 old style
-sdl
/-curses
/... options
. Valid values
for @
var{type
} are
1075 Display video output via
SDL (usually
in a separate graphics
1076 window
; see the SDL documentation
for other possibilities
).
1078 Display video output via curses
. For graphics device models which
1079 support a text mode
, QEMU can display
this output
using a
1080 curses
/ncurses
interface. Nothing is displayed when the graphics
1081 device is
in graphical mode or
if the graphics device does not support
1082 a text mode
. Generally only the VGA device models support text mode
.
1084 Do not display video output
. The guest will still see an emulated
1085 graphics card
, but its output will not be displayed to the QEMU
1086 user
. This option differs from the
-nographic option
in that it
1087 only affects what is done with video output
; -nographic also changes
1088 the destination of the serial and parallel port data
.
1090 Display video output
in a GTK window
. This
interface provides drop
-down
1091 menus and other UI elements to configure and control the VM during
1094 Start a VNC server on display
<arg
>
1098 DEF("nographic", 0, QEMU_OPTION_nographic
,
1099 "-nographic disable graphical output and redirect serial I/Os to console\n",
1104 Normally
, if QEMU is compiled with graphical window support
, it displays
1105 output such as guest graphics
, guest console
, and the QEMU monitor
in a
1106 window
. With
this option
, you can totally disable graphical output so
1107 that QEMU is a simple command line application
. The emulated serial port
1108 is redirected on the console and muxed with the
monitor (unless
1109 redirected elsewhere explicitly
). Therefore
, you can still use QEMU to
1110 debug a Linux kernel with a serial console
. Use @key
{C
-a h
} for help on
1111 switching between the console and monitor
.
1114 DEF("curses", 0, QEMU_OPTION_curses
,
1115 "-curses shorthand for -display curses\n",
1120 Normally
, if QEMU is compiled with graphical window support
, it displays
1121 output such as guest graphics
, guest console
, and the QEMU monitor
in a
1122 window
. With
this option
, QEMU can display the VGA output when
in text
1123 mode
using a curses
/ncurses
interface. Nothing is displayed
in graphical
1127 DEF("no-frame", 0, QEMU_OPTION_no_frame
,
1128 "-no-frame open SDL window without a frame and window decorations\n",
1133 Do not use decorations
for SDL windows and start them
using the whole
1134 available screen space
. This makes the
using QEMU
in a dedicated desktop
1135 workspace more convenient
.
1138 DEF("alt-grab", 0, QEMU_OPTION_alt_grab
,
1139 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1144 Use Ctrl
-Alt
-Shift to grab
mouse (instead of Ctrl
-Alt
). Note that
this also
1145 affects the special
keys (for fullscreen
, monitor
-mode switching
, etc
).
1148 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab
,
1149 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1154 Use Right
-Ctrl to grab
mouse (instead of Ctrl
-Alt
). Note that
this also
1155 affects the special
keys (for fullscreen
, monitor
-mode switching
, etc
).
1158 DEF("no-quit", 0, QEMU_OPTION_no_quit
,
1159 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL
)
1163 Disable SDL window close capability
.
1166 DEF("sdl", 0, QEMU_OPTION_sdl
,
1167 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL
)
1174 DEF("spice", HAS_ARG
, QEMU_OPTION_spice
,
1175 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1176 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1177 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
1178 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
1179 " [,tls-ciphers=<list>]\n"
1180 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1181 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1182 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1183 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1184 " [,jpeg-wan-compression=[auto|never|always]]\n"
1185 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1186 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
1187 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1188 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
1189 " [,gl=[on|off]][,rendernode=<file>]\n"
1191 " at least one of {port, tls-port} is mandatory\n",
1194 @item
-spice @
var{option
}[,@
var{option
}[,...]]
1196 Enable the spice remote desktop protocol
. Valid options are
1201 Set the TCP port spice is listening on
for plaintext channels
.
1204 Set the IP address spice is listening on
. Default is any address
.
1209 Force
using the specified IP version
.
1211 @item password
=<secret
>
1212 Set the password you need to authenticate
.
1215 Require that the client use SASL to authenticate with the spice
.
1216 The exact choice of authentication method used is controlled from the
1217 system
/ user
's SASL configuration file for the 'qemu
' service. This
1218 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1219 unprivileged user, an environment variable SASL_CONF_PATH can be used
1220 to make it search alternate locations for the service config.
1221 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1222 it is recommended that SASL always be combined with the 'tls
' and
1223 'x509
' settings to enable use of SSL and server certificates. This
1224 ensures a data encryption preventing compromise of authentication
1227 @item disable-ticketing
1228 Allow client connects without authentication.
1230 @item disable-copy-paste
1231 Disable copy paste between the client and the guest.
1233 @item disable-agent-file-xfer
1234 Disable spice-vdagent based file-xfer between the client and the guest.
1237 Set the TCP port spice is listening on for encrypted channels.
1239 @item x509-dir=<dir>
1240 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1242 @item x509-key-file=<file>
1243 @itemx x509-key-password=<file>
1244 @itemx x509-cert-file=<file>
1245 @itemx x509-cacert-file=<file>
1246 @itemx x509-dh-key-file=<file>
1247 The x509 file names can also be configured individually.
1249 @item tls-ciphers=<list>
1250 Specify which ciphers to use.
1252 @item tls-channel=[main|display|cursor|inputs|record|playback]
1253 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
1254 Force specific channel to be used with or without TLS encryption. The
1255 options can be specified multiple times to configure multiple
1256 channels. The special name "default" can be used to set the default
1257 mode. For channels which are not explicitly forced into one mode the
1258 spice client is allowed to pick tls/plaintext as he pleases.
1260 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1261 Configure image compression (lossless).
1262 Default is auto_glz.
1264 @item jpeg-wan-compression=[auto|never|always]
1265 @itemx zlib-glz-wan-compression=[auto|never|always]
1266 Configure wan image compression (lossy for slow links).
1269 @item streaming-video=[off|all|filter]
1270 Configure video stream detection. Default is off.
1272 @item agent-mouse=[on|off]
1273 Enable/disable passing mouse events via vdagent. Default is on.
1275 @item playback-compression=[on|off]
1276 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1278 @item seamless-migration=[on|off]
1279 Enable/disable spice seamless migration. Default is off.
1282 Enable/disable OpenGL context. Default is off.
1284 @item rendernode=<file>
1285 DRM render node for OpenGL rendering. If not specified, it will pick
1286 the first available. (Since 2.9)
1291 DEF("portrait", 0, QEMU_OPTION_portrait,
1292 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1297 Rotate graphical output 90 deg left (only PXA LCD).
1300 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1301 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1304 @item -rotate @var{deg}
1306 Rotate graphical output some deg left (only PXA LCD).
1309 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
1310 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
1311 " select video card type\n", QEMU_ARCH_ALL)
1313 @item -vga @var{type}
1315 Select type of VGA card to emulate. Valid values for @var{type} are
1318 Cirrus Logic GD5446 Video card. All Windows versions starting from
1319 Windows 95 should recognize and use this graphic card. For optimal
1320 performances, use 16 bit color depth in the guest and the host OS.
1321 (This card was the default before QEMU 2.2)
1323 Standard VGA card with Bochs VBE extensions. If your guest OS
1324 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1325 to use high resolution modes (>= 1280x1024x16) then you should use
1326 this option. (This card is the default since QEMU 2.2)
1328 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1329 recent XFree86/XOrg server or Windows guest with a driver for this
1332 QXL paravirtual graphic card. It is VGA compatible (including VESA
1333 2.0 VBE support). Works best with qxl guest drivers installed though.
1334 Recommended choice when using the spice protocol.
1336 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1337 sun4m machines and offers both 8-bit and 24-bit colour depths at a
1338 fixed resolution of 1024x768.
1340 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1341 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1342 resolutions aimed at people wishing to run older Solaris versions.
1350 DEF("full-screen", 0, QEMU_OPTION_full_screen,
1351 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
1354 @findex -full-screen
1355 Start in full screen.
1358 DEF("g", 1, QEMU_OPTION_g ,
1359 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1360 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
1362 @item -g @var{width}x@var{height}[x@var{depth}]
1364 Set the initial graphical resolution and depth (PPC, SPARC only).
1367 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1368 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
1370 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1372 Normally, if QEMU is compiled with graphical window support, it displays
1373 output such as guest graphics, guest console, and the QEMU monitor in a
1374 window. With this option, you can have QEMU listen on VNC display
1375 @var{display} and redirect the VGA display over the VNC session. It is
1376 very useful to enable the usb tablet device when using this option
1377 (option @option{-device usb-tablet}). When using the VNC display, you
1378 must use the @option{-k} parameter to set the keyboard layout if you are
1379 not using en-us. Valid syntax for the @var{display} is
1385 With this option, QEMU will try next available VNC @var{display}s, until the
1386 number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1387 available, e.g. port 5900+@var{display} is already used by another
1388 application. By default, to=0.
1390 @item @var{host}:@var{d}
1392 TCP connections will only be allowed from @var{host} on display @var{d}.
1393 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1394 be omitted in which case the server will accept connections from any host.
1396 @item unix:@var{path}
1398 Connections will be allowed over UNIX domain sockets where @var{path} is the
1399 location of a unix socket to listen for connections on.
1403 VNC is initialized but not started. The monitor @code{change} command
1404 can be used to later start the VNC server.
1408 Following the @var{display} value there may be one or more @var{option} flags
1409 separated by commas. Valid options are
1415 Connect to a listening VNC client via a ``reverse'' connection. The
1416 client is specified by the @var{display}. For reverse network
1417 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1418 is a TCP port number, not a display number.
1422 Opens an additional TCP listening port dedicated to VNC Websocket connections.
1423 If a bare @var{websocket} option is given, the Websocket port is
1424 5700+@var{display}. An alternative port can be specified with the
1425 syntax @code{websocket}=@var{port}.
1427 If @var{host} is specified connections will only be allowed from this host.
1428 It is possible to control the websocket listen address independently, using
1429 the syntax @code{websocket}=@var{host}:@var{port}.
1431 If no TLS credentials are provided, the websocket connection runs in
1432 unencrypted mode. If TLS credentials are provided, the websocket connection
1433 requires encrypted client connections.
1437 Require that password based authentication is used for client connections.
1439 The password must be set separately using the @code{set_password} command in
1440 the @ref{pcsys_monitor}. The syntax to change your password is:
1441 @code{set_password <protocol> <password>} where <protocol> could be either
1444 If you would like to change <protocol> password expiration, you should use
1445 @code{expire_password <protocol> <expiration-time>} where expiration time could
1446 be one of the following options: now, never, +seconds or UNIX time of
1447 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1448 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1451 You can also use keywords "now" or "never" for the expiration time to
1452 allow <protocol> password to expire immediately or never expire.
1454 @item tls-creds=@var{ID}
1456 Provides the ID of a set of TLS credentials to use to secure the
1457 VNC server. They will apply to both the normal VNC server socket
1458 and the websocket socket (if enabled). Setting TLS credentials
1459 will cause the VNC server socket to enable the VeNCrypt auth
1460 mechanism. The credentials should have been previously created
1461 using the @option{-object tls-creds} argument.
1463 The @option{tls-creds} parameter obsoletes the @option{tls},
1464 @option{x509}, and @option{x509verify} options, and as such
1465 it is not permitted to set both new and old type options at
1470 Require that client use TLS when communicating with the VNC server. This
1471 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1472 attack. It is recommended that this option be combined with either the
1473 @option{x509} or @option{x509verify} options.
1475 This option is now deprecated in favor of using the @option{tls-creds}
1478 @item x509=@var{/path/to/certificate/dir}
1480 Valid if @option{tls} is specified. Require that x509 credentials are used
1481 for negotiating the TLS session. The server will send its x509 certificate
1482 to the client. It is recommended that a password be set on the VNC server
1483 to provide authentication of the client when this is used. The path following
1484 this option specifies where the x509 certificates are to be loaded from.
1485 See the @ref{vnc_security} section for details on generating certificates.
1487 This option is now deprecated in favour of using the @option{tls-creds}
1490 @item x509verify=@var{/path/to/certificate/dir}
1492 Valid if @option{tls} is specified. Require that x509 credentials are used
1493 for negotiating the TLS session. The server will send its x509 certificate
1494 to the client, and request that the client send its own x509 certificate.
1495 The server will validate the client's certificate against the CA certificate
,
1496 and reject clients when validation fails
. If the certificate authority is
1497 trusted
, this is a sufficient authentication mechanism
. You may still wish
1498 to set a password on the VNC server as a second authentication layer
. The
1499 path following
this option specifies where the x509 certificates are to
1500 be loaded from
. See the @ref
{vnc_security
} section
for details on generating
1503 This option is now deprecated
in favour of
using the @option
{tls
-creds
}
1508 Require that the client use SASL to authenticate with the VNC server
.
1509 The exact choice of authentication method used is controlled from the
1510 system
/ user
's SASL configuration file for the 'qemu
' service. This
1511 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1512 unprivileged user, an environment variable SASL_CONF_PATH can be used
1513 to make it search alternate locations for the service config.
1514 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1515 it is recommended that SASL always be combined with the 'tls
' and
1516 'x509
' settings to enable use of SSL and server certificates. This
1517 ensures a data encryption preventing compromise of authentication
1518 credentials. See the @ref{vnc_security} section for details on using
1519 SASL authentication.
1523 Turn on access control lists for checking of the x509 client certificate
1524 and SASL party. For x509 certs, the ACL check is made against the
1525 certificate's distinguished name
. This is something that looks like
1526 @code
{C
=GB
,O
=ACME
,L
=Boston
,CN
=bob
}. For SASL party
, the ACL check is
1527 made against the username
, which depending on the SASL plugin
, may
1528 include a realm component
, eg @code
{bob
} or @code
{bob@@EXAMPLE
.COM
}.
1529 When the @option
{acl
} flag is set
, the initial access list will be
1530 empty
, with a @code
{deny
} policy
. Thus no one will be allowed to
1531 use the VNC server until the ACLs have been loaded
. This can be
1532 achieved
using the @code
{acl
} monitor command
.
1536 Enable lossy compression
methods (gradient
, JPEG
, ...). If
this
1537 option is set
, VNC client may receive lossy framebuffer updates
1538 depending on its encoding settings
. Enabling
this option can save
1539 a lot of bandwidth at the expense of quality
.
1543 Disable adaptive encodings
. Adaptive encodings are enabled by
default.
1544 An adaptive encoding will
try to detect frequently updated screen regions
,
1545 and send updates
in these regions
using a lossy
encoding (like JPEG
).
1546 This can be really helpful to save bandwidth when playing videos
. Disabling
1547 adaptive encodings restores the original
static behavior of encodings
1550 @item share
=[allow
-exclusive|force
-shared|ignore
]
1552 Set display sharing policy
. 'allow-exclusive' allows clients to ask
1553 for exclusive access
. As suggested by the rfb spec
this is
1554 implemented by dropping other connections
. Connecting multiple
1555 clients
in parallel requires all clients asking
for a shared session
1556 (vncviewer
: -shared
switch). This is the
default. 'force-shared'
1557 disables exclusive client access
. Useful
for shared desktop sessions
,
1558 where you don
't want someone forgetting specify -shared disconnect
1559 everybody else. 'ignore
' completely ignores the shared flag and
1560 allows everybody connect unconditionally. Doesn't conform to the rfb
1561 spec but is traditional QEMU behavior
.
1565 Set keyboard delay
, for key down and key up events
, in milliseconds
.
1566 Default is
1. Keyboards are low
-bandwidth devices
, so
this slowdown
1567 can help the device and guest to keep up and not lose events
in case
1568 events are arriving
in bulk
. Possible causes
for the latter are flaky
1569 network connections
, or scripts
for automated testing
.
1577 ARCHHEADING(, QEMU_ARCH_I386
)
1579 ARCHHEADING(i386 target only
, QEMU_ARCH_I386
)
1584 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack
,
1585 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1590 Use it when installing Windows
2000 to avoid a disk full bug
. After
1591 Windows
2000 is installed
, you no longer need
this option (this option
1592 slows down the IDE transfers
).
1595 HXCOMM Deprecated by
-rtc
1596 DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack
, "", QEMU_ARCH_I386
)
1598 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk
,
1599 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1602 @item
-no
-fd
-bootchk
1603 @findex
-no
-fd
-bootchk
1604 Disable boot signature checking
for floppy disks
in BIOS
. May
1605 be needed to boot from old floppy disks
.
1608 DEF("no-acpi", 0, QEMU_OPTION_no_acpi
,
1609 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM
)
1613 Disable
ACPI (Advanced Configuration and Power Interface
) support
. Use
1614 it
if your guest OS complains about ACPI
problems (PC target machine
1618 DEF("no-hpet", 0, QEMU_OPTION_no_hpet
,
1619 "-no-hpet disable HPET\n", QEMU_ARCH_I386
)
1623 Disable HPET support
.
1626 DEF("acpitable", HAS_ARG
, QEMU_OPTION_acpitable
,
1627 "-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"
1628 " ACPI table description\n", QEMU_ARCH_I386
)
1630 @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
}]...]
1632 Add ACPI table with specified header fields and context from specified files
.
1633 For file
=, take whole ACPI table from the specified files
, including all
1634 ACPI
headers (possible overridden by other options
).
1635 For data
=, only data
1636 portion of the table is used
, all header information is specified
in the
1638 If a SLIC table is supplied to QEMU
, then the SLIC
's oem_id and oem_table_id
1639 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1640 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1644 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1645 "-smbios file=binary\n"
1646 " load SMBIOS entry from binary file\n"
1647 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1649 " specify SMBIOS type 0 fields\n"
1650 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1651 " [,uuid=uuid][,sku=str][,family=str]\n"
1652 " specify SMBIOS type 1 fields\n"
1653 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1654 " [,asset=str][,location=str]\n"
1655 " specify SMBIOS type 2 fields\n"
1656 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
1658 " specify SMBIOS type 3 fields\n"
1659 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
1660 " [,asset=str][,part=str]\n"
1661 " specify SMBIOS type 4 fields\n"
1662 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
1663 " [,asset=str][,part=str][,speed=%d]\n"
1664 " specify SMBIOS type 17 fields\n",
1665 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1667 @item -smbios file=@var{binary}
1669 Load SMBIOS entry from binary file.
1671 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
1672 Specify SMBIOS type 0 fields
1674 @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}]
1675 Specify SMBIOS type 1 fields
1677 @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}]
1678 Specify SMBIOS type 2 fields
1680 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1681 Specify SMBIOS type 3 fields
1683 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1684 Specify SMBIOS type 4 fields
1686 @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}]
1687 Specify SMBIOS type 17 fields
1695 DEFHEADING(Network options)
1700 HXCOMM Legacy slirp options (now moved to -net user):
1702 DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1703 DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1704 DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1706 DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1710 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1712 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
1713 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
1714 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
1715 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,tftp=dir]\n"
1716 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
1718 "[,smb=dir[,smbserver=addr]]\n"
1720 " configure a user mode network backend with ID 'str
',\n"
1721 " its DHCP server and optional services\n"
1724 "-netdev tap,id=str,ifname=name\n"
1725 " configure a host TAP network backend with ID 'str
'\n"
1727 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
1728 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
1729 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
1731 " configure a host TAP network backend with ID 'str
'\n"
1732 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1733 " use network scripts 'file
' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1734 " to configure it and 'dfile
' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1735 " to deconfigure it\n"
1736 " use '[down
]script
=no
' to disable script execution\n"
1737 " use network helper 'helper
' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1739 " use 'fd
=h
' to connect to an already opened TAP interface\n"
1740 " use 'fds
=x
:y
:...:z
' to connect to already opened multiqueue capable TAP interfaces\n"
1741 " use 'sndbuf
=nbytes
' to limit the size of the send buffer (the\n"
1742 " default is disabled 'sndbuf
=0' to enable flow control set 'sndbuf
=1048576')\n"
1743 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1744 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1745 " use vhost=on to enable experimental in kernel accelerator\n"
1746 " (only has effect for virtio guests which use MSIX)\n"
1747 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1748 " use 'vhostfd
=h
' to connect to an already opened vhost net device\n"
1749 " use 'vhostfds
=x
:y
:...:z to connect to multiple already opened vhost net devices
\n"
1750 " use
'queues=n' to specify the number of queues to be created
for multiqueue TAP
\n"
1751 " use
'poll-us=n' to speciy the maximum number of microseconds that could be
\n"
1752 " spent on busy polling
for vhost net
\n"
1753 "-netdev bridge
,id
=str
[,br
=bridge
][,helper
=helper
]\n"
1754 " configure a host TAP network backend with ID
'str' that is
\n"
1755 " connected to a
bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1756 " using the program
'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
1759 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
1760 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
1761 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
1762 " [,rxcookie=rxcookie][,offset=offset]\n"
1763 " configure a network backend with ID 'str
' connected to\n"
1764 " an Ethernet over L2TPv3 pseudowire.\n"
1765 " Linux kernel 3.3+ as well as most routers can talk\n"
1766 " L2TPv3. This transport allows connecting a VM to a VM,\n"
1767 " VM to a router and even VM to Host. It is a nearly-universal\n"
1768 " standard (RFC3391). Note - this implementation uses static\n"
1769 " pre-configured tunnels (same as the Linux kernel).\n"
1770 " use 'src
=' to specify source address\n"
1771 " use 'dst
=' to specify destination address\n"
1772 " use 'udp
=on
' to specify udp encapsulation\n"
1773 " use 'srcport
=' to specify source udp port\n"
1774 " use 'dstport
=' to specify destination udp port\n"
1775 " use 'ipv6
=on
' to force v6\n"
1776 " L2TPv3 uses cookies to prevent misconfiguration as\n"
1777 " well as a weak security measure\n"
1778 " use 'rxcookie
=0x012345678' to specify a rxcookie\n"
1779 " use 'txcookie
=0x012345678' to specify a txcookie\n"
1780 " use 'cookie64
=on
' to set cookie size to 64 bit, otherwise 32\n"
1781 " use 'counter
=off
' to force a 'cut
-down
' L2TPv3 with no counter\n"
1782 " use 'pincounter
=on
' to work around broken counter handling in peer\n"
1783 " use 'offset
=X
' to add an extra offset between header and data\n"
1785 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
1786 " configure a network backend to connect to another network\n"
1787 " using a socket connection\n"
1788 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1789 " configure a network backend to connect to a multicast maddr and port\n"
1790 " use 'localaddr
=addr
' to specify the host address to send packets from\n"
1791 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
1792 " configure a network backend to connect to another network\n"
1793 " using an UDP tunnel\n"
1795 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1796 " configure a network backend to connect to port 'n
' of a vde switch\n"
1797 " running on host and listening for incoming connections on 'socketpath
'.\n"
1798 " Use group 'groupname
' and mode 'octalmode
' to change default\n"
1799 " ownership and permissions for communication port.\n"
1801 #ifdef CONFIG_NETMAP
1802 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
1803 " attach to the existing netmap-enabled network interface 'name
', or to a\n"
1804 " VALE port (created on the fly) called 'name
' ('nmname
' is name of the \n"
1805 " netmap device, defaults to '/dev
/netmap
')\n"
1807 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
1808 " configure a vhost-user network, backed by a chardev 'dev
'\n"
1809 "-netdev hubport,id=str,hubid=n\n"
1810 " configure a hub port on QEMU VLAN 'n
'\n", QEMU_ARCH_ALL)
1811 DEF("net", HAS_ARG, QEMU_OPTION_net,
1812 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1813 " old way to create a new NIC and connect it to VLAN 'n
'\n"
1814 " (use the '-device devtype
,netdev
=str
' option if possible instead)\n"
1815 "-net dump[,vlan=n][,file=f][,len=n]\n"
1816 " dump traffic on vlan 'n
' to file 'f
' (max n bytes per packet)\n"
1817 "-net none use it alone to have zero network devices. If no -net option\n"
1818 " is provided, the default is '-net nic
-net user
'\n"
1828 #ifdef CONFIG_NETMAP
1831 "socket][,vlan=n][,option][,option][,...]\n"
1832 " old way to initialize a host network interface\n"
1833 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
1835 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1837 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1838 = 0 is the default). The NIC is an e1000 by default on the PC
1839 target. Optionally, the MAC address can be changed to @var{mac}, the
1840 device address set to @var{addr} (PCI cards only),
1841 and a @var{name} can be assigned for use in monitor commands.
1842 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1843 that the card should have; this option currently only affects virtio cards; set
1844 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1845 NIC is created. QEMU can emulate several different models of network card.
1846 Valid values for @var{type} are
1847 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1848 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1849 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1850 Not all devices are supported on all targets. Use @code{-net nic,model=help}
1851 for a list of available devices for your target.
1853 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
1855 @item -net user[,@var{option}][,@var{option}][,...]
1856 Use the user mode network stack which requires no administrator
1857 privilege to run. Valid options are:
1861 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1864 @itemx name=@var{name}
1865 Assign symbolic name for use in monitor commands.
1867 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must
1868 be enabled. If neither is specified both protocols are enabled.
1870 @item net=@var{addr}[/@var{mask}]
1871 Set IP network address the guest will see. Optionally specify the netmask,
1872 either in the form a.b.c.d or as number of valid top-most bits. Default is
1875 @item host=@var{addr}
1876 Specify the guest-visible address of the host. Default is the 2nd IP in the
1877 guest network, i.e. x.x.x.2.
1879 @item ipv6-net=@var{addr}[/@var{int}]
1880 Set IPv6 network address the guest will see (default is fec0::/64). The
1881 network prefix is given in the usual hexadecimal IPv6 address
1882 notation. The prefix size is optional, and is given as the number of
1883 valid top-most bits (default is 64).
1885 @item ipv6-host=@var{addr}
1886 Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
1887 the guest network, i.e. xxxx::2.
1889 @item restrict=on|off
1890 If this option is enabled, the guest will be isolated, i.e. it will not be
1891 able to contact the host and no guest IP packets will be routed over the host
1892 to the outside. This option does not affect any explicitly set forwarding rules.
1894 @item hostname=@var{name}
1895 Specifies the client hostname reported by the built-in DHCP server.
1897 @item dhcpstart=@var{addr}
1898 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1899 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1901 @item dns=@var{addr}
1902 Specify the guest-visible address of the virtual nameserver. The address must
1903 be different from the host address. Default is the 3rd IP in the guest network,
1906 @item ipv6-dns=@var{addr}
1907 Specify the guest-visible address of the IPv6 virtual nameserver. The address
1908 must be different from the host address. Default is the 3rd IP in the guest
1909 network, i.e. xxxx::3.
1911 @item dnssearch=@var{domain}
1912 Provides an entry for the domain-search list sent by the built-in
1913 DHCP server. More than one domain suffix can be transmitted by specifying
1914 this option multiple times. If supported, this will cause the guest to
1915 automatically try to append the given domain suffix(es) in case a domain name
1916 can not be resolved.
1920 qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1923 @item tftp=@var{dir}
1924 When using the user mode network stack, activate a built-in TFTP
1925 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1926 The TFTP client on the guest must be configured in binary mode (use the command
1927 @code{bin} of the Unix TFTP client).
1929 @item bootfile=@var{file}
1930 When using the user mode network stack, broadcast @var{file} as the BOOTP
1931 filename. In conjunction with @option{tftp}, this can be used to network boot
1932 a guest from a local directory.
1934 Example (using pxelinux):
1936 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1939 @item smb=@var{dir}[,smbserver=@var{addr}]
1940 When using the user mode network stack, activate a built-in SMB
1941 server so that Windows OSes can access to the host files in @file{@var{dir}}
1942 transparently. The IP address of the SMB server can be set to @var{addr}. By
1943 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1945 In the guest Windows OS, the line:
1949 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1950 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1952 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1954 Note that a SAMBA server must be installed on the host OS.
1955 QEMU was tested successfully with smbd versions from Red Hat 9,
1956 Fedora Core 3 and OpenSUSE 11.x.
1958 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1959 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1960 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1961 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1962 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1963 be bound to a specific host interface. If no connection type is set, TCP is
1964 used. This option can be given multiple times.
1966 For example, to redirect host X11 connection from screen 1 to guest
1967 screen 0, use the following:
1971 qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1972 # this host xterm should open in the guest X11 server
1976 To redirect telnet connections from host port 5555 to telnet port on
1977 the guest, use the following:
1981 qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
1982 telnet localhost 5555
1985 Then when you use on the host @code{telnet localhost 5555}, you
1986 connect to the guest telnet server.
1988 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1989 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
1990 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1991 to the character device @var{dev} or to a program executed by @var{cmd:command}
1992 which gets spawned for each connection. This option can be given multiple times.
1994 You can either use a chardev directly and have that one used throughout QEMU's
1995 lifetime
, like
in the following example
:
1998 # open
10.10.1.1:4321 on bootup
, connect
10.0.2.100:1234 to it whenever
1999 # the guest accesses it
2000 qemu
-net user
,guestfwd
=tcp
:10.0.2.100:1234-tcp
:10.10.1.1:4321 [...]
2003 Or you can execute a command on every TCP connection established by the guest
,
2004 so that QEMU behaves similar to an inetd process
for that virtual server
:
2007 # call
"netcat 10.10.1.1 4321" on every TCP connection to
10.0.2.100:1234
2008 # and connect the TCP stream to its stdin
/stdout
2009 qemu
-net
'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2014 Note
: Legacy stand
-alone options
-tftp
, -bootp
, -smb and
-redir are still
2015 processed and applied to
-net user
. Mixing them with the
new configuration
2016 syntax gives undefined results
. Their use
for new applications is discouraged
2017 as they will be removed from future versions
.
2019 @item
-netdev tap
,id
=@
var{id
}[,fd
=@
var{h
}][,ifname
=@
var{name
}][,script
=@
var{file
}][,downscript
=@
var{dfile
}][,br
=@
var{bridge
}][,helper
=@
var{helper
}]
2020 @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
}]
2021 Connect the host TAP network
interface @
var{name
} to VLAN @
var{n
}.
2023 Use the network script @
var{file
} to configure it and the network script
2024 @
var{dfile
} to deconfigure it
. If @
var{name
} is not provided
, the OS
2025 automatically provides one
. The
default network configure script is
2026 @file
{/etc
/qemu
-ifup
} and the
default network deconfigure script is
2027 @file
{/etc
/qemu
-ifdown
}. Use @option
{script
=no
} or @option
{downscript
=no
}
2028 to disable script execution
.
2030 If running QEMU as an unprivileged user
, use the network helper
2031 @
var{helper
} to configure the TAP
interface and attach it to the bridge
.
2032 The
default network helper executable is @file
{/path
/to
/qemu
-bridge
-helper
}
2033 and the
default bridge device is @file
{br0
}.
2035 @option
{fd
}=@
var{h
} can be used to specify the handle of an already
2036 opened host TAP
interface.
2041 #launch a QEMU instance with the
default network script
2042 qemu
-system
-i386 linux
.img
-net nic
-net tap
2046 #launch a QEMU instance with two NICs
, each one connected
2048 qemu
-system
-i386 linux
.img \
2049 -net nic
,vlan
=0 -net tap
,vlan
=0,ifname
=tap0 \
2050 -net nic
,vlan
=1 -net tap
,vlan
=1,ifname
=tap1
2054 #launch a QEMU instance with the
default network helper to
2055 #connect a TAP device to bridge br0
2056 qemu
-system
-i386 linux
.img \
2057 -net nic
-net tap
,"helper=/path/to/qemu-bridge-helper"
2060 @item
-netdev bridge
,id
=@
var{id
}[,br
=@
var{bridge
}][,helper
=@
var{helper
}]
2061 @itemx
-net bridge
[,vlan
=@
var{n
}][,name
=@
var{name
}][,br
=@
var{bridge
}][,helper
=@
var{helper
}]
2062 Connect a host TAP network
interface to a host bridge device
.
2064 Use the network helper @
var{helper
} to configure the TAP
interface and
2065 attach it to the bridge
. The
default network helper executable is
2066 @file
{/path
/to
/qemu
-bridge
-helper
} and the
default bridge
2067 device is @file
{br0
}.
2072 #launch a QEMU instance with the
default network helper to
2073 #connect a TAP device to bridge br0
2074 qemu
-system
-i386 linux
.img
-net bridge
-net nic
,model
=virtio
2078 #launch a QEMU instance with the
default network helper to
2079 #connect a TAP device to bridge qemubr0
2080 qemu
-system
-i386 linux
.img
-net bridge
,br
=qemubr0
-net nic
,model
=virtio
2083 @item
-netdev socket
,id
=@
var{id
}[,fd
=@
var{h
}][,listen
=[@
var{host
}]:@
var{port
}][,connect
=@
var{host
}:@
var{port
}]
2084 @itemx
-net socket
[,vlan
=@
var{n
}][,name
=@
var{name
}][,fd
=@
var{h
}] [,listen
=[@
var{host
}]:@
var{port
}][,connect
=@
var{host
}:@
var{port
}]
2086 Connect the VLAN @
var{n
} to a remote VLAN
in another QEMU virtual
2087 machine
using a TCP socket connection
. If @option
{listen
} is
2088 specified
, QEMU waits
for incoming connections on @
var{port
}
2089 (@
var{host
} is optional
). @option
{connect
} is used to connect to
2090 another QEMU instance
using the @option
{listen
} option
. @option
{fd
}=@
var{h
}
2091 specifies an already opened TCP socket
.
2095 # launch a first QEMU instance
2096 qemu
-system
-i386 linux
.img \
2097 -net nic
,macaddr
=52:54:00:12:34:56 \
2098 -net socket
,listen
=:1234
2099 # connect the VLAN
0 of
this instance to the VLAN
0
2100 # of the first instance
2101 qemu
-system
-i386 linux
.img \
2102 -net nic
,macaddr
=52:54:00:12:34:57 \
2103 -net socket
,connect
=127.0.0.1:1234
2106 @item
-netdev socket
,id
=@
var{id
}[,fd
=@
var{h
}][,mcast
=@
var{maddr
}:@
var{port
}[,localaddr
=@
var{addr
}]]
2107 @itemx
-net socket
[,vlan
=@
var{n
}][,name
=@
var{name
}][,fd
=@
var{h
}][,mcast
=@
var{maddr
}:@
var{port
}[,localaddr
=@
var{addr
}]]
2109 Create a VLAN @
var{n
} shared with another QEMU virtual
2110 machines
using a UDP multicast socket
, effectively making a bus
for
2111 every QEMU with same multicast address @
var{maddr
} and @
var{port
}.
2115 Several QEMU can be running on different hosts and share same
bus (assuming
2116 correct multicast setup
for these hosts
).
2118 mcast support is compatible with User Mode
Linux (argument @option
{eth@
var{N
}=mcast
}), see
2119 @url
{http
://user-mode-linux.sf.net}.
2121 Use @option
{fd
=h
} to specify an already opened UDP multicast socket
.
2126 # launch one QEMU instance
2127 qemu
-system
-i386 linux
.img \
2128 -net nic
,macaddr
=52:54:00:12:34:56 \
2129 -net socket
,mcast
=230.0.0.1:1234
2130 # launch another QEMU instance on same
"bus"
2131 qemu
-system
-i386 linux
.img \
2132 -net nic
,macaddr
=52:54:00:12:34:57 \
2133 -net socket
,mcast
=230.0.0.1:1234
2134 # launch yet another QEMU instance on same
"bus"
2135 qemu
-system
-i386 linux
.img \
2136 -net nic
,macaddr
=52:54:00:12:34:58 \
2137 -net socket
,mcast
=230.0.0.1:1234
2140 Example (User Mode Linux compat
.):
2142 # launch QEMU
instance (note mcast address selected
2144 qemu-system-i386 linux.img \
2145 -net nic,macaddr=52:54:00:12:34:56 \
2146 -net socket,mcast=239.192.168.1:1102
2148 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2151 Example (send packets from host's
1.2.3.4):
2153 qemu
-system
-i386 linux
.img \
2154 -net nic
,macaddr
=52:54:00:12:34:56 \
2155 -net socket
,mcast
=239.192.168.1:1102,localaddr
=1.2.3.4
2158 @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
}]
2159 @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
}]
2160 Connect VLAN @
var{n
} to L2TPv3 pseudowire
. L2TPv3 (RFC3391
) is a popular
2161 protocol to transport
Ethernet (and other Layer
2) data frames between
2162 two systems
. It is present
in routers
, firewalls and the Linux kernel
2163 (from version
3.3 onwards
).
2165 This transport allows a VM to communicate to another VM
, router or firewall directly
.
2167 @item src
=@
var{srcaddr
}
2168 source
address (mandatory
)
2169 @item dst
=@
var{dstaddr
}
2170 destination
address (mandatory
)
2172 select udp
encapsulation (default is ip
).
2173 @item srcport
=@
var{srcport
}
2175 @item dstport
=@
var{dstport
}
2176 destination udp port
.
2178 force v6
, otherwise defaults to v4
.
2179 @item rxcookie
=@
var{rxcookie
}
2180 @itemx txcookie
=@
var{txcookie
}
2181 Cookies are a weak form of security
in the l2tpv3 specification
.
2182 Their
function is mostly to prevent misconfiguration
. By
default they are
32
2185 Set cookie size to
64 bit instead of the
default 32
2187 Force a
'cut-down' L2TPv3 with no counter as
in
2188 draft
-mkonstan
-l2tpext
-keyed
-ipv6
-tunnel
-00
2190 Work around broken counter handling
in peer
. This may also help on
2191 networks which have packet reorder
.
2192 @item offset
=@
var{offset
}
2193 Add an extra offset between header and data
2195 For example
, to attach a VM running on host
4.3.2.1 via L2TPv3 to the bridge br
-lan
2196 on the remote Linux host
1.2.3.4:
2198 # Setup tunnel on linux host
using raw ip as encapsulation
2200 ip l2tp add tunnel remote
4.3.2.1 local
1.2.3.4 tunnel_id
1 peer_tunnel_id
1 \
2201 encap udp udp_sport
16384 udp_dport
16384
2202 ip l2tp add session tunnel_id
1 name vmtunnel0 session_id \
2203 0xFFFFFFFF peer_session_id
0xFFFFFFFF
2204 ifconfig vmtunnel0 mtu
1500
2205 ifconfig vmtunnel0 up
2206 brctl addif br
-lan vmtunnel0
2210 # launch QEMU instance
- if your network has reorder or is very lossy add
,pincounter
2212 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 @item
-netdev vde
,id
=@
var{id
}[,sock
=@
var{socketpath
}][,port
=@
var{n
}][,group
=@
var{groupname
}][,mode
=@
var{octalmode
}]
2218 @itemx
-net vde
[,vlan
=@
var{n
}][,name
=@
var{name
}][,sock
=@
var{socketpath
}] [,port
=@
var{n
}][,group
=@
var{groupname
}][,mode
=@
var{octalmode
}]
2219 Connect VLAN @
var{n
} to PORT @
var{n
} of a vde
switch running on host and
2220 listening
for incoming connections on @
var{socketpath
}. Use GROUP @
var{groupname
}
2221 and MODE @
var{octalmode
} to change
default ownership and permissions
for
2222 communication port
. This option is only available
if QEMU has been compiled
2223 with vde support enabled
.
2228 vde_switch
-F
-sock
/tmp
/myswitch
2229 # launch QEMU instance
2230 qemu
-system
-i386 linux
.img
-net nic
-net vde
,sock
=/tmp
/myswitch
2233 @item
-netdev hubport
,id
=@
var{id
},hubid
=@
var{hubid
}
2235 Create a hub port on QEMU
"vlan" @
var{hubid
}.
2237 The hubport netdev lets you connect a NIC to a QEMU
"vlan" instead of a single
2238 netdev
. @code
{-net
} and @code
{-device
} with parameter @option
{vlan
} create the
2239 required hub automatically
.
2241 @item
-netdev vhost
-user
,chardev
=@
var{id
}[,vhostforce
=on|off
][,queues
=n
]
2243 Establish a vhost
-user netdev
, backed by a chardev @
var{id
}. The chardev should
2244 be a unix domain socket backed one
. The vhost
-user uses a specifically defined
2245 protocol to pass vhost ioctl replacement messages to an application on the other
2246 end of the socket
. On non
-MSIX guests
, the feature can be forced with
2247 @
var{vhostforce
}. Use
'queues=@var{n}' to specify the number of queues to
2248 be created
for multiqueue vhost
-user
.
2252 qemu
-m
512 -object memory
-backend
-file
,id
=mem
,size
=512M
,mem
-path
=/hugetlbfs
,share
=on \
2253 -numa node
,memdev
=mem \
2254 -chardev socket
,id
=chr0
,path
=/path
/to
/socket \
2255 -netdev type
=vhost
-user
,id
=net0
,chardev
=chr0 \
2256 -device virtio
-net
-pci
,netdev
=net0
2259 @item
-net dump
[,vlan
=@
var{n
}][,file
=@
var{file
}][,len
=@
var{len
}]
2260 Dump network traffic on VLAN @
var{n
} to file @
var{file
} (@file
{qemu
-vlan0
.pcap
} by
default).
2261 At most @
var{len
} bytes (64k by
default) per packet are stored
. The file format is
2262 libpcap
, so it can be analyzed with tools such as tcpdump or Wireshark
.
2263 Note
: For devices created with
'-netdev', use
'-object filter-dump,...' instead
.
2266 Indicate that no network devices should be configured
. It is used to
2267 override the
default configuration (@option
{-net nic
-net user
}) which
2268 is activated
if no @option
{-net
} options are provided
.
2276 DEFHEADING(Character device options
)
2279 The general form of a character device option is
:
2283 DEF("chardev", HAS_ARG
, QEMU_OPTION_chardev
,
2285 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2286 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
2287 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off]\n"
2288 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID] (tcp)\n"
2289 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds]\n"
2290 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
2291 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
2292 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
2293 " [,logfile=PATH][,logappend=on|off]\n"
2294 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2295 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
2296 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2297 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2298 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2299 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2301 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2302 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2304 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2305 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
2307 #ifdef CONFIG_BRLAPI
2308 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2310 #
if defined(__linux__
) ||
defined(__sun__
) ||
defined(__FreeBSD__
) \
2311 ||
defined(__NetBSD__
) ||
defined(__OpenBSD__
) ||
defined(__DragonFly__
)
2312 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2313 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2315 #
if defined(__linux__
) ||
defined(__FreeBSD__
) ||
defined(__DragonFly__
)
2316 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2317 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2319 #
if defined(CONFIG_SPICE
)
2320 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2321 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2327 @item
-chardev @
var{backend
} ,id
=@
var{id
} [,mux
=on|off
] [,@
var{options
}]
2348 The specific backend will determine the applicable options
.
2350 Use
"-chardev help" to print all available chardev backend types
.
2352 All devices must have an id
, which can be any string up to
127 characters long
.
2353 It is used to uniquely identify
this device
in other command line directives
.
2355 A character device may be used
in multiplexing mode by multiple front
-ends
.
2356 Specify @option
{mux
=on
} to enable
this mode
.
2357 A multiplexer is a
"1:N" device
, and
here the
"1" end is your specified chardev
2358 backend
, and the
"N" end is the various parts of QEMU that can talk to a chardev
.
2359 If you create a chardev with @option
{id
=myid
} and @option
{mux
=on
}, QEMU will
2360 create a multiplexer with your specified ID
, and you can then configure multiple
2361 front ends to use that chardev ID
for their input
/output
. Up to four different
2362 front ends can be connected to a single multiplexed chardev
. (Without
2363 multiplexing enabled
, a chardev can only be used by a single front end
.)
2364 For instance you could use
this to allow a single stdio chardev to be used by
2365 two serial ports and the QEMU monitor
:
2368 -chardev stdio
,mux
=on
,id
=char0 \
2369 -mon chardev
=char0
,mode
=readline \
2370 -serial chardev
:char0 \
2371 -serial chardev
:char0
2374 You can have more than one multiplexer
in a system configuration
; for instance
2375 you could have a TCP port multiplexed between UART
0 and UART
1, and stdio
2376 multiplexed between the QEMU monitor and a parallel port
:
2379 -chardev stdio
,mux
=on
,id
=char0 \
2380 -mon chardev
=char0
,mode
=readline \
2381 -parallel chardev
:char0 \
2382 -chardev tcp
,...,mux
=on
,id
=char1 \
2383 -serial chardev
:char1 \
2384 -serial chardev
:char1
2387 When you
're using a multiplexed character device, some escape sequences are
2388 interpreted in the input. @xref{mux_keys, Keys in the character backend
2391 Note that some other command line options may implicitly create multiplexed
2392 character backends; for instance @option{-serial mon:stdio} creates a
2393 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2394 and @option{-nographic} also multiplexes the console and the monitor to
2397 There is currently no support for multiplexing in the other direction
2398 (where a single QEMU front end takes input and output from multiple chardevs).
2400 Every backend supports the @option{logfile} option, which supplies the path
2401 to a file to record all data transmitted via the backend. The @option{logappend}
2402 option controls whether the log file will be truncated or appended to when
2405 Further options to each backend are described below.
2407 @item -chardev null ,id=@var{id}
2408 A void device. This device will not emit any data, and will drop any data it
2409 receives. The null backend does not take any options.
2411 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
2413 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2414 unix socket will be created if @option{path} is specified. Behaviour is
2415 undefined if TCP options are specified for a unix socket.
2417 @option{server} specifies that the socket shall be a listening socket.
2419 @option{nowait} specifies that QEMU should not block waiting for a client to
2420 connect to a listening socket.
2422 @option{telnet} specifies that traffic on the socket should interpret telnet
2425 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2426 the remote end goes away. qemu will delay this many seconds and then attempt
2427 to reconnect. Zero disables reconnecting, and is the default.
2429 @option{tls-creds} requests enablement of the TLS protocol for encryption,
2430 and specifies the id of the TLS credentials to use for the handshake. The
2431 credentials must be previously created with the @option{-object tls-creds}
2434 TCP and unix socket options are given below:
2438 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
2440 @option{host} for a listening socket specifies the local address to be bound.
2441 For a connecting socket species the remote host to connect to. @option{host} is
2442 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2444 @option{port} for a listening socket specifies the local port to be bound. For a
2445 connecting socket specifies the port on the remote host to connect to.
2446 @option{port} can be given as either a port number or a service name.
2447 @option{port} is required.
2449 @option{to} is only relevant to listening sockets. If it is specified, and
2450 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2451 to and including @option{to} until it succeeds. @option{to} must be specified
2454 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2455 If neither is specified the socket may use either protocol.
2457 @option{nodelay} disables the Nagle algorithm.
2459 @item unix options: path=@var{path}
2461 @option{path} specifies the local path of the unix socket. @option{path} is
2466 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2468 Sends all traffic from the guest to a remote host over UDP.
2470 @option{host} specifies the remote host to connect to. If not specified it
2471 defaults to @code{localhost}.
2473 @option{port} specifies the port on the remote host to connect to. @option{port}
2476 @option{localaddr} specifies the local address to bind to. If not specified it
2477 defaults to @code{0.0.0.0}.
2479 @option{localport} specifies the local port to bind to. If not specified any
2480 available local port will be used.
2482 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2483 If neither is specified the device may use either protocol.
2485 @item -chardev msmouse ,id=@var{id}
2487 Forward QEMU's emulated msmouse events to the guest
. @option
{msmouse
} does not
2490 @item
-chardev vc
,id
=@
var{id
} [[,width
=@
var{width
}] [,height
=@
var{height
}]] [[,cols
=@
var{cols
}] [,rows
=@
var{rows
}]]
2492 Connect to a QEMU text console
. @option
{vc
} may optionally be given a specific
2495 @option
{width
} and @option
{height
} specify the width and height respectively of
2496 the console
, in pixels
.
2498 @option
{cols
} and @option
{rows
} specify that the console be sized to fit a text
2499 console with the given dimensions
.
2501 @item
-chardev ringbuf
,id
=@
var{id
} [,size
=@
var{size
}]
2503 Create a ring buffer with fixed size @option
{size
}.
2504 @
var{size
} must be a power of two and defaults to @code
{64K
}.
2506 @item
-chardev file
,id
=@
var{id
} ,path
=@
var{path
}
2508 Log all traffic received from the guest to a file
.
2510 @option
{path
} specifies the path of the file to be opened
. This file will be
2511 created
if it does not already exist
, and overwritten
if it does
. @option
{path
}
2514 @item
-chardev pipe
,id
=@
var{id
} ,path
=@
var{path
}
2516 Create a two
-way connection to the guest
. The behaviour differs slightly between
2517 Windows hosts and other hosts
:
2519 On Windows
, a single duplex pipe will be created at
2520 @file
{\\.pipe\@option
{path
}}.
2522 On other hosts
, 2 pipes will be created called @file
{@option
{path
}.in} and
2523 @file
{@option
{path
}.out
}. Data written to @file
{@option
{path
}.in} will be
2524 received by the guest
. Data written by the guest can be read from
2525 @file
{@option
{path
}.out
}. QEMU will not create these fifos
, and requires them to
2528 @option
{path
} forms part of the pipe path as described above
. @option
{path
} is
2531 @item
-chardev console
,id
=@
var{id
}
2533 Send traffic from the guest to QEMU
's standard output. @option{console} does not
2536 @option{console} is only available on Windows hosts.
2538 @item -chardev serial ,id=@var{id} ,path=@option{path}
2540 Send traffic from the guest to a serial device on the host.
2542 On Unix hosts serial will actually accept any tty device,
2543 not only serial lines.
2545 @option{path} specifies the name of the serial device to open.
2547 @item -chardev pty ,id=@var{id}
2549 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2550 not take any options.
2552 @option{pty} is not available on Windows hosts.
2554 @item -chardev stdio ,id=@var{id} [,signal=on|off]
2555 Connect to standard input and standard output of the QEMU process.
2557 @option{signal} controls if signals are enabled on the terminal, that includes
2558 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2559 default, use @option{signal=off} to disable it.
2561 @item -chardev braille ,id=@var{id}
2563 Connect to a local BrlAPI server. @option{braille} does not take any options.
2565 @item -chardev tty ,id=@var{id} ,path=@var{path}
2567 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2568 DragonFlyBSD hosts. It is an alias for @option{serial}.
2570 @option{path} specifies the path to the tty. @option{path} is required.
2572 @item -chardev parallel ,id=@var{id} ,path=@var{path}
2573 @itemx -chardev parport ,id=@var{id} ,path=@var{path}
2575 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2577 Connect to a local parallel port.
2579 @option{path} specifies the path to the parallel port device. @option{path} is
2582 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2584 @option{spicevmc} is only available when spice support is built in.
2586 @option{debug} debug level for spicevmc
2588 @option{name} name of spice channel to connect to
2590 Connect to a spice virtual machine channel, such as vdiport.
2592 @item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2594 @option{spiceport} is only available when spice support is built in.
2596 @option{debug} debug level for spicevmc
2598 @option{name} name of spice port to connect to
2600 Connect to a spice port, allowing a Spice client to handle the traffic
2601 identified by a name (preferably a fqdn).
2609 DEFHEADING(Device URL Syntax)
2612 In addition to using normal file images for the emulated storage devices,
2613 QEMU can also use networked resources such as iSCSI devices. These are
2614 specified using a special URL syntax.
2618 iSCSI support allows QEMU to access iSCSI resources directly and use as
2619 images for the guest storage. Both disk and cdrom images are supported.
2621 Syntax for specifying iSCSI LUNs is
2622 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2624 By default qemu will use the iSCSI initiator-name
2625 'iqn
.2008-11.org
.linux
-kvm
[:<name
>]' but this can also be set from the command
2626 line or a configuration file.
2628 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2629 stalled requests and force a reestablishment of the session. The timeout
2630 is specified in seconds. The default is 0 which means no timeout. Libiscsi
2631 1.15.0 or greater is required for this feature.
2633 Example (without authentication):
2635 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2636 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2637 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2640 Example (CHAP username/password via URL):
2642 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
2645 Example (CHAP username/password via environment variables):
2647 LIBISCSI_CHAP_USERNAME="user" \
2648 LIBISCSI_CHAP_PASSWORD="password" \
2649 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2652 iSCSI support is an optional feature of QEMU and only available when
2653 compiled and linked against libiscsi.
2655 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2656 "-iscsi [user=user][,password=password]\n"
2657 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
2658 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
2659 " [,timeout=timeout]\n"
2660 " iSCSI session parameters\n", QEMU_ARCH_ALL)
2663 iSCSI parameters such as username and password can also be specified via
2664 a configuration file. See qemu-doc for more information and examples.
2667 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2668 as Unix Domain Sockets.
2670 Syntax for specifying a NBD device using TCP
2671 ``nbd:<server-ip>:<port>[:exportname=<export>]''
2673 Syntax for specifying a NBD device using Unix Domain Sockets
2674 ``nbd:unix:<domain-socket>[:exportname=<export>]''
2679 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
2682 Example for Unix Domain Sockets
2684 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
2688 QEMU supports SSH (Secure Shell) access to remote disks.
2692 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2693 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2696 Currently authentication must be done using ssh-agent. Other
2697 authentication methods may be supported in future.
2700 Sheepdog is a distributed storage system for QEMU.
2701 QEMU supports using either local sheepdog devices or remote networked
2704 Syntax for specifying a sheepdog device
2706 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
2711 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
2714 See also @url{https://sheepdog.github.io/sheepdog/}.
2717 GlusterFS is a user space distributed file system.
2718 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2719 TCP, Unix Domain Sockets and RDMA transport protocols.
2721 Syntax for specifying a VM disk image on GlusterFS volume is
2725 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
2728 'json
:@
{"driver":"qcow2","file":@
{"driver":"gluster","volume":"testvol","path":"a.img","debug":N
,"logfile":"...",
2729 @
"server":[@
{"type":"tcp","host":"...","port":"..."@
},
2730 @ @
{"type":"unix","socket":"..."@
}]@
}@
}'
2737 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
2738 @ file.debug=9,file.logfile=/var/log/qemu-gluster.log
2741 qemu-system-x86_64 'json
:@
{"driver":"qcow2",
2742 @
"file":@
{"driver":"gluster",
2743 @
"volume":"testvol","path":"a.img",
2744 @
"debug":9,"logfile":"/var/log/qemu-gluster.log",
2745 @
"server":[@
{"type":"tcp","host":"1.2.3.4","port":24007@
},
2746 @ @
{"type":"unix","socket":"/var/run/glusterd.socket"@
}]@
}@
}'
2747 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
2748 @ file.debug=9,file.logfile=/var/log/qemu-gluster.log,
2749 @ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
2750 @ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
2753 See also @url{http://www.gluster.org}.
2755 @item HTTP/HTTPS/FTP/FTPS
2756 QEMU supports read-only access to files accessed over http(s) and ftp(s).
2758 Syntax using a single filename:
2760 <protocol>://[<username>[:<password>]@@]<host>/<path>
2766 'http
', 'https
', 'ftp
', or 'ftps
'.
2769 Optional username for authentication to the remote server.
2772 Optional password for authentication to the remote server.
2775 Address of the remote server.
2778 Path on the remote server, including any query string.
2781 The following options are also supported:
2784 The full URL when passing options to the driver explicitly.
2787 The amount of data to read ahead with each range request to the remote server.
2788 This value may optionally have the suffix 'T
', 'G
', 'M
', 'K
', 'k
' or 'b
'. If it
2789 does not have a suffix, it will be assumed to be in bytes. The value must be a
2790 multiple of 512 bytes. It defaults to 256k.
2793 Whether to verify the remote server's certificate when connecting over SSL
. It
2794 can have the value
'on' or
'off'. It defaults to
'on'.
2797 Send
this cookie (it can also be a list of cookies separated by
';') with
2798 each outgoing request
. Only supported when
using protocols such as HTTP
2799 which support cookies
, otherwise ignored
.
2802 Set the timeout
in seconds of the CURL connection
. This timeout is the time
2803 that CURL waits
for a response from the remote server to get the size of the
2804 image to be downloaded
. If not set
, the
default timeout of
5 seconds is used
.
2807 Note that when passing options to qemu explicitly
, @option
{driver
} is the value
2810 Example
: boot from a remote Fedora
20 live ISO image
2812 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
2814 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
2817 Example
: boot from a remote Fedora
20 cloud image
using a local overlay
for
2818 writes
, copy
-on
-read
, and a readahead of
64k
2820 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
2822 qemu
-system
-x86_64
-drive file
=/tmp
/Fedora
-x86_64
-20-20131211.1-sda
.qcow2
,copy
-on
-read
=on
2825 Example
: boot from an image stored on a VMware vSphere server with a self
-signed
2826 certificate
using a local overlay
for writes
, a readahead of
64k and a timeout
2829 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
2831 qemu
-system
-x86_64
-drive file
=/tmp
/test
.qcow2
2839 DEFHEADING(Bluetooth(R
) options
)
2844 DEF("bt", HAS_ARG
, QEMU_OPTION_bt
, \
2845 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2846 "-bt hci,host[:id]\n" \
2847 " use host's HCI with the given name\n" \
2848 "-bt hci[,vlan=n]\n" \
2849 " emulate a standard HCI in virtual scatternet 'n'\n" \
2850 "-bt vhci[,vlan=n]\n" \
2851 " add host computer to virtual scatternet 'n' using VHCI\n" \
2852 "-bt device:dev[,vlan=n]\n" \
2853 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2858 Defines the
function of the corresponding Bluetooth HCI
. -bt options
2859 are matched with the HCIs present
in the chosen machine type
. For
2860 example when emulating a machine with only one HCI built into it
, only
2861 the first @code
{-bt hci
[...]} option is valid and defines the HCI
's
2862 logic. The Transport Layer is decided by the machine type. Currently
2863 the machines @code{n800} and @code{n810} have one HCI and all other
2867 The following three types are recognized:
2871 (default) The corresponding Bluetooth HCI assumes no internal logic
2872 and will not respond to any HCI commands or emit events.
2874 @item -bt hci,host[:@var{id}]
2875 (@code{bluez} only) The corresponding HCI passes commands / events
2876 to / from the physical HCI identified by the name @var{id} (default:
2877 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2878 capable systems like Linux.
2880 @item -bt hci[,vlan=@var{n}]
2881 Add a virtual, standard HCI that will participate in the Bluetooth
2882 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2883 VLANs, devices inside a bluetooth network @var{n} can only communicate
2884 with other devices in the same network (scatternet).
2887 @item -bt vhci[,vlan=@var{n}]
2888 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2889 to the host bluetooth stack instead of to the emulated target. This
2890 allows the host and target machines to participate in a common scatternet
2891 and communicate. Requires the Linux @code{vhci} driver installed. Can
2892 be used as following:
2895 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2898 @item -bt device:@var{dev}[,vlan=@var{n}]
2899 Emulate a bluetooth device @var{dev} and place it in network @var{n}
2900 (default @code{0}). QEMU can only emulate one type of bluetooth devices
2905 Virtual wireless keyboard implementing the HIDP bluetooth profile.
2915 DEFHEADING(TPM device options)
2917 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
2918 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2919 " use path to provide path to a character device; default is /dev/tpm0\n"
2920 " use cancel-path to provide path to TPM's cancel sysfs entry
; if\n"
2921 " not provided it will be searched
for in /sys
/class/misc
/tpm?
/device
\n",
2925 The general form of a TPM device option is:
2928 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2930 Backend type must be:
2931 @option{passthrough}.
2933 The specific backend type will determine the applicable options.
2934 The @code{-tpmdev} option creates the TPM backend and requires a
2935 @code{-device} option that specifies the TPM frontend interface model.
2937 Options to each backend are described below.
2939 Use 'help' to print all available TPM backend types.
2944 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
2946 (Linux-host only) Enable access to the host's TPM using the passthrough
2949 @option{path} specifies the path to the host's TPM device, i.e., on
2950 a Linux host this would be @code{/dev/tpm0}.
2951 @option{path} is optional and by default @code{/dev/tpm0} is used.
2953 @option{cancel-path} specifies the path to the host TPM device's sysfs
2954 entry allowing for cancellation of an ongoing TPM command.
2955 @option{cancel-path} is optional and by default QEMU will search for the
2958 Some notes about using the host's TPM with the passthrough driver:
2960 The TPM device accessed by the passthrough driver must not be
2961 used by any other application on the host.
2963 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2964 the VM's firmware (BIOS/UEFI) will not be able to initialize the
2965 TPM again and may therefore not show a TPM-specific menu that would
2966 otherwise allow the user to configure the TPM, e.g., allow the user to
2967 enable/disable or activate/deactivate the TPM.
2968 Further, if TPM ownership is released from within a VM then the host's TPM
2969 will get disabled and deactivated. To enable and activate the
2970 TPM again afterwards, the host has to be rebooted and the user is
2971 required to enter the firmware's menu to enable and activate the TPM.
2972 If the TPM is left disabled and/or deactivated most TPM commands will fail.
2974 To create a passthrough TPM use the following two options:
2976 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2978 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2979 @code{tpmdev=tpm0} in the device option.
2989 DEFHEADING(Linux/Multiboot boot specific)
2992 When using these options, you can use a given Linux or Multiboot
2993 kernel without installing it in the disk image. It can be useful
2994 for easier testing of various kernels.
2999 DEF("kernel
", HAS_ARG, QEMU_OPTION_kernel, \
3000 "-kernel bzImage use
'bzImage' as kernel image
\n", QEMU_ARCH_ALL)
3002 @item -kernel @var{bzImage}
3004 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3005 or in multiboot format.
3008 DEF("append
", HAS_ARG, QEMU_OPTION_append, \
3009 "-append cmdline use
'cmdline' as kernel command line
\n", QEMU_ARCH_ALL)
3011 @item -append @var{cmdline}
3013 Use @var{cmdline} as kernel command line
3016 DEF("initrd
", HAS_ARG, QEMU_OPTION_initrd, \
3017 "-initrd file use
'file' as initial ram disk
\n", QEMU_ARCH_ALL)
3019 @item -initrd @var{file}
3021 Use @var{file} as initial ram disk.
3023 @item -initrd "@
var{file1
} arg
=foo
,@
var{file2
}"
3025 This syntax is only available with multiboot.
3027 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3031 DEF("dtb
", HAS_ARG, QEMU_OPTION_dtb, \
3032 "-dtb file use
'file' as device tree image
\n", QEMU_ARCH_ALL)
3034 @item -dtb @var{file}
3036 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3045 DEFHEADING(Debug/Expert options)
3050 DEF("fw_cfg
", HAS_ARG, QEMU_OPTION_fwcfg,
3051 "-fw_cfg
[name
=]<name
>,file
=<file
>\n"
3052 " add named fw_cfg entry with contents from file
\n"
3053 "-fw_cfg
[name
=]<name
>,string
=<str
>\n"
3054 " add named fw_cfg entry with contents from string
\n",
3058 @item -fw_cfg [name=]@var{name},file=@var{file}
3060 Add named fw_cfg entry with contents from file @var{file}.
3062 @item -fw_cfg [name=]@var{name},string=@var{str}
3063 Add named fw_cfg entry with contents from string @var{str}.
3065 The terminating NUL character of the contents of @var{str} will not be
3066 included as part of the fw_cfg item data. To insert contents with
3067 embedded NUL characters, you have to use the @var{file} parameter.
3069 The fw_cfg entries are passed by QEMU through to the guest.
3073 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3075 creates an fw_cfg entry named opt/com.mycompany/blob with contents
3080 DEF("serial
", HAS_ARG, QEMU_OPTION_serial, \
3081 "-serial dev redirect the serial port to char device
'dev'\n",
3084 @item -serial @var{dev}
3086 Redirect the virtual serial port to host character device
3087 @var{dev}. The default device is @code{vc} in graphical mode and
3088 @code{stdio} in non graphical mode.
3090 This option can be used several times to simulate up to 4 serial
3093 Use @code{-serial none} to disable all serial ports.
3095 Available character devices are:
3097 @item vc[:@var{W}x@var{H}]
3098 Virtual console. Optionally, a width and height can be given in pixel with
3102 It is also possible to specify width or height in characters:
3107 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3109 No device is allocated.
3112 @item chardev:@var{id}
3113 Use a named character device defined with the @code{-chardev} option.
3115 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3116 parameters are set according to the emulated ones.
3117 @item /dev/parport@var{N}
3118 [Linux only, parallel port only] Use host parallel port
3119 @var{N}. Currently SPP and EPP parallel port features can be used.
3120 @item file:@var{filename}
3121 Write output to @var{filename}. No character can be read.
3123 [Unix only] standard input/output
3124 @item pipe:@var{filename}
3125 name pipe @var{filename}
3127 [Windows only] Use host serial port @var{n}
3128 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3129 This implements UDP Net Console.
3130 When @var{remote_host} or @var{src_ip} are not specified
3131 they default to @code{0.0.0.0}.
3132 When not using a specified @var{src_port} a random port is automatically chosen.
3134 If you just want a simple readonly console you can use @code{netcat} or
3135 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3136 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
3137 will appear in the netconsole session.
3139 If you plan to send characters back via netconsole or you want to stop
3140 and start QEMU a lot of times, you should have QEMU use the same
3141 source port each time by using something like @code{-serial
3142 udp::4555@@:4556} to QEMU. Another approach is to use a patched
3143 version of netcat which can listen to a TCP port and send and receive
3144 characters via udp. If you have a patched version of netcat which
3145 activates telnet remote echo and single char transfer, then you can
3146 use the following options to set up a netcat redirector to allow
3147 telnet on port 5555 to access the QEMU port.
3150 -serial udp::4555@@:4556
3151 @item netcat options:
3152 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3153 @item telnet options:
3157 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
3158 The TCP Net Console has two modes of operation. It can send the serial
3159 I/O to a location or wait for a connection from a location. By default
3160 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3161 the @var{server} option QEMU will wait for a client socket application
3162 to connect to the port before continuing, unless the @code{nowait}
3163 option was specified. The @code{nodelay} option disables the Nagle buffering
3164 algorithm. The @code{reconnect} option only applies if @var{noserver} is
3165 set, if the connection goes down it will attempt to reconnect at the
3166 given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
3167 one TCP connection at a time is accepted. You can use @code{telnet} to
3168 connect to the corresponding character device.
3170 @item Example to send tcp console to 192.168.0.2 port 4444
3171 -serial tcp:192.168.0.2:4444
3172 @item Example to listen and wait on port 4444 for connection
3173 -serial tcp::4444,server
3174 @item Example to not wait and listen on ip 192.168.0.100 port 4444
3175 -serial tcp:192.168.0.100:4444,server,nowait
3178 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3179 The telnet protocol is used instead of raw tcp sockets. The options
3180 work the same as if you had specified @code{-serial tcp}. The
3181 difference is that the port acts like a telnet server or client using
3182 telnet option negotiation. This will also allow you to send the
3183 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3184 sequence. Typically in unix telnet you do it with Control-] and then
3185 type "send
break" followed by pressing the enter key.
3187 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
3188 A unix domain socket is used instead of a tcp socket. The option works the
3189 same as if you had specified @code{-serial tcp} except the unix domain socket
3190 @var{path} is used for connections.
3192 @item mon:@var{dev_string}
3193 This is a special option to allow the monitor to be multiplexed onto
3194 another serial port. The monitor is accessed with key sequence of
3195 @key{Control-a} and then pressing @key{c}.
3196 @var{dev_string} should be any one of the serial devices specified
3197 above. An example to multiplex the monitor onto a telnet server
3198 listening on port 4444 would be:
3200 @item -serial mon:telnet::4444,server,nowait
3202 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3203 QEMU any more but will be passed to the guest instead.
3206 Braille device. This will use BrlAPI to display the braille output on a real
3210 Three button serial mouse. Configure the guest to use Microsoft protocol.
3214 DEF("parallel
", HAS_ARG, QEMU_OPTION_parallel, \
3215 "-parallel dev redirect the parallel port to char device
'dev'\n",
3218 @item -parallel @var{dev}
3220 Redirect the virtual parallel port to host device @var{dev} (same
3221 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3222 be used to use hardware devices connected on the corresponding host
3225 This option can be used several times to simulate up to 3 parallel
3228 Use @code{-parallel none} to disable all parallel ports.
3231 DEF("monitor
", HAS_ARG, QEMU_OPTION_monitor, \
3232 "-monitor dev redirect the monitor to char device
'dev'\n",
3235 @item -monitor @var{dev}
3237 Redirect the monitor to host device @var{dev} (same devices as the
3239 The default device is @code{vc} in graphical mode and @code{stdio} in
3241 Use @code{-monitor none} to disable the default monitor.
3243 DEF("qmp
", HAS_ARG, QEMU_OPTION_qmp, \
3244 "-qmp dev like
-monitor but opens
in 'control' mode
\n",
3247 @item -qmp @var{dev}
3249 Like -monitor but opens in 'control' mode.
3251 DEF("qmp
-pretty
", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3252 "-qmp
-pretty dev like
-qmp but uses pretty JSON formatting
\n",
3255 @item -qmp-pretty @var{dev}
3257 Like -qmp but uses pretty JSON formatting.
3260 DEF("mon
", HAS_ARG, QEMU_OPTION_mon, \
3261 "-mon
[chardev
=]name
[,mode
=readline|control
]\n", QEMU_ARCH_ALL)
3263 @item -mon [chardev=]name[,mode=readline|control]
3265 Setup monitor on chardev @var{name}.
3268 DEF("debugcon
", HAS_ARG, QEMU_OPTION_debugcon, \
3269 "-debugcon dev redirect the debug console to char device
'dev'\n",
3272 @item -debugcon @var{dev}
3274 Redirect the debug console to host device @var{dev} (same devices as the
3275 serial port). The debug console is an I/O port which is typically port
3276 0xe9; writing to that I/O port sends output to this device.
3277 The default device is @code{vc} in graphical mode and @code{stdio} in
3281 DEF("pidfile
", HAS_ARG, QEMU_OPTION_pidfile, \
3282 "-pidfile file write PID to
'file'\n", QEMU_ARCH_ALL)
3284 @item -pidfile @var{file}
3286 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3290 DEF("singlestep
", 0, QEMU_OPTION_singlestep, \
3291 "-singlestep always run
in singlestep mode
\n", QEMU_ARCH_ALL)
3295 Run the emulation in single step mode.
3298 DEF("S
", 0, QEMU_OPTION_S, \
3299 "-S freeze CPU at
startup (use
'c' to start execution
)\n",
3304 Do not start CPU at startup (you must type 'c' in the monitor).
3307 DEF("realtime
", HAS_ARG, QEMU_OPTION_realtime,
3308 "-realtime
[mlock
=on|off
]\n"
3309 " run qemu with realtime features
\n"
3310 " mlock
=on|off controls mlock
support (default: on
)\n",
3313 @item -realtime mlock=on|off
3315 Run qemu with realtime features.
3316 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3317 (enabled by default).
3320 DEF("gdb
", HAS_ARG, QEMU_OPTION_gdb, \
3321 "-gdb dev wait
for gdb connection on
'dev'\n", QEMU_ARCH_ALL)
3323 @item -gdb @var{dev}
3325 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3326 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3327 stdio are reasonable use case. The latter is allowing to start QEMU from
3328 within gdb and establish the connection via a pipe:
3330 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3334 DEF("s
", 0, QEMU_OPTION_s, \
3335 "-s shorthand
for -gdb tcp
::" DEFAULT_GDBSTUB_PORT "\n",
3340 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3341 (@pxref{gdb_usage}).
3344 DEF("d
", HAS_ARG, QEMU_OPTION_d, \
3345 "-d item1
,... enable logging of specified
items (use
'-d help' for a list of log items
)\n",
3348 @item -d @var{item1}[,...]
3350 Enable logging of specified items. Use '-d help' for a list of log items.
3353 DEF("D
", HAS_ARG, QEMU_OPTION_D, \
3354 "-D logfile output log to
logfile (default stderr
)\n",
3357 @item -D @var{logfile}
3359 Output log in @var{logfile} instead of to stderr
3362 DEF("dfilter
", HAS_ARG, QEMU_OPTION_DFILTER, \
3363 "-dfilter range
,.. filter debug output to range of
addresses (useful
for -d cpu
,exec
,etc
..)\n",
3366 @item -dfilter @var{range1}[,...]
3368 Filter debug output to that relevant to a range of target addresses. The filter
3369 spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3370 @var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3371 addresses and sizes required. For example:
3373 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3375 Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3376 the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3377 block starting at 0xffffffc00005f000.
3380 DEF("L
", HAS_ARG, QEMU_OPTION_L, \
3381 "-L path set the directory
for the BIOS
, VGA BIOS and keymaps
\n",
3386 Set the directory for the BIOS, VGA BIOS and keymaps.
3388 To list all the data directories, use @code{-L help}.
3391 DEF("bios
", HAS_ARG, QEMU_OPTION_bios, \
3392 "-bios file set the filename
for the BIOS
\n", QEMU_ARCH_ALL)
3394 @item -bios @var{file}
3396 Set the filename for the BIOS.
3399 DEF("enable
-kvm
", 0, QEMU_OPTION_enable_kvm, \
3400 "-enable
-kvm enable KVM full virtualization support
\n", QEMU_ARCH_ALL)
3404 Enable KVM full virtualization support. This option is only available
3405 if KVM support is enabled when compiling.
3408 DEF("enable
-hax
", 0, QEMU_OPTION_enable_hax, \
3409 "-enable
-hax enable HAX virtualization support
\n", QEMU_ARCH_I386)
3413 Enable HAX (Hardware-based Acceleration eXecution) support. This option
3414 is only available if HAX support is enabled when compiling. HAX is only
3415 applicable to MAC and Windows platform, and thus does not conflict with
3419 DEF("xen
-domid
", HAS_ARG, QEMU_OPTION_xen_domid,
3420 "-xen
-domid id specify xen guest domain id
\n", QEMU_ARCH_ALL)
3421 DEF("xen
-create
", 0, QEMU_OPTION_xen_create,
3422 "-xen
-create create domain
using xen hypercalls
, bypassing xend
\n"
3423 " warning
: should not be used when xend is
in use
\n",
3425 DEF("xen
-attach
", 0, QEMU_OPTION_xen_attach,
3426 "-xen
-attach attach to existing xen domain
\n"
3427 " xend will use
this when starting QEMU
\n",
3429 DEF("xen
-domid
-restrict
", 0, QEMU_OPTION_xen_domid_restrict,
3430 "-xen
-domid
-restrict restrict set of available xen operations
\n"
3431 " to specified domain id
. (Does not affect
\n"
3432 " xenpv machine type
).\n",
3435 @item -xen-domid @var{id}
3437 Specify xen guest domain @var{id} (XEN only).
3440 Create domain using xen hypercalls, bypassing xend.
3441 Warning: should not be used when xend is in use (XEN only).
3444 Attach to existing xen domain.
3445 xend will use this when starting QEMU (XEN only).
3446 @findex -xen-domid-restrict
3447 Restrict set of available xen operations to specified domain id (XEN only).
3450 DEF("no
-reboot
", 0, QEMU_OPTION_no_reboot, \
3451 "-no
-reboot exit instead of rebooting
\n", QEMU_ARCH_ALL)
3455 Exit instead of rebooting.
3458 DEF("no
-shutdown
", 0, QEMU_OPTION_no_shutdown, \
3459 "-no
-shutdown stop before shutdown
\n", QEMU_ARCH_ALL)
3462 @findex -no-shutdown
3463 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3464 This allows for instance switching to monitor to commit changes to the
3468 DEF("loadvm
", HAS_ARG, QEMU_OPTION_loadvm, \
3469 "-loadvm
[tag|id
]\n" \
3470 " start right away with a saved
state (loadvm
in monitor
)\n",
3473 @item -loadvm @var{file}
3475 Start right away with a saved state (@code{loadvm} in monitor)
3479 DEF("daemonize
", 0, QEMU_OPTION_daemonize, \
3480 "-daemonize daemonize QEMU after initializing
\n", QEMU_ARCH_ALL)
3485 Daemonize the QEMU process after initialization. QEMU will not detach from
3486 standard IO until it is ready to receive connections on any of its devices.
3487 This option is a useful way for external programs to launch QEMU without having
3488 to cope with initialization race conditions.
3491 DEF("option
-rom
", HAS_ARG, QEMU_OPTION_option_rom, \
3492 "-option
-rom rom load a file
, rom
, into the option ROM space
\n",
3495 @item -option-rom @var{file}
3497 Load the contents of @var{file} as an option ROM.
3498 This option is useful to load things like EtherBoot.
3501 HXCOMM Silently ignored for compatibility
3502 DEF("clock
", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
3504 HXCOMM Options deprecated by -rtc
3505 DEF("localtime
", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3506 DEF("startdate
", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
3508 DEF("rtc
", HAS_ARG, QEMU_OPTION_rtc, \
3509 "-rtc
[base
=utc|localtime|date
][,clock
=host|rt|vm
][,driftfix
=none|slew
]\n" \
3510 " set the RTC base and clock
, enable drift fix
for clock
ticks (x86 only
)\n",
3515 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3517 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3518 UTC or local time, respectively. @code{localtime} is required for correct date in
3519 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3520 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3522 By default the RTC is driven by the host system time. This allows using of the
3523 RTC as accurate reference clock inside the guest, specifically if the host
3524 time is smoothly following an accurate external reference clock, e.g. via NTP.
3525 If you want to isolate the guest time from the host, you can set @option{clock}
3526 to @code{rt} instead. To even prevent it from progressing during suspension,
3527 you can set it to @code{vm}.
3529 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3530 specifically with Windows' ACPI HAL. This option will try to figure out how
3531 many timer interrupts were not processed by the Windows guest and will
3535 DEF("icount
", HAS_ARG, QEMU_OPTION_icount, \
3536 "-icount
[shift
=N|auto
][,align
=on|off
][,sleep
=on|off
,rr
=record|replay
,rrfile
=<filename
>,rrsnapshot
=<snapshot
>]\n" \
3537 " enable virtual instruction counter with
2^N clock ticks per
\n" \
3538 " instruction
, enable aligning the host and virtual clocks
\n" \
3539 " or disable real time cpu sleeping
\n", QEMU_ARCH_ALL)
3541 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
3543 Enable virtual instruction counter. The virtual cpu will execute one
3544 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
3545 then the virtual cpu speed will be automatically adjusted to keep virtual
3546 time within a few seconds of real time.
3548 When the virtual cpu is sleeping, the virtual time will advance at default
3549 speed unless @option{sleep=on|off} is specified.
3550 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3551 instantly whenever the virtual cpu goes to sleep mode and will not advance
3552 if no timer is enabled. This behavior give deterministic execution times from
3553 the guest point of view.
3555 Note that while this option can give deterministic behavior, it does not
3556 provide cycle accurate emulation. Modern CPUs contain superscalar out of
3557 order cores with complex cache hierarchies. The number of instructions
3558 executed often has little or no correlation with actual performance.
3560 @option{align=on} will activate the delay algorithm which will try
3561 to synchronise the host clock and the virtual clock. The goal is to
3562 have a guest running at the real frequency imposed by the shift option.
3563 Whenever the guest clock is behind the host clock and if
3564 @option{align=on} is specified then we print a message to the user
3565 to inform about the delay.
3566 Currently this option does not work when @option{shift} is @code{auto}.
3567 Note: The sync algorithm will work for those shift values for which
3568 the guest clock runs ahead of the host clock. Typically this happens
3569 when the shift value is high (how high depends on the host machine).
3571 When @option{rr} option is specified deterministic record/replay is enabled.
3572 Replay log is written into @var{filename} file in record mode and
3573 read from this file in replay mode.
3575 Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3576 at the start of execution recording. In replay mode this option is used
3577 to load the initial VM state.
3580 DEF("watchdog
", HAS_ARG, QEMU_OPTION_watchdog, \
3581 "-watchdog model
\n" \
3582 " enable virtual hardware watchdog
[default=none
]\n",
3585 @item -watchdog @var{model}
3587 Create a virtual hardware watchdog device. Once enabled (by a guest
3588 action), the watchdog must be periodically polled by an agent inside
3589 the guest or else the guest will be restarted. Choose a model for
3590 which your guest has drivers.
3592 The @var{model} is the model of hardware watchdog to emulate. Use
3593 @code{-watchdog help} to list available hardware models. Only one
3594 watchdog can be enabled for a guest.
3596 The following models may be available:
3599 iBASE 700 is a very simple ISA watchdog with a single timer.
3601 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3602 dual-timer watchdog.
3604 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3605 (currently KVM only).
3609 DEF("watchdog
-action
", HAS_ARG, QEMU_OPTION_watchdog_action, \
3610 "-watchdog
-action reset|shutdown|poweroff|pause|debug|none
\n" \
3611 " action when watchdog fires
[default=reset
]\n",
3614 @item -watchdog-action @var{action}
3615 @findex -watchdog-action
3617 The @var{action} controls what QEMU will do when the watchdog timer
3620 @code{reset} (forcefully reset the guest).
3621 Other possible actions are:
3622 @code{shutdown} (attempt to gracefully shutdown the guest),
3623 @code{poweroff} (forcefully poweroff the guest),
3624 @code{pause} (pause the guest),
3625 @code{debug} (print a debug message and continue), or
3626 @code{none} (do nothing).
3628 Note that the @code{shutdown} action requires that the guest responds
3629 to ACPI signals, which it may not be able to do in the sort of
3630 situations where the watchdog would have expired, and thus
3631 @code{-watchdog-action shutdown} is not recommended for production use.
3636 @item -watchdog i6300esb -watchdog-action pause
3637 @itemx -watchdog ib700
3641 DEF("echr
", HAS_ARG, QEMU_OPTION_echr, \
3642 "-echr chr set terminal escape character instead of ctrl
-a
\n",
3646 @item -echr @var{numeric_ascii_value}
3648 Change the escape character used for switching to the monitor when using
3649 monitor and serial sharing. The default is @code{0x01} when using the
3650 @code{-nographic} option. @code{0x01} is equal to pressing
3651 @code{Control-a}. You can select a different character from the ascii
3652 control keys where 1 through 26 map to Control-a through Control-z. For
3653 instance you could use the either of the following to change the escape
3654 character to Control-t.
3661 DEF("virtioconsole
", HAS_ARG, QEMU_OPTION_virtiocon, \
3662 "-virtioconsole c
\n" \
3663 " set virtio console
\n", QEMU_ARCH_ALL)
3665 @item -virtioconsole @var{c}
3666 @findex -virtioconsole
3669 This option is maintained for backward compatibility.
3671 Please use @code{-device virtconsole} for the new way of invocation.
3674 DEF("show
-cursor
", 0, QEMU_OPTION_show_cursor, \
3675 "-show
-cursor show cursor
\n", QEMU_ARCH_ALL)
3678 @findex -show-cursor
3682 DEF("tb
-size
", HAS_ARG, QEMU_OPTION_tb_size, \
3683 "-tb
-size n set TB size
\n", QEMU_ARCH_ALL)
3685 @item -tb-size @var{n}
3690 DEF("incoming
", HAS_ARG, QEMU_OPTION_incoming, \
3691 "-incoming tcp
:[host
]:port
[,to
=maxport
][,ipv4
][,ipv6
]\n" \
3692 "-incoming rdma
:host
:port
[,ipv4
][,ipv6
]\n" \
3693 "-incoming unix
:socketpath
\n" \
3694 " prepare
for incoming migration
, listen on
\n" \
3695 " specified protocol and socket address
\n" \
3696 "-incoming fd
:fd
\n" \
3697 "-incoming exec
:cmdline
\n" \
3698 " accept incoming migration on given file descriptor
\n" \
3699 " or from given external command
\n" \
3700 "-incoming defer
\n" \
3701 " wait
for the URI to be specified via migrate_incoming
\n",
3704 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3705 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3707 Prepare for incoming migration, listen on a given tcp port.
3709 @item -incoming unix:@var{socketpath}
3710 Prepare for incoming migration, listen on a given unix socket.
3712 @item -incoming fd:@var{fd}
3713 Accept incoming migration from a given filedescriptor.
3715 @item -incoming exec:@var{cmdline}
3716 Accept incoming migration as an output from specified external command.
3718 @item -incoming defer
3719 Wait for the URI to be specified via migrate_incoming. The monitor can
3720 be used to change settings (such as migration parameters) prior to issuing
3721 the migrate_incoming to allow the migration to begin.
3724 DEF("only
-migratable
", 0, QEMU_OPTION_only_migratable, \
3725 "-only
-migratable allow only migratable devices
\n", QEMU_ARCH_ALL)
3727 @item -only-migratable
3728 @findex -only-migratable
3729 Only allow migratable devices. Devices will not be allowed to enter an
3733 DEF("nodefaults
", 0, QEMU_OPTION_nodefaults, \
3734 "-nodefaults don
't create default devices\n", QEMU_ARCH_ALL)
3738 Don't create
default devices
. Normally
, QEMU sets the
default devices like serial
3739 port
, parallel port
, virtual console
, monitor device
, VGA adapter
, floppy and
3740 CD
-ROM drive and others
. The @code
{-nodefaults
} option will disable all those
3745 DEF("chroot", HAS_ARG
, QEMU_OPTION_chroot
, \
3746 "-chroot dir chroot to dir just before starting the VM\n",
3750 @item
-chroot @
var{dir
}
3752 Immediately before starting guest execution
, chroot to the specified
3753 directory
. Especially useful
in combination with
-runas
.
3757 DEF("runas", HAS_ARG
, QEMU_OPTION_runas
, \
3758 "-runas user change to user id user just before starting the VM\n",
3762 @item
-runas @
var{user
}
3764 Immediately before starting guest execution
, drop root privileges
, switching
3765 to the specified user
.
3768 DEF("prom-env", HAS_ARG
, QEMU_OPTION_prom_env
,
3769 "-prom-env variable=value\n"
3770 " set OpenBIOS nvram variables\n",
3771 QEMU_ARCH_PPC | QEMU_ARCH_SPARC
)
3773 @item
-prom
-env @
var{variable
}=@
var{value
}
3775 Set OpenBIOS nvram @
var{variable
} to given @
var{value
} (PPC
, SPARC only
).
3777 DEF("semihosting", 0, QEMU_OPTION_semihosting
,
3778 "-semihosting semihosting mode\n",
3779 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3783 @findex
-semihosting
3784 Enable semihosting
mode (ARM
, M68K
, Xtensa
, MIPS only
).
3786 DEF("semihosting-config", HAS_ARG
, QEMU_OPTION_semihosting_config
,
3787 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3788 " semihosting configuration\n",
3789 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3792 @item
-semihosting
-config
[enable
=on|off
][,target
=native|gdb|auto
][,arg
=str
[,...]]
3793 @findex
-semihosting
-config
3794 Enable and configure
semihosting (ARM
, M68K
, Xtensa
, MIPS only
).
3796 @item target
=@code
{native|gdb|auto
}
3797 Defines where the semihosting calls will be addressed
, to
QEMU (@code
{native
})
3798 or to
GDB (@code
{gdb
}). The
default is @code
{auto
}, which means @code
{gdb
}
3799 during debug sessions and @code
{native
} otherwise
.
3800 @item arg
=@
var{str1
},arg
=@
var{str2
},...
3801 Allows the user to pass input arguments
, and can be used multiple times to build
3802 up a list
. The old
-style @code
{-kernel
}/@code
{-append
} method of passing a
3803 command line is still supported
for backward compatibility
. If both the
3804 @code
{--semihosting
-config arg
} and the @code
{-kernel
}/@code
{-append
} are
3805 specified
, the former is passed to semihosting as it always takes precedence
.
3808 DEF("old-param", 0, QEMU_OPTION_old_param
,
3809 "-old-param old param mode\n", QEMU_ARCH_ARM
)
3812 @findex
-old
-param (ARM
)
3813 Old param
mode (ARM only
).
3816 DEF("sandbox", HAS_ARG
, QEMU_OPTION_sandbox
, \
3817 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
3820 @item
-sandbox @
var{arg
}
3822 Enable Seccomp mode
2 system call filter
. 'on' will enable syscall filtering and
'off' will
3823 disable it
. The
default is
'off'.
3826 DEF("readconfig", HAS_ARG
, QEMU_OPTION_readconfig
,
3827 "-readconfig <file>\n", QEMU_ARCH_ALL
)
3829 @item
-readconfig @
var{file
}
3831 Read device configuration from @
var{file
}. This approach is useful when you want to spawn
3832 QEMU process with many command line options but you don
't want to exceed the command line
3835 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3836 "-writeconfig <file>\n"
3837 " read/write config file\n", QEMU_ARCH_ALL)
3839 @item -writeconfig @var{file}
3840 @findex -writeconfig
3841 Write device configuration to @var{file}. The @var{file} can be either filename to save
3842 command line and device configuration into file or dash @code{-}) character to print the
3843 output to stdout. This can be later used as input file for @code{-readconfig} option.
3845 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3847 " do not load default config files at startup\n",
3851 @findex -nodefconfig
3852 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3853 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3855 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3857 " do not load user-provided config files at startup\n",
3860 @item -no-user-config
3861 @findex -no-user-config
3862 The @code{-no-user-config} option makes QEMU not load any of the user-provided
3863 config files on @var{sysconfdir}, but won't make it skip the QEMU
-provided config
3864 files from @
var{datadir
}.
3866 DEF("trace", HAS_ARG
, QEMU_OPTION_trace
,
3867 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
3868 " specify tracing options\n",
3871 HXCOMM This line is not accurate
, as some sub
-options are backend
-specific but
3872 HXCOMM HX does not support conditional compilation of text
.
3873 @item
-trace [[enable
=]@
var{pattern
}][,events
=@
var{file
}][,file
=@
var{file
}]
3875 @include qemu
-option
-trace.texi
3879 DEF("qtest", HAS_ARG
, QEMU_OPTION_qtest
, "", QEMU_ARCH_ALL
)
3880 DEF("qtest-log", HAS_ARG
, QEMU_OPTION_qtest_log
, "", QEMU_ARCH_ALL
)
3883 DEF("enable-fips", 0, QEMU_OPTION_enablefips
,
3884 "-enable-fips enable FIPS 140-2 compliance\n",
3889 @findex
-enable
-fips
3890 Enable FIPS
140-2 compliance mode
.
3893 HXCOMM Deprecated by
-machine accel
=tcg property
3894 DEF("no-kvm", 0, QEMU_OPTION_no_kvm
, "", QEMU_ARCH_I386
)
3896 HXCOMM Deprecated by kvm
-pit driver properties
3897 DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection
,
3900 HXCOMM
Deprecated (ignored
)
3901 DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit
, "", QEMU_ARCH_I386
)
3903 HXCOMM Deprecated by
-machine kernel_irqchip
=on|off property
3904 DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip
, "", QEMU_ARCH_I386
)
3906 HXCOMM
Deprecated (ignored
)
3907 DEF("tdf", 0, QEMU_OPTION_tdf
,"", QEMU_ARCH_ALL
)
3909 DEF("msg", HAS_ARG
, QEMU_OPTION_msg
,
3910 "-msg timestamp[=on|off]\n"
3911 " change the format of messages\n"
3912 " on|off controls leading timestamps (default:on)\n",
3915 @item
-msg timestamp
[=on|off
]
3917 prepend a timestamp to each log message
.(default:on
)
3920 DEF("dump-vmstate", HAS_ARG
, QEMU_OPTION_dump_vmstate
,
3921 "-dump-vmstate <file>\n"
3922 " Output vmstate information in JSON format to file.\n"
3923 " Use the scripts/vmstate-static-checker.py file to\n"
3924 " check for possible regressions in migration code\n"
3925 " by comparing two such vmstate dumps.\n",
3928 @item
-dump
-vmstate @
var{file
}
3929 @findex
-dump
-vmstate
3930 Dump json
-encoded vmstate information
for current machine type to file
3938 DEFHEADING(Generic object creation
)
3943 DEF("object", HAS_ARG
, QEMU_OPTION_object
,
3944 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3945 " create a new object of type TYPENAME setting properties\n"
3946 " in the order they are specified. Note that the 'id'\n"
3947 " property must be set. These objects are placed in the\n"
3948 " '/objects' path.\n",
3951 @item
-object @
var{typename
}[,@
var{prop1
}=@
var{value1
},...]
3953 Create a
new object of type @
var{typename
} setting properties
3954 in the order they are specified
. Note that the
'id'
3955 property must be set
. These objects are placed
in the
3960 @item
-object memory
-backend
-file
,id
=@
var{id
},size
=@
var{size
},mem
-path
=@
var{dir
},share
=@
var{on|off
}
3962 Creates a memory file backend object
, which can be used to back
3963 the guest RAM with huge pages
. The @option
{id
} parameter is a
3964 unique ID that will be used to reference
this memory region
3965 when configuring the @option
{-numa
} argument
. The @option
{size
}
3966 option provides the size of the memory region
, and accepts
3967 common suffixes
, eg @option
{500M
}. The @option
{mem
-path
} provides
3968 the path to either a shared memory or huge page filesystem mount
.
3969 The @option
{share
} boolean option determines whether the memory
3970 region is marked as
private to QEMU
, or shared
. The latter allows
3971 a co
-operating external process to access the QEMU memory region
.
3973 @item
-object rng
-random
,id
=@
var{id
},filename
=@
var{/dev
/random
}
3975 Creates a random number generator backend which obtains entropy from
3976 a device on the host
. The @option
{id
} parameter is a unique ID that
3977 will be used to reference
this entropy backend from the @option
{virtio
-rng
}
3978 device
. The @option
{filename
} parameter specifies which file to obtain
3979 entropy from and
if omitted defaults to @option
{/dev
/random
}.
3981 @item
-object rng
-egd
,id
=@
var{id
},chardev
=@
var{chardevid
}
3983 Creates a random number generator backend which obtains entropy from
3984 an external daemon running on the host
. The @option
{id
} parameter is
3985 a unique ID that will be used to reference
this entropy backend from
3986 the @option
{virtio
-rng
} device
. The @option
{chardev
} parameter is
3987 the unique ID of a character device backend that provides the connection
3990 @item
-object tls
-creds
-anon
,id
=@
var{id
},endpoint
=@
var{endpoint
},dir
=@
var{/path
/to
/cred
/dir
},verify
-peer
=@
var{on|off
}
3992 Creates a TLS anonymous credentials object
, which can be used to provide
3993 TLS support on network backends
. The @option
{id
} parameter is a unique
3994 ID which network backends will use to access the credentials
. The
3995 @option
{endpoint
} is either @option
{server
} or @option
{client
} depending
3996 on whether the QEMU network backend that uses the credentials will be
3997 acting as a client or as a server
. If @option
{verify
-peer
} is enabled
3998 (the
default) then once the handshake is completed
, the peer credentials
3999 will be verified
, though
this is a no
-op
for anonymous credentials
.
4001 The @
var{dir
} parameter tells QEMU where to find the credential
4002 files
. For server endpoints
, this directory may contain a file
4003 @
var{dh
-params
.pem
} providing diffie
-hellman parameters to use
4004 for the TLS server
. If the file is missing
, QEMU will generate
4005 a set of DH parameters at startup
. This is a computationally
4006 expensive operation that consumes random pool entropy
, so it is
4007 recommended that a persistent set of parameters be generated
4010 @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
}
4012 Creates a TLS anonymous credentials object
, which can be used to provide
4013 TLS support on network backends
. The @option
{id
} parameter is a unique
4014 ID which network backends will use to access the credentials
. The
4015 @option
{endpoint
} is either @option
{server
} or @option
{client
} depending
4016 on whether the QEMU network backend that uses the credentials will be
4017 acting as a client or as a server
. If @option
{verify
-peer
} is enabled
4018 (the
default) then once the handshake is completed
, the peer credentials
4019 will be verified
. With x509 certificates
, this implies that the clients
4020 must be provided with valid client certificates too
.
4022 The @
var{dir
} parameter tells QEMU where to find the credential
4023 files
. For server endpoints
, this directory may contain a file
4024 @
var{dh
-params
.pem
} providing diffie
-hellman parameters to use
4025 for the TLS server
. If the file is missing
, QEMU will generate
4026 a set of DH parameters at startup
. This is a computationally
4027 expensive operation that consumes random pool entropy
, so it is
4028 recommended that a persistent set of parameters be generated
4031 For x509 certificate credentials the directory will contain further files
4032 providing the x509 certificates
. The certificates must be stored
4033 in PEM format
, in filenames @
var{ca
-cert
.pem
}, @
var{ca
-crl
.pem
} (optional
),
4034 @
var{server
-cert
.pem
} (only servers
), @
var{server
-key
.pem
} (only servers
),
4035 @
var{client
-cert
.pem
} (only clients
), and @
var{client
-key
.pem
} (only clients
).
4037 For the @
var{server
-key
.pem
} and @
var{client
-key
.pem
} files which
4038 contain sensitive
private keys
, it is possible to use an encrypted
4039 version by providing the @
var{passwordid
} parameter
. This provides
4040 the ID of a previously created @code
{secret
} object containing the
4041 password
for decryption
.
4043 @item
-object filter
-buffer
,id
=@
var{id
},netdev
=@
var{netdevid
},interval
=@
var{t
}[,queue
=@
var{all|rx|tx
}][,status
=@
var{on|off
}]
4045 Interval @
var{t
} can
't be 0, this filter batches the packet delivery: all
4046 packets arriving in a given interval on netdev @var{netdevid} are delayed
4047 until the end of the interval. Interval is in microseconds.
4048 @option{status} is optional that indicate whether the netfilter is
4049 on (enabled) or off (disabled), the default status for netfilter will be 'on
'.
4051 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4053 @option{all}: the filter is attached both to the receive and the transmit
4054 queue of the netdev (default).
4056 @option{rx}: the filter is attached to the receive queue of the netdev,
4057 where it will receive packets sent to the netdev.
4059 @option{tx}: the filter is attached to the transmit queue of the netdev,
4060 where it will receive packets sent by the netdev.
4062 @item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
4064 filter-mirror on netdev @var{netdevid},mirror net packet to chardev
4067 @item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},
4068 outdev=@var{chardevid}[,queue=@var{all|rx|tx}]
4070 filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
4071 @
var{chardevid
},and redirect indev
's packet to filter.
4072 Create a filter-redirector we need to differ outdev id from indev id, id can not
4073 be the same. we can just use indev or outdev, but at least one of indev or outdev
4074 need to be specified.
4076 @item -object filter-rewriter,id=@var{id},netdev=@var{netdevid}[,queue=@var{all|rx|tx}]
4078 Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4079 secondary from primary to keep secondary tcp connection,and rewrite
4080 tcp packet to primary from secondary make tcp packet can be handled by
4085 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4086 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4087 -object filter-rewriter,id=rew0,netdev=hn0,queue=all
4089 @item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
4091 Dump the network traffic on netdev @var{dev} to the file specified by
4092 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4093 The file format is libpcap, so it can be analyzed with tools such as tcpdump
4096 @item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},
4097 outdev=@var{chardevid}
4099 Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4100 secondary packet. If the packets are same, we will output primary
4101 packet to outdev@var{chardevid}, else we will notify colo-frame
4102 do checkpoint and send primary packet to outdev@var{chardevid}.
4104 we must use it with the help of filter-mirror and filter-redirector.
4109 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4110 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4111 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4112 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4113 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4114 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4115 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4116 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4117 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4118 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4119 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4120 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4123 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4124 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4125 -chardev socket,id=red0,host=3.3.3.3,port=9003
4126 -chardev socket,id=red1,host=3.3.3.3,port=9004
4127 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4128 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4132 If you want to know the detail of above command line, you can read
4133 the colo-compare git log.
4135 @item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4137 Creates a cryptodev backend which executes crypto opreation from
4138 the QEMU cipher APIS. The @var{id} parameter is
4139 a unique ID that will be used to reference this cryptodev backend from
4140 the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4141 which specify the queue number of cryptodev backend, the default of
4146 # qemu-system-x86_64 \
4148 -object cryptodev-backend-builtin,id=cryptodev0 \
4149 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4153 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4154 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4156 Defines a secret to store a password, encryption key, or some other sensitive
4157 data. The sensitive data can either be passed directly via the @var{data}
4158 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4159 parameter is insecure unless the sensitive data is encrypted.
4161 The sensitive data can be provided in raw format (the default), or base64.
4162 When encoded as JSON, the raw format only supports valid UTF-8 characters,
4163 so base64 is recommended for sending binary data. QEMU will convert from
4164 which ever format is provided to the format it needs internally. eg, an
4165 RBD password can be provided in raw format, even though it will be base64
4166 encoded when passed onto the RBD sever.
4168 For added protection, it is possible to encrypt the data associated with
4169 a secret using the AES-256-CBC cipher. Use of encryption is indicated
4170 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4171 parameter provides the ID of a previously defined secret that contains
4172 the AES-256 decryption key. This key should be 32-bytes long and be
4173 base64 encoded. The @var{iv} parameter provides the random initialization
4174 vector used for encryption of this particular secret and should be a
4175 base64 encrypted string of the 16-byte IV.
4177 The simplest (insecure) usage is to provide the secret inline
4181 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4185 The simplest secure usage is to provide the secret via a file
4187 # echo -n "letmein" > mypasswd.txt
4188 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4190 For greater security, AES-256-CBC should be used. To illustrate usage,
4191 consider the openssl command line tool which can encrypt the data. Note
4192 that when encrypting, the plaintext must be padded to the cipher block
4193 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4195 First a master key needs to be created in base64 encoding:
4198 # openssl rand -base64 32 > key.b64
4199 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4202 Each secret to be encrypted needs to have a random initialization vector
4203 generated. These do not need to be kept secret
4206 # openssl rand -base64 16 > iv.b64
4207 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4210 The secret to be defined can now be encrypted, in this case we're
4211 telling openssl to base64 encode the result
, but it could be left
4212 as raw bytes
if desired
.
4215 # SECRET
=$
(echo
-n
"letmein" |
4216 openssl enc
-aes
-256-cbc
-a
-K $KEY
-iv $IV
)
4219 When launching QEMU
, create a master secret pointing to @code
{key
.b64
}
4220 and specify that to be used to decrypt the user password
. Pass the
4221 contents of @code
{iv
.b64
} to the second secret
4225 -object secret
,id
=secmaster0
,format
=base64
,file
=key
.b64 \
4226 -object secret
,id
=sec0
,keyid
=secmaster0
,format
=base64
,\
4227 data
=$SECRET
,iv
=$
(<iv
.b64
)
4235 HXCOMM This is the last statement
. Insert
new options before
this line
!