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, tcg (default: tcg)\n"
35 " kernel_irqchip=on|off controls accelerated irqchip support\n"
36 " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
37 " vmport=on|off|auto controls emulation of vmport (default: auto)\n"
38 " kvm_shadow_mem=size of KVM shadow MMU\n"
39 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
40 " mem-merge=on|off controls memory merge support (default: on)\n"
41 " iommu=on|off controls emulated Intel IOMMU (VT-d) support (default=off)\n"
42 " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
43 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
44 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
45 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
46 " nvdimm=on|off controls NVDIMM support (default=off)\n"
47 " enforce-config-section=on|off enforce configuration section migration (default=off)\n",
50 @item
-machine
[type
=]@
var{name
}[,prop
=@
var{value
}[,...]]
52 Select the emulated machine by @
var{name
}. Use @code
{-machine help
} to list
53 available machines
. Supported machine properties are
:
55 @item accel
=@
var{accels1
}[:@
var{accels2
}[:...]]
56 This is used to enable an accelerator
. Depending on the target architecture
,
57 kvm
, xen
, or tcg can be available
. By
default, tcg is used
. If there is more
58 than one accelerator specified
, the next one is used
if the previous one fails
60 @item kernel_irqchip
=on|off
61 Controls
in-kernel irqchip support
for the chosen accelerator when available
.
62 @item gfx_passthru
=on|off
63 Enables IGD GFX passthrough support
for the chosen machine when available
.
64 @item vmport
=on|off|auto
65 Enables emulation of VMWare IO port
, for vmmouse etc
. auto says to select the
66 value based on accel
. For accel
=xen the
default is off otherwise the
default
68 @item kvm_shadow_mem
=size
69 Defines the size of the KVM shadow MMU
.
70 @item dump
-guest
-core
=on|off
71 Include guest memory
in a core dump
. The
default is on
.
72 @item mem
-merge
=on|off
73 Enables or disables memory merge support
. This feature
, when supported by
74 the host
, de
-duplicates identical memory pages among VMs instances
77 Enables or disables emulated Intel
IOMMU (VT
-d
) support
. The
default is off
.
78 @item aes
-key
-wrap
=on|off
79 Enables or disables AES key wrapping support on s390
-ccw hosts
. This feature
80 controls whether AES wrapping keys will be created to allow
81 execution of AES cryptographic functions
. The
default is on
.
82 @item dea
-key
-wrap
=on|off
83 Enables or disables DEA key wrapping support on s390
-ccw hosts
. This feature
84 controls whether DEA wrapping keys will be created to allow
85 execution of DEA cryptographic functions
. The
default is on
.
87 Enables or disables NVDIMM support
. The
default is off
.
91 HXCOMM Deprecated by
-machine
92 DEF("M", HAS_ARG
, QEMU_OPTION_M
, "", QEMU_ARCH_ALL
)
94 DEF("cpu", HAS_ARG
, QEMU_OPTION_cpu
,
95 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL
)
97 @item
-cpu @
var{model
}
99 Select CPU
model (@code
{-cpu help
} for list and additional feature selection
)
102 DEF("smp", HAS_ARG
, QEMU_OPTION_smp
,
103 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
104 " set the number of CPUs to 'n' [default=1]\n"
105 " maxcpus= maximum number of total cpus, including\n"
106 " offline CPUs for hotplug, etc\n"
107 " cores= number of CPU cores on one socket\n"
108 " threads= number of threads on one CPU core\n"
109 " sockets= number of discrete sockets in the system\n",
112 @item
-smp
[cpus
=]@
var{n
}[,cores
=@
var{cores
}][,threads
=@
var{threads
}][,sockets
=@
var{sockets
}][,maxcpus
=@
var{maxcpus
}]
114 Simulate an SMP system with @
var{n
} CPUs
. On the PC target
, up to
255
115 CPUs are supported
. On Sparc32 target
, Linux limits the number of usable CPUs
117 For the PC target
, the number of @
var{cores
} per socket
, the number
118 of @
var{threads
} per cores and the total number of @
var{sockets
} can be
119 specified
. Missing values will be computed
. If any on the three values is
120 given
, the total number of CPUs @
var{n
} can be omitted
. @
var{maxcpus
}
121 specifies the maximum number of hotpluggable CPUs
.
124 DEF("numa", HAS_ARG
, QEMU_OPTION_numa
,
125 "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
126 "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL
)
128 @item
-numa node
[,mem
=@
var{size
}][,cpus
=@
var{cpu
[-cpu
]}][,nodeid
=@
var{node
}]
129 @itemx
-numa node
[,memdev
=@
var{id
}][,cpus
=@
var{cpu
[-cpu
]}][,nodeid
=@
var{node
}]
131 Simulate a multi node NUMA system
. If @samp
{mem
}, @samp
{memdev
}
132 and @samp
{cpus
} are omitted
, resources are split equally
. Also
, note
133 that the
-@option
{numa
} option doesn
't allocate any of the specified
134 resources. That is, it just assigns existing resources to NUMA nodes. This
135 means that one still has to use the @option{-m}, @option{-smp} options
136 to allocate RAM and VCPUs respectively, and possibly @option{-object}
137 to specify the memory backend for the @samp{memdev} suboption.
139 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one
140 node uses @samp{memdev}, all of them have to use it.
143 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
144 "-add-fd fd=fd,set=set[,opaque=opaque]\n"
145 " Add 'fd
' to fd 'set
'\n", QEMU_ARCH_ALL)
147 @item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
150 Add a file descriptor to an fd set. Valid options are:
154 This option defines the file descriptor of which a duplicate is added to fd set.
155 The file descriptor cannot be stdin, stdout, or stderr.
157 This option defines the ID of the fd set to add the file descriptor to.
158 @item opaque=@var{opaque}
159 This option defines a free-form string that can be used to describe @var{fd}.
162 You can open an image using pre-opened file descriptors from an fd set:
165 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
166 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
167 -drive file=/dev/fdset/2,index=0,media=disk
171 DEF("set", HAS_ARG, QEMU_OPTION_set,
172 "-set group.id.arg=value\n"
173 " set <arg> parameter for item <id> of type <group>\n"
174 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
176 @item -set @var{group}.@var{id}.@var{arg}=@var{value}
178 Set parameter @var{arg} for item @var{id} of type @var{group}\n"
181 DEF("global", HAS_ARG, QEMU_OPTION_global,
182 "-global driver.property=value\n"
183 "-global driver=driver,property=property,value=value\n"
184 " set a global default for a driver property\n",
187 @item -global @var{driver}.@var{prop}=@var{value}
188 @itemx -global driver=@var{driver},property=@var{property},value=@var{value}
190 Set default value of @var{driver}'s property @
var{prop
} to @
var{value
}, e
.g
.:
193 qemu
-system
-i386
-global ide
-drive
.physical_block_size
=4096 -drive file
=file
,if=ide
,index
=0,media
=disk
196 In particular
, you can use
this to set driver properties
for devices which are
197 created automatically by the machine model
. To create a device which is not
198 created automatically and set properties on it
, use
-@option
{device
}.
200 -global @
var{driver
}.@
var{prop
}=@
var{value
} is shorthand
for -global
201 driver
=@
var{driver
},property
=@
var{prop
},value
=@
var{value
}. The
202 longhand syntax works even when @
var{driver
} contains a dot
.
205 DEF("boot", HAS_ARG
, QEMU_OPTION_boot
,
206 "-boot [order=drives][,once=drives][,menu=on|off]\n"
207 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
208 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
209 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
210 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
211 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
214 @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
]
216 Specify boot order @
var{drives
} as a string of drive letters
. Valid
217 drive letters depend on the target architecture
. The x86 PC uses
: a
, b
218 (floppy
1 and
2), c (first hard disk
), d (first CD
-ROM
), n
-p (Etherboot
219 from network adapter
1-4), hard disk boot is the
default. To apply a
220 particular boot order only on the first startup
, specify it via
223 Interactive boot menus
/prompts can be enabled via @option
{menu
=on
} as far
224 as firmware
/BIOS supports them
. The
default is non
-interactive boot
.
226 A splash picture could be passed to bios
, enabling user to show it as logo
,
227 when option splash
=@
var{sp_name
} is given and menu
=on
, If firmware
/BIOS
228 supports them
. Currently Seabios
for X86 system support it
.
229 limitation
: The splash file could be a jpeg file or a BMP file
in 24 BPP
230 format(true color
). The resolution should be supported by the SVGA mode
, so
231 the recommended is
320x240
, 640x480
, 800x640
.
233 A timeout could be passed to bios
, guest will pause
for @
var{rb_timeout
} ms
234 when boot failed
, then reboot
. If @
var{rb_timeout
} is
'-1', guest will not
235 reboot
, qemu passes
'-1' to bios by
default. Currently Seabios
for X86
238 Do strict boot via @option
{strict
=on
} as far as firmware
/BIOS
239 supports it
. This only effects when boot priority is changed by
240 bootindex options
. The
default is non
-strict boot
.
243 #
try to boot from network first
, then from hard disk
244 qemu
-system
-i386
-boot order
=nc
245 # boot from CD
-ROM first
, switch back to
default order after reboot
246 qemu
-system
-i386
-boot once
=d
247 # boot with a splash picture
for 5 seconds
.
248 qemu
-system
-i386
-boot menu
=on
,splash
=/root
/boot
.bmp
,splash
-time
=5000
251 Note
: The legacy format
'-boot @var{drives}' is still supported but its
252 use is discouraged as it may be removed from future versions
.
255 DEF("m", HAS_ARG
, QEMU_OPTION_m
,
256 "-m[emory] [size=]megs[,slots=n,maxmem=size]\n"
257 " configure guest RAM\n"
258 " size: initial amount of guest memory\n"
259 " slots: number of hotplug slots (default: none)\n"
260 " maxmem: maximum amount of guest memory (default: none)\n"
261 "NOTE: Some architectures might enforce a specific granularity\n",
264 @item
-m
[size
=]@
var{megs
}[,slots
=n
,maxmem
=size
]
266 Sets guest startup RAM size to @
var{megs
} megabytes
. Default is
128 MiB
.
267 Optionally
, a suffix of ``M
'' or ``G
'' can be used to signify a value
in
268 megabytes or gigabytes respectively
. Optional pair @
var{slots
}, @
var{maxmem
}
269 could be used to set amount of hotpluggable memory slots and maximum amount of
270 memory
. Note that @
var{maxmem
} must be aligned to the page size
.
272 For example
, the following command
-line sets the guest startup RAM size to
273 1GB
, creates
3 slots to hotplug additional memory and sets the maximum
274 memory the guest can reach to
4GB
:
277 qemu
-system
-x86_64
-m
1G
,slots
=3,maxmem
=4G
280 If @
var{slots
} and @
var{maxmem
} are not specified
, memory hotplug won
't
281 be enabled and the guest startup RAM will never increase.
284 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
285 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
287 @item -mem-path @var{path}
289 Allocate guest RAM from a temporarily created file in @var{path}.
292 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
293 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
297 @findex -mem-prealloc
298 Preallocate memory when using -mem-path.
301 DEF("k", HAS_ARG, QEMU_OPTION_k,
302 "-k language use keyboard layout (for example 'fr
' for French)\n",
305 @item -k @var{language}
307 Use keyboard layout @var{language} (for example @code{fr} for
308 French). This option is only needed where it is not easy to get raw PC
309 keycodes (e.g. on Macs, with some X11 servers or with a VNC
310 display). You don't normally need to use it on PC
/Linux or PC
/Windows
313 The available layouts are
:
315 ar de
-ch es fo fr
-ca hu ja mk no pt
-br sv
316 da en
-gb et fr fr
-ch is lt nl pl ru th
317 de en
-us fi fr
-be hr it lv nl
-be pt sl tr
320 The
default is @code
{en
-us
}.
324 DEF("audio-help", 0, QEMU_OPTION_audio_help
,
325 "-audio-help print list of audio drivers and their options\n",
330 Will show the audio subsystem help
: list of drivers
, tunable
334 DEF("soundhw", HAS_ARG
, QEMU_OPTION_soundhw
,
335 "-soundhw c1,... enable audio support\n"
336 " and only specified sound cards (comma separated list)\n"
337 " use '-soundhw help' to get the list of supported cards\n"
338 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL
)
340 @item
-soundhw @
var{card1
}[,@
var{card2
},...] or
-soundhw all
342 Enable audio and selected sound hardware
. Use
'help' to print all
343 available sound hardware
.
346 qemu
-system
-i386
-soundhw sb16
,adlib disk
.img
347 qemu
-system
-i386
-soundhw es1370 disk
.img
348 qemu
-system
-i386
-soundhw ac97 disk
.img
349 qemu
-system
-i386
-soundhw hda disk
.img
350 qemu
-system
-i386
-soundhw all disk
.img
351 qemu
-system
-i386
-soundhw help
354 Note that Linux
's i810_audio OSS kernel (for AC97) module might
355 require manually specifying clocking.
358 modprobe i810_audio clocking=48000
362 DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
363 "-balloon none disable balloon device\n"
364 "-balloon virtio[,addr=str]\n"
365 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
369 Disable balloon device.
370 @item -balloon virtio[,addr=@var{addr}]
371 Enable virtio balloon device (default), optionally with PCI address
375 DEF("device", HAS_ARG, QEMU_OPTION_device,
376 "-device driver[,prop[=value][,...]]\n"
377 " add device (based on driver)\n"
378 " prop=value,... sets driver properties\n"
379 " use '-device help
' to print all possible drivers\n"
380 " use '-device driver
,help
' to print all possible properties\n",
383 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
385 Add device @var{driver}. @var{prop}=@var{value} sets driver
386 properties. Valid properties depend on the driver. To get help on
387 possible drivers and properties, use @code{-device help} and
388 @code{-device @var{driver},help}.
391 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}]
393 Add an IPMI BMC. This is a simulation of a hardware management
394 interface processor that normally sits on a system. It provides
395 a watchdog and the ability to reset and power control the system.
396 You need to connect this to an IPMI interface to make it useful
398 The IPMI slave address to use for the BMC. The default is 0x20.
399 This address is the BMC's address on the I2C network of management
400 controllers
. If you don
't know what this means, it is safe to ignore
403 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
405 Add a connection to an external IPMI BMC simulator. Instead of
406 locally emulating the BMC like the above item, instead connect
407 to an external entity that provides the IPMI services.
409 A connection is made to an external BMC simulator. If you do this, it
410 is strongly recommended that you use the "reconnect=" chardev option
411 to reconnect to the simulator if the connection is lost. Note that if
412 this is not used carefully, it can be a security issue, as the
413 interface has the ability to send resets, NMIs, and power off the VM.
414 It's best
if QEMU makes a connection to an external simulator running
415 on a secure port on localhost
, so neither the simulator nor QEMU is
416 exposed to any outside network
.
418 See the
"lanserv/README.vm" file
in the OpenIPMI library
for more
419 details on the external
interface.
421 @item
-device isa
-ipmi
-kcs
,bmc
=@
var{id
}[,ioport
=@
var{val
}][,irq
=@
var{val
}]
423 Add a KCS IPMI interafce on the ISA bus
. This also adds a
424 corresponding ACPI and SMBIOS entries
, if appropriate
.
428 The BMC to connect to
, one of ipmi
-bmc
-sim or ipmi
-bmc
-extern above
.
429 @item ioport
=@
var{val
}
430 Define the I
/O address of the
interface. The
default is
0xca0 for KCS
.
432 Define the interrupt to use
. The
default is
5. To disable interrupts
,
436 @item
-device isa
-ipmi
-bt
,bmc
=@
var{id
}[,ioport
=@
var{val
}][,irq
=@
var{val
}]
438 Like the KCS
interface, but defines a BT
interface. The
default port is
439 0xe4 and the
default interrupt is
5.
443 DEF("name", HAS_ARG
, QEMU_OPTION_name
,
444 "-name string1[,process=string2][,debug-threads=on|off]\n"
445 " set the name of the guest\n"
446 " string1 sets the window title and string2 the process name (on Linux)\n"
447 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
448 " NOTE: The thread names are for debugging and not a stable API.\n",
451 @item
-name @
var{name
}
453 Sets the @
var{name
} of the guest
.
454 This name will be displayed
in the SDL window caption
.
455 The @
var{name
} will also be used
for the VNC server
.
456 Also optionally set the top visible process name
in Linux
.
457 Naming of individual threads can also be enabled on Linux to aid debugging
.
460 DEF("uuid", HAS_ARG
, QEMU_OPTION_uuid
,
461 "-uuid %08x-%04x-%04x-%04x-%012x\n"
462 " specify machine UUID\n", QEMU_ARCH_ALL
)
464 @item
-uuid @
var{uuid
}
474 DEFHEADING(Block device options
:)
479 DEF("fda", HAS_ARG
, QEMU_OPTION_fda
,
480 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL
)
481 DEF("fdb", HAS_ARG
, QEMU_OPTION_fdb
, "", QEMU_ARCH_ALL
)
483 @item
-fda @
var{file
}
484 @itemx
-fdb @
var{file
}
487 Use @
var{file
} as floppy disk
0/1 image (@pxref
{disk_images
}).
490 DEF("hda", HAS_ARG
, QEMU_OPTION_hda
,
491 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL
)
492 DEF("hdb", HAS_ARG
, QEMU_OPTION_hdb
, "", QEMU_ARCH_ALL
)
493 DEF("hdc", HAS_ARG
, QEMU_OPTION_hdc
,
494 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL
)
495 DEF("hdd", HAS_ARG
, QEMU_OPTION_hdd
, "", QEMU_ARCH_ALL
)
497 @item
-hda @
var{file
}
498 @itemx
-hdb @
var{file
}
499 @itemx
-hdc @
var{file
}
500 @itemx
-hdd @
var{file
}
505 Use @
var{file
} as hard disk
0, 1, 2 or
3 image (@pxref
{disk_images
}).
508 DEF("cdrom", HAS_ARG
, QEMU_OPTION_cdrom
,
509 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
512 @item
-cdrom @
var{file
}
514 Use @
var{file
} as CD
-ROM
image (you cannot use @option
{-hdc
} and
515 @option
{-cdrom
} at the same time
). You can use the host CD
-ROM by
516 using @file
{/dev
/cdrom
} as
filename (@pxref
{host_drives
}).
519 DEF("drive", HAS_ARG
, QEMU_OPTION_drive
,
520 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
521 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
522 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
523 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
524 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
525 " [,readonly=on|off][,copy-on-read=on|off]\n"
526 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
527 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
528 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
529 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
530 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
531 " [[,iops_size=is]]\n"
533 " use 'file' as a drive image\n", QEMU_ARCH_ALL
)
535 @item
-drive @
var{option
}[,@
var{option
}[,@
var{option
}[,...]]]
538 Define a
new drive
. Valid options are
:
541 @item file
=@
var{file
}
542 This option defines which disk
image (@pxref
{disk_images
}) to use with
543 this drive
. If the filename contains comma
, you must double it
544 (for instance
, "file=my,,file" to use file
"my,file").
546 Special files such as iSCSI devices can be specified
using protocol
547 specific URLs
. See the section
for "Device URL Syntax" for more information
.
548 @item
if=@
var{interface}
549 This option defines on which type on
interface the drive is connected
.
550 Available types are
: ide
, scsi
, sd
, mtd
, floppy
, pflash
, virtio
.
551 @item bus
=@
var{bus
},unit
=@
var{unit
}
552 These options define where is connected the drive by defining the bus number and
554 @item index
=@
var{index
}
555 This option defines where is connected the drive by
using an index
in the list
556 of available connectors of a given
interface type
.
557 @item media
=@
var{media
}
558 This option defines the type of the media
: disk or cdrom
.
559 @item cyls
=@
var{c
},heads
=@
var{h
},secs
=@
var{s
}[,trans
=@
var{t
}]
560 These options have the same definition as they have
in @option
{-hdachs
}.
561 @item snapshot
=@
var{snapshot
}
562 @
var{snapshot
} is
"on" or
"off" and controls snapshot mode
for the given drive
563 (see @option
{-snapshot
}).
564 @item cache
=@
var{cache
}
565 @
var{cache
} is
"none", "writeback", "unsafe", "directsync" or
"writethrough" and controls how the host cache is used to access block data
.
567 @
var{aio
} is
"threads", or
"native" and selects between pthread based disk I
/O and native Linux AIO
.
568 @item discard
=@
var{discard
}
569 @
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
.
570 @item format
=@
var{format
}
571 Specify which disk @
var{format
} will be used rather than detecting
572 the format
. Can be used to specifiy format
=raw to avoid interpreting
573 an untrusted format header
.
574 @item serial
=@
var{serial
}
575 This option specifies the serial number to assign to the device
.
576 @item addr
=@
var{addr
}
577 Specify the controller
's PCI address (if=virtio only).
578 @item werror=@var{action},rerror=@var{action}
579 Specify which @var{action} to take on write and read errors. Valid actions are:
580 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
581 "report" (report the error to the guest), "enospc" (pause QEMU only if the
582 host disk is full; report the error to the guest otherwise).
583 The default setting is @option{werror=enospc} and @option{rerror=report}.
585 Open drive @option{file} as read-only. Guest write attempts will fail.
586 @item copy-on-read=@var{copy-on-read}
587 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
588 file sectors into the image file.
589 @item detect-zeroes=@var{detect-zeroes}
590 @var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
591 conversion of plain zero writes by the OS to driver specific optimized
592 zero write commands. You may even choose "unmap" if @var{discard} is set
593 to "unmap" to allow a zero write to be converted to an UNMAP operation.
596 By default, the @option{cache=writeback} mode is used. It will report data
597 writes as completed as soon as the data is present in the host page cache.
598 This is safe as long as your guest OS makes sure to correctly flush disk caches
599 where needed. If your guest OS does not handle volatile disk write caches
600 correctly and your host crashes or loses power, then the guest may experience
603 For such guests, you should consider using @option{cache=writethrough}. This
604 means that the host page cache will be used to read and write data, but write
605 notification will be sent to the guest only after QEMU has made sure to flush
606 each write to the disk. Be aware that this has a major impact on performance.
608 The host page cache can be avoided entirely with @option{cache=none}. This will
609 attempt to do disk IO directly to the guest's memory
. QEMU may still perform
610 an internal copy of the data
. Note that
this is considered a writeback mode and
611 the guest OS must handle the disk write cache correctly
in order to avoid data
612 corruption on host crashes
.
614 The host page cache can be avoided
while only sending write notifications to
615 the guest when the data has been flushed to the disk
using
616 @option
{cache
=directsync
}.
618 In
case you don
't care about data integrity over host failures, use
619 @option{cache=unsafe}. This option tells QEMU that it never needs to write any
620 data to the disk but can instead keep things in cache. If anything goes wrong,
621 like your host losing power, the disk storage getting disconnected accidentally,
622 etc. your image will most probably be rendered unusable. When using
623 the @option{-snapshot} option, unsafe caching is always used.
625 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
626 useful when the backing file is over a slow network. By default copy-on-read
629 Instead of @option{-cdrom} you can use:
631 qemu-system-i386 -drive file=file,index=2,media=cdrom
634 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
637 qemu-system-i386 -drive file=file,index=0,media=disk
638 qemu-system-i386 -drive file=file,index=1,media=disk
639 qemu-system-i386 -drive file=file,index=2,media=disk
640 qemu-system-i386 -drive file=file,index=3,media=disk
643 You can open an image using pre-opened file descriptors from an fd set:
646 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
647 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
648 -drive file=/dev/fdset/2,index=0,media=disk
651 You can connect a CDROM to the slave of ide0:
653 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
656 If you don't specify the
"file=" argument
, you define an empty drive
:
658 qemu
-system
-i386
-drive
if=ide
,index
=1,media
=cdrom
661 You can connect a SCSI disk with unit ID
6 on the bus #
0:
663 qemu
-system
-i386
-drive file
=file
,if=scsi
,bus
=0,unit
=6
666 Instead of @option
{-fda
}, @option
{-fdb
}, you can use
:
668 qemu
-system
-i386
-drive file
=file
,index
=0,if=floppy
669 qemu
-system
-i386
-drive file
=file
,index
=1,if=floppy
672 By
default, @
var{interface} is
"ide" and @
var{index
} is automatically
675 qemu
-system
-i386
-drive file
=a
-drive file
=b
"
679 qemu-system-i386 -hda a -hdb b
683 DEF("mtdblock
", HAS_ARG, QEMU_OPTION_mtdblock,
684 "-mtdblock file use
'file' as on
-board Flash memory image
\n",
687 @item -mtdblock @var{file}
689 Use @var{file} as on-board Flash memory image.
692 DEF("sd
", HAS_ARG, QEMU_OPTION_sd,
693 "-sd file use
'file' as SecureDigital card image
\n", QEMU_ARCH_ALL)
697 Use @var{file} as SecureDigital card image.
700 DEF("pflash
", HAS_ARG, QEMU_OPTION_pflash,
701 "-pflash file use
'file' as a parallel flash image
\n", QEMU_ARCH_ALL)
703 @item -pflash @var{file}
705 Use @var{file} as a parallel flash image.
708 DEF("snapshot
", 0, QEMU_OPTION_snapshot,
709 "-snapshot write to temporary files instead of disk image files
\n",
714 Write to temporary files instead of disk image files. In this case,
715 the raw disk image you use is not written back. You can however force
716 the write back by pressing @key{C-a s} (@pxref{disk_images}).
719 DEF("hdachs
", HAS_ARG, QEMU_OPTION_hdachs, \
720 "-hdachs c
,h
,s
[,t
]\n" \
721 " force hard disk
0 physical geometry and the optional BIOS
\n" \
722 " translation (t
=none or lba
) (usually QEMU can guess them
)\n",
725 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
727 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
728 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
729 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
730 all those parameters. This option is useful for old MS-DOS disk
734 DEF("fsdev
", HAS_ARG, QEMU_OPTION_fsdev,
735 "-fsdev fsdriver
,id
=id
[,path
=path
,][security_model
={mapped
-xattr|mapped
-file|passthrough|none
}]\n"
736 " [,writeout
=immediate
][,readonly
][,socket
=socket|sock_fd
=sock_fd
]\n",
741 @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}]
743 Define a new file system device. Valid options are:
746 This option specifies the fs driver backend to use.
747 Currently "local
", "handle
" and "proxy
" file system drivers are supported.
749 Specifies identifier for this device
750 @item path=@var{path}
751 Specifies the export path for the file system device. Files under
752 this path will be available to the 9p client on the guest.
753 @item security_model=@var{security_model}
754 Specifies the security model to be used for this export path.
755 Supported security models are "passthrough
", "mapped
-xattr
", "mapped
-file
" and "none
".
756 In "passthrough
" security model, files are stored using the same
757 credentials as they are created on the guest. This requires QEMU
758 to run as root. In "mapped
-xattr
" security model, some of the file
759 attributes like uid, gid, mode bits and link target are stored as
760 file attributes. For "mapped
-file
" these attributes are stored in the
761 hidden .virtfs_metadata directory. Directories exported by this security model cannot
762 interact with other unix tools. "none
" security model is same as
763 passthrough except the sever won't report failures if it fails to
764 set file attributes like ownership. Security model is mandatory
765 only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
766 security model as a parameter.
767 @item writeout=@var{writeout}
768 This is an optional argument. The only supported value is "immediate
".
769 This means that host page cache will be used to read and write data but
770 write notification will be sent to the guest only when the data has been
771 reported as written by the storage subsystem.
773 Enables exporting 9p share as a readonly mount for guests. By default
774 read-write access is given.
775 @item socket=@var{socket}
776 Enables proxy filesystem driver to use passed socket file for communicating
777 with virtfs-proxy-helper
778 @item sock_fd=@var{sock_fd}
779 Enables proxy filesystem driver to use passed socket descriptor for
780 communicating with virtfs-proxy-helper. Usually a helper like libvirt
781 will create socketpair and pass one of the fds as sock_fd
784 -fsdev option is used along with -device driver "virtio
-9p
-pci
".
785 @item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
786 Options for virtio-9p-pci driver are:
789 Specifies the id value specified along with -fsdev option
790 @item mount_tag=@var{mount_tag}
791 Specifies the tag name to be used by the guest to mount this export point
796 DEF("virtfs
", HAS_ARG, QEMU_OPTION_virtfs,
797 "-virtfs local
,path
=path
,mount_tag
=tag
,security_model
=[mapped
-xattr|mapped
-file|passthrough|none
]\n"
798 " [,writeout
=immediate
][,readonly
][,socket
=socket|sock_fd
=sock_fd
]\n",
803 @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}]
806 The general form of a Virtual File system pass-through options are:
809 This option specifies the fs driver backend to use.
810 Currently "local
", "handle
" and "proxy
" file system drivers are supported.
812 Specifies identifier for this device
813 @item path=@var{path}
814 Specifies the export path for the file system device. Files under
815 this path will be available to the 9p client on the guest.
816 @item security_model=@var{security_model}
817 Specifies the security model to be used for this export path.
818 Supported security models are "passthrough
", "mapped
-xattr
", "mapped
-file
" and "none
".
819 In "passthrough
" security model, files are stored using the same
820 credentials as they are created on the guest. This requires QEMU
821 to run as root. In "mapped
-xattr
" security model, some of the file
822 attributes like uid, gid, mode bits and link target are stored as
823 file attributes. For "mapped
-file
" these attributes are stored in the
824 hidden .virtfs_metadata directory. Directories exported by this security model cannot
825 interact with other unix tools. "none
" security model is same as
826 passthrough except the sever won't report failures if it fails to
827 set file attributes like ownership. Security model is mandatory only
828 for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
829 model as a parameter.
830 @item writeout=@var{writeout}
831 This is an optional argument. The only supported value is "immediate
".
832 This means that host page cache will be used to read and write data but
833 write notification will be sent to the guest only when the data has been
834 reported as written by the storage subsystem.
836 Enables exporting 9p share as a readonly mount for guests. By default
837 read-write access is given.
838 @item socket=@var{socket}
839 Enables proxy filesystem driver to use passed socket file for
840 communicating with virtfs-proxy-helper. Usually a helper like libvirt
841 will create socketpair and pass one of the fds as sock_fd
843 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
844 descriptor for interfacing with virtfs-proxy-helper
848 DEF("virtfs_synth
", 0, QEMU_OPTION_virtfs_synth,
849 "-virtfs_synth Create synthetic file system image
\n",
853 @findex -virtfs_synth
854 Create synthetic file system image
862 DEFHEADING(USB options:)
867 DEF("usb
", 0, QEMU_OPTION_usb,
868 "-usb enable the USB
driver (will be the
default soon
)\n",
873 Enable the USB driver (will be the default soon)
876 DEF("usbdevice
", HAS_ARG, QEMU_OPTION_usbdevice,
877 "-usbdevice name add the host or guest USB device
'name'\n",
881 @item -usbdevice @var{devname}
883 Add the USB device @var{devname}. @xref{usb_devices}.
888 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
891 Pointer device that uses absolute coordinates (like a touchscreen). This
892 means QEMU is able to report the mouse position without having to grab the
893 mouse. Also overrides the PS/2 mouse emulation when activated.
895 @item disk:[format=@var{format}]:@var{file}
896 Mass storage device based on file. The optional @var{format} argument
897 will be used rather than detecting the format. Can be used to specifiy
898 @code{format=raw} to avoid interpreting an untrusted format header.
900 @item host:@var{bus}.@var{addr}
901 Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
903 @item host:@var{vendor_id}:@var{product_id}
904 Pass through the host device identified by @var{vendor_id}:@var{product_id}
907 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
908 Serial converter to host character device @var{dev}, see @code{-serial} for the
912 Braille device. This will use BrlAPI to display the braille output on a real
915 @item net:@var{options}
916 Network adapter that supports CDC ethernet and RNDIS protocols.
926 DEFHEADING(Display options:)
931 DEF("display
", HAS_ARG, QEMU_OPTION_display,
932 "-display sdl
[,frame
=on|off
][,alt_grab
=on|off
][,ctrl_grab
=on|off
]\n"
933 " [,window_close
=on|off
]|curses|none|
\n"
934 " gtk
[,grab_on_hover
=on|off
]|
\n"
935 " vnc
=<display
>[,<optargs
>]\n"
936 " select display type
\n", QEMU_ARCH_ALL)
938 @item -display @var{type}
940 Select type of display to use. This option is a replacement for the
941 old style -sdl/-curses/... options. Valid values for @var{type} are
944 Display video output via SDL (usually in a separate graphics
945 window; see the SDL documentation for other possibilities).
947 Display video output via curses. For graphics device models which
948 support a text mode, QEMU can display this output using a
949 curses/ncurses interface. Nothing is displayed when the graphics
950 device is in graphical mode or if the graphics device does not support
951 a text mode. Generally only the VGA device models support text mode.
953 Do not display video output. The guest will still see an emulated
954 graphics card, but its output will not be displayed to the QEMU
955 user. This option differs from the -nographic option in that it
956 only affects what is done with video output; -nographic also changes
957 the destination of the serial and parallel port data.
959 Display video output in a GTK window. This interface provides drop-down
960 menus and other UI elements to configure and control the VM during
963 Start a VNC server on display <arg>
967 DEF("nographic
", 0, QEMU_OPTION_nographic,
968 "-nographic disable graphical output and redirect serial I
/Os to console
\n",
973 Normally, QEMU uses SDL to display the VGA output. With this option,
974 you can totally disable graphical output so that QEMU is a simple
975 command line application. The emulated serial port is redirected on
976 the console and muxed with the monitor (unless redirected elsewhere
977 explicitly). Therefore, you can still use QEMU to debug a Linux kernel
978 with a serial console. Use @key{C-a h} for help on switching between
979 the console and monitor.
982 DEF("curses
", 0, QEMU_OPTION_curses,
983 "-curses use a curses
/ncurses
interface instead of SDL
\n",
988 Normally, QEMU uses SDL to display the VGA output. With this option,
989 QEMU can display the VGA output when in text mode using a
990 curses/ncurses interface. Nothing is displayed in graphical mode.
993 DEF("no
-frame
", 0, QEMU_OPTION_no_frame,
994 "-no
-frame open SDL window without a frame and window decorations
\n",
999 Do not use decorations for SDL windows and start them using the whole
1000 available screen space. This makes the using QEMU in a dedicated desktop
1001 workspace more convenient.
1004 DEF("alt
-grab
", 0, QEMU_OPTION_alt_grab,
1005 "-alt
-grab use Ctrl
-Alt
-Shift to grab
mouse (instead of Ctrl
-Alt
)\n",
1010 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1011 affects the special keys (for fullscreen, monitor-mode switching, etc).
1014 DEF("ctrl
-grab
", 0, QEMU_OPTION_ctrl_grab,
1015 "-ctrl
-grab use Right
-Ctrl to grab
mouse (instead of Ctrl
-Alt
)\n",
1020 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1021 affects the special keys (for fullscreen, monitor-mode switching, etc).
1024 DEF("no
-quit
", 0, QEMU_OPTION_no_quit,
1025 "-no
-quit disable SDL window close capability
\n", QEMU_ARCH_ALL)
1029 Disable SDL window close capability.
1032 DEF("sdl
", 0, QEMU_OPTION_sdl,
1033 "-sdl enable SDL
\n", QEMU_ARCH_ALL)
1040 DEF("spice
", HAS_ARG, QEMU_OPTION_spice,
1041 "-spice
[port
=port
][,tls
-port
=secured
-port
][,x509
-dir
=<dir
>]\n"
1042 " [,x509
-key
-file
=<file
>][,x509
-key
-password
=<file
>]\n"
1043 " [,x509
-cert
-file
=<file
>][,x509
-cacert
-file
=<file
>]\n"
1044 " [,x509
-dh
-key
-file
=<file
>][,addr
=addr
][,ipv4|ipv6|unix
]\n"
1045 " [,tls
-ciphers
=<list
>]\n"
1046 " [,tls
-channel
=[main|display|cursor|inputs|record|playback
]]\n"
1047 " [,plaintext
-channel
=[main|display|cursor|inputs|record|playback
]]\n"
1048 " [,sasl
][,password
=<secret
>][,disable
-ticketing
]\n"
1049 " [,image
-compression
=[auto_glz|auto_lz|quic|glz|lz|off
]]\n"
1050 " [,jpeg
-wan
-compression
=[auto|
never|always
]]\n"
1051 " [,zlib
-glz
-wan
-compression
=[auto|
never|always
]]\n"
1052 " [,streaming
-video
=[off|all|filter
]][,disable
-copy
-paste
]\n"
1053 " [,disable
-agent
-file
-xfer
][,agent
-mouse
=[on|off
]]\n"
1054 " [,playback
-compression
=[on|off
]][,seamless
-migration
=[on|off
]]\n"
1057 " at least one of
{port
, tls
-port
} is mandatory
\n",
1060 @item -spice @var{option}[,@var{option}[,...]]
1062 Enable the spice remote desktop protocol. Valid options are
1067 Set the TCP port spice is listening on for plaintext channels.
1070 Set the IP address spice is listening on. Default is any address.
1075 Force using the specified IP version.
1077 @item password=<secret>
1078 Set the password you need to authenticate.
1081 Require that the client use SASL to authenticate with the spice.
1082 The exact choice of authentication method used is controlled from the
1083 system / user's SASL configuration file for the 'qemu' service. This
1084 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1085 unprivileged user, an environment variable SASL_CONF_PATH can be used
1086 to make it search alternate locations for the service config.
1087 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1088 it is recommended that SASL always be combined with the 'tls' and
1089 'x509' settings to enable use of SSL and server certificates. This
1090 ensures a data encryption preventing compromise of authentication
1093 @item disable-ticketing
1094 Allow client connects without authentication.
1096 @item disable-copy-paste
1097 Disable copy paste between the client and the guest.
1099 @item disable-agent-file-xfer
1100 Disable spice-vdagent based file-xfer between the client and the guest.
1103 Set the TCP port spice is listening on for encrypted channels.
1105 @item x509-dir=<dir>
1106 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1108 @item x509-key-file=<file>
1109 @itemx x509-key-password=<file>
1110 @itemx x509-cert-file=<file>
1111 @itemx x509-cacert-file=<file>
1112 @itemx x509-dh-key-file=<file>
1113 The x509 file names can also be configured individually.
1115 @item tls-ciphers=<list>
1116 Specify which ciphers to use.
1118 @item tls-channel=[main|display|cursor|inputs|record|playback]
1119 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
1120 Force specific channel to be used with or without TLS encryption. The
1121 options can be specified multiple times to configure multiple
1122 channels. The special name "default" can be used to set the default
1123 mode. For channels which are not explicitly forced into one mode the
1124 spice client is allowed to pick tls/plaintext as he pleases.
1126 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1127 Configure image compression (lossless).
1128 Default is auto_glz.
1130 @item jpeg-wan-compression=[auto|never|always]
1131 @itemx zlib-glz-wan-compression=[auto|never|always]
1132 Configure wan image compression (lossy for slow links).
1135 @item streaming-video=[off|all|filter]
1136 Configure video stream detection. Default is filter.
1138 @item agent-mouse=[on|off]
1139 Enable/disable passing mouse events via vdagent. Default is on.
1141 @item playback-compression=[on|off]
1142 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1144 @item seamless-migration=[on|off]
1145 Enable/disable spice seamless migration. Default is off.
1148 Enable/disable OpenGL context. Default is off.
1153 DEF("portrait
", 0, QEMU_OPTION_portrait,
1154 "-portrait rotate graphical output
90 deg
left (only PXA LCD
)\n",
1159 Rotate graphical output 90 deg left (only PXA LCD).
1162 DEF("rotate
", HAS_ARG, QEMU_OPTION_rotate,
1163 "-rotate
<deg
> rotate graphical output some deg
left (only PXA LCD
)\n",
1166 @item -rotate @var{deg}
1168 Rotate graphical output some deg left (only PXA LCD).
1171 DEF("vga
", HAS_ARG, QEMU_OPTION_vga,
1172 "-vga
[std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none
]\n"
1173 " select video card type
\n", QEMU_ARCH_ALL)
1175 @item -vga @var{type}
1177 Select type of VGA card to emulate. Valid values for @var{type} are
1180 Cirrus Logic GD5446 Video card. All Windows versions starting from
1181 Windows 95 should recognize and use this graphic card. For optimal
1182 performances, use 16 bit color depth in the guest and the host OS.
1183 (This one is the default)
1185 Standard VGA card with Bochs VBE extensions. If your guest OS
1186 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1187 to use high resolution modes (>= 1280x1024x16) then you should use
1190 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1191 recent XFree86/XOrg server or Windows guest with a driver for this
1194 QXL paravirtual graphic card. It is VGA compatible (including VESA
1195 2.0 VBE support). Works best with qxl guest drivers installed though.
1196 Recommended choice when using the spice protocol.
1198 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1199 sun4m machines and offers both 8-bit and 24-bit colour depths at a
1200 fixed resolution of 1024x768.
1202 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1203 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1204 resolutions aimed at people wishing to run older Solaris versions.
1212 DEF("full
-screen
", 0, QEMU_OPTION_full_screen,
1213 "-full
-screen start
in full screen
\n", QEMU_ARCH_ALL)
1216 @findex -full-screen
1217 Start in full screen.
1220 DEF("g
", 1, QEMU_OPTION_g ,
1221 "-g WxH
[xDEPTH
] Set the initial graphical resolution and depth
\n",
1222 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
1224 @item -g @var{width}x@var{height}[x@var{depth}]
1226 Set the initial graphical resolution and depth (PPC, SPARC only).
1229 DEF("vnc
", HAS_ARG, QEMU_OPTION_vnc ,
1230 "-vnc display start a VNC server on display
\n", QEMU_ARCH_ALL)
1232 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1234 Normally, QEMU uses SDL to display the VGA output. With this option,
1235 you can have QEMU listen on VNC display @var{display} and redirect the VGA
1236 display over the VNC session. It is very useful to enable the usb
1237 tablet device when using this option (option @option{-usbdevice
1238 tablet}). When using the VNC display, you must use the @option{-k}
1239 parameter to set the keyboard layout if you are not using en-us. Valid
1240 syntax for the @var{display} is
1244 @item @var{host}:@var{d}
1246 TCP connections will only be allowed from @var{host} on display @var{d}.
1247 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1248 be omitted in which case the server will accept connections from any host.
1250 @item unix:@var{path}
1252 Connections will be allowed over UNIX domain sockets where @var{path} is the
1253 location of a unix socket to listen for connections on.
1257 VNC is initialized but not started. The monitor @code{change} command
1258 can be used to later start the VNC server.
1262 Following the @var{display} value there may be one or more @var{option} flags
1263 separated by commas. Valid options are
1269 Connect to a listening VNC client via a ``reverse'' connection. The
1270 client is specified by the @var{display}. For reverse network
1271 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1272 is a TCP port number, not a display number.
1276 Opens an additional TCP listening port dedicated to VNC Websocket connections.
1277 By definition the Websocket port is 5700+@var{display}. If @var{host} is
1278 specified connections will only be allowed from this host.
1279 As an alternative the Websocket port could be specified by using
1280 @code{websocket}=@var{port}.
1281 If no TLS credentials are provided, the websocket connection runs in
1282 unencrypted mode. If TLS credentials are provided, the websocket connection
1283 requires encrypted client connections.
1287 Require that password based authentication is used for client connections.
1289 The password must be set separately using the @code{set_password} command in
1290 the @ref{pcsys_monitor}. The syntax to change your password is:
1291 @code{set_password <protocol> <password>} where <protocol> could be either
1294 If you would like to change <protocol> password expiration, you should use
1295 @code{expire_password <protocol> <expiration-time>} where expiration time could
1296 be one of the following options: now, never, +seconds or UNIX time of
1297 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1298 to make password expire on "Mon Apr
23 12:00:00 EDT
2012" (UNIX time for this
1301 You can also use keywords "now
" or "never" for the expiration time to
1302 allow <protocol> password to expire immediately or never expire.
1304 @item tls-creds=@var{ID}
1306 Provides the ID of a set of TLS credentials to use to secure the
1307 VNC server. They will apply to both the normal VNC server socket
1308 and the websocket socket (if enabled). Setting TLS credentials
1309 will cause the VNC server socket to enable the VeNCrypt auth
1310 mechanism. The credentials should have been previously created
1311 using the @option{-object tls-creds} argument.
1313 The @option{tls-creds} parameter obsoletes the @option{tls},
1314 @option{x509}, and @option{x509verify} options, and as such
1315 it is not permitted to set both new and old type options at
1320 Require that client use TLS when communicating with the VNC server. This
1321 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1322 attack. It is recommended that this option be combined with either the
1323 @option{x509} or @option{x509verify} options.
1325 This option is now deprecated in favor of using the @option{tls-creds}
1328 @item x509=@var{/path/to/certificate/dir}
1330 Valid if @option{tls} is specified. Require that x509 credentials are used
1331 for negotiating the TLS session. The server will send its x509 certificate
1332 to the client. It is recommended that a password be set on the VNC server
1333 to provide authentication of the client when this is used. The path following
1334 this option specifies where the x509 certificates are to be loaded from.
1335 See the @ref{vnc_security} section for details on generating certificates.
1337 This option is now deprecated in favour of using the @option{tls-creds}
1340 @item x509verify=@var{/path/to/certificate/dir}
1342 Valid if @option{tls} is specified. Require that x509 credentials are used
1343 for negotiating the TLS session. The server will send its x509 certificate
1344 to the client, and request that the client send its own x509 certificate.
1345 The server will validate the client's certificate against the CA certificate,
1346 and reject clients when validation fails. If the certificate authority is
1347 trusted, this is a sufficient authentication mechanism. You may still wish
1348 to set a password on the VNC server as a second authentication layer. The
1349 path following this option specifies where the x509 certificates are to
1350 be loaded from. See the @ref{vnc_security} section for details on generating
1353 This option is now deprecated in favour of using the @option{tls-creds}
1358 Require that the client use SASL to authenticate with the VNC server.
1359 The exact choice of authentication method used is controlled from the
1360 system / user's SASL configuration file for the 'qemu' service. This
1361 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1362 unprivileged user, an environment variable SASL_CONF_PATH can be used
1363 to make it search alternate locations for the service config.
1364 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1365 it is recommended that SASL always be combined with the 'tls' and
1366 'x509' settings to enable use of SSL and server certificates. This
1367 ensures a data encryption preventing compromise of authentication
1368 credentials. See the @ref{vnc_security} section for details on using
1369 SASL authentication.
1373 Turn on access control lists for checking of the x509 client certificate
1374 and SASL party. For x509 certs, the ACL check is made against the
1375 certificate's distinguished name. This is something that looks like
1376 @code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1377 made against the username, which depending on the SASL plugin, may
1378 include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1379 When the @option{acl} flag is set, the initial access list will be
1380 empty, with a @code{deny} policy. Thus no one will be allowed to
1381 use the VNC server until the ACLs have been loaded. This can be
1382 achieved using the @code{acl} monitor command.
1386 Enable lossy compression methods (gradient, JPEG, ...). If this
1387 option is set, VNC client may receive lossy framebuffer updates
1388 depending on its encoding settings. Enabling this option can save
1389 a lot of bandwidth at the expense of quality.
1393 Disable adaptive encodings. Adaptive encodings are enabled by default.
1394 An adaptive encoding will try to detect frequently updated screen regions,
1395 and send updates in these regions using a lossy encoding (like JPEG).
1396 This can be really helpful to save bandwidth when playing videos. Disabling
1397 adaptive encodings restores the original static behavior of encodings
1400 @item share=[allow-exclusive|force-shared|ignore]
1402 Set display sharing policy. 'allow-exclusive' allows clients to ask
1403 for exclusive access. As suggested by the rfb spec this is
1404 implemented by dropping other connections. Connecting multiple
1405 clients in parallel requires all clients asking for a shared session
1406 (vncviewer: -shared switch). This is the default. 'force-shared'
1407 disables exclusive client access. Useful for shared desktop sessions,
1408 where you don't want someone forgetting specify -shared disconnect
1409 everybody else. 'ignore' completely ignores the shared flag and
1410 allows everybody connect unconditionally. Doesn't conform to the rfb
1411 spec but is traditional QEMU behavior.
1419 ARCHHEADING(, QEMU_ARCH_I386)
1421 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1426 DEF("win2k
-hack
", 0, QEMU_OPTION_win2k_hack,
1427 "-win2k
-hack use it when installing Windows
2000 to avoid a disk full bug
\n",
1432 Use it when installing Windows 2000 to avoid a disk full bug. After
1433 Windows 2000 is installed, you no longer need this option (this option
1434 slows down the IDE transfers).
1437 HXCOMM Deprecated by -rtc
1438 DEF("rtc
-td
-hack
", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1440 DEF("no
-fd
-bootchk
", 0, QEMU_OPTION_no_fd_bootchk,
1441 "-no
-fd
-bootchk disable boot signature checking
for floppy disks
\n",
1444 @item -no-fd-bootchk
1445 @findex -no-fd-bootchk
1446 Disable boot signature checking for floppy disks in BIOS. May
1447 be needed to boot from old floppy disks.
1450 DEF("no
-acpi
", 0, QEMU_OPTION_no_acpi,
1451 "-no
-acpi disable ACPI
\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1455 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1456 it if your guest OS complains about ACPI problems (PC target machine
1460 DEF("no
-hpet
", 0, QEMU_OPTION_no_hpet,
1461 "-no
-hpet disable HPET
\n", QEMU_ARCH_I386)
1465 Disable HPET support.
1468 DEF("acpitable
", HAS_ARG, QEMU_OPTION_acpitable,
1469 "-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"
1470 " ACPI table description
\n", QEMU_ARCH_I386)
1472 @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}]...]
1474 Add ACPI table with specified header fields and context from specified files.
1475 For file=, take whole ACPI table from the specified files, including all
1476 ACPI headers (possible overridden by other options).
1477 For data=, only data
1478 portion of the table is used, all header information is specified in the
1480 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1481 fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
1482 to ensure the field matches required by the Microsoft SLIC spec and the ACPI
1486 DEF("smbios
", HAS_ARG, QEMU_OPTION_smbios,
1487 "-smbios file
=binary
\n"
1488 " load SMBIOS entry from binary file
\n"
1489 "-smbios type
=0[,vendor
=str
][,version
=str
][,date
=str
][,release
=%d
.%d
]\n"
1491 " specify SMBIOS type
0 fields
\n"
1492 "-smbios type
=1[,manufacturer
=str
][,product
=str
][,version
=str
][,serial
=str
]\n"
1493 " [,uuid
=uuid
][,sku
=str
][,family
=str
]\n"
1494 " specify SMBIOS type
1 fields
\n"
1495 "-smbios type
=2[,manufacturer
=str
][,product
=str
][,version
=str
][,serial
=str
]\n"
1496 " [,asset
=str
][,location
=str
]\n"
1497 " specify SMBIOS type
2 fields
\n"
1498 "-smbios type
=3[,manufacturer
=str
][,version
=str
][,serial
=str
][,asset
=str
]\n"
1500 " specify SMBIOS type
3 fields
\n"
1501 "-smbios type
=4[,sock_pfx
=str
][,manufacturer
=str
][,version
=str
][,serial
=str
]\n"
1502 " [,asset
=str
][,part
=str
]\n"
1503 " specify SMBIOS type
4 fields
\n"
1504 "-smbios type
=17[,loc_pfx
=str
][,bank
=str
][,manufacturer
=str
][,serial
=str
]\n"
1505 " [,asset
=str
][,part
=str
][,speed
=%d
]\n"
1506 " specify SMBIOS type
17 fields
\n",
1507 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
1509 @item -smbios file=@var{binary}
1511 Load SMBIOS entry from binary file.
1513 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
1514 Specify SMBIOS type 0 fields
1516 @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}]
1517 Specify SMBIOS type 1 fields
1519 @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}]
1520 Specify SMBIOS type 2 fields
1522 @item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
1523 Specify SMBIOS type 3 fields
1525 @item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
1526 Specify SMBIOS type 4 fields
1528 @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}]
1529 Specify SMBIOS type 17 fields
1537 DEFHEADING(Network options:)
1542 HXCOMM Legacy slirp options (now moved to -net user):
1544 DEF("tftp
", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1545 DEF("bootp
", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1546 DEF("redir
", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1548 DEF("smb
", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1552 DEF("netdev
", HAS_ARG, QEMU_OPTION_netdev,
1554 "-netdev user
,id
=str
[,net
=addr
[/mask
]][,host
=addr
][,restrict
=on|off
]\n"
1555 " [,hostname
=host
][,dhcpstart
=addr
][,dns
=addr
][,dnssearch
=domain
][,tftp
=dir
]\n"
1556 " [,bootfile
=f
][,hostfwd
=rule
][,guestfwd
=rule
]"
1558 "[,smb
=dir
[,smbserver
=addr
]]\n"
1560 " configure a user mode network backend with ID
'str',\n"
1561 " its DHCP server and optional services
\n"
1564 "-netdev tap
,id
=str
,ifname
=name
\n"
1565 " configure a host TAP network backend with ID
'str'\n"
1567 "-netdev tap
,id
=str
[,fd
=h
][,fds
=x
:y
:...:z
][,ifname
=name
][,script
=file
][,downscript
=dfile
]\n"
1568 " [,helper
=helper
][,sndbuf
=nbytes
][,vnet_hdr
=on|off
][,vhost
=on|off
]\n"
1569 " [,vhostfd
=h
][,vhostfds
=x
:y
:...:z
][,vhostforce
=on|off
][,queues
=n
]\n"
1570 " configure a host TAP network backend with ID
'str'\n"
1571 " use network scripts
'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1572 " to configure it and
'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1573 " to deconfigure it
\n"
1574 " use
'[down]script=no' to disable script execution
\n"
1575 " use network helper
'helper' (default=" DEFAULT_BRIDGE_HELPER ") to
\n"
1577 " use
'fd=h' to connect to an already opened TAP
interface\n"
1578 " use
'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces
\n"
1579 " use
'sndbuf=nbytes' to limit the size of the send
buffer (the
\n"
1580 " default is disabled
'sndbuf=0' to enable flow control set
'sndbuf=1048576')\n"
1581 " use vnet_hdr
=off to avoid enabling the IFF_VNET_HDR tap flag
\n"
1582 " use vnet_hdr
=on to make the lack of IFF_VNET_HDR support an error condition
\n"
1583 " use vhost
=on to enable experimental
in kernel accelerator
\n"
1584 " (only has effect
for virtio guests which use MSIX
)\n"
1585 " use vhostforce
=on to force vhost on
for non
-MSIX virtio guests
\n"
1586 " use
'vhostfd=h' to connect to an already opened vhost net device
\n"
1587 " use
'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
1588 " use 'queues
=n
' to specify the number of queues to be created for multiqueue TAP\n"
1589 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
1590 " configure a host TAP network backend with ID 'str
' that is\n"
1591 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
1592 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
1595 "-netdev l2tpv3
,id
=str
,src
=srcaddr
,dst
=dstaddr
[,srcport
=srcport
][,dstport
=dstport
]\n"
1596 " [,rxsession
=rxsession
],txsession
=txsession
[,ipv6
=on
/off
][,udp
=on
/off
]\n"
1597 " [,cookie64
=on
/off
][,counter
][,pincounter
][,txcookie
=txcookie
]\n"
1598 " [,rxcookie
=rxcookie
][,offset
=offset
]\n"
1599 " configure a network backend with ID
'str' connected to
\n"
1600 " an Ethernet over L2TPv3 pseudowire
.\n"
1601 " Linux kernel
3.3+ as well as most routers can talk
\n"
1602 " L2TPv3
. This transport allows connecting a VM to a VM
,\n"
1603 " VM to a router and even VM to Host
. It is a nearly
-universal
\n"
1604 " standard (RFC3391
). Note
- this implementation uses
static\n"
1605 " pre
-configured
tunnels (same as the Linux kernel
).\n"
1606 " use
'src=' to specify source address
\n"
1607 " use
'dst=' to specify destination address
\n"
1608 " use
'udp=on' to specify udp encapsulation
\n"
1609 " use
'srcport=' to specify source udp port
\n"
1610 " use
'dstport=' to specify destination udp port
\n"
1611 " use
'ipv6=on' to force v6
\n"
1612 " L2TPv3 uses cookies to prevent misconfiguration as
\n"
1613 " well as a weak security measure
\n"
1614 " use
'rxcookie=0x012345678' to specify a rxcookie
\n"
1615 " use
'txcookie=0x012345678' to specify a txcookie
\n"
1616 " use
'cookie64=on' to set cookie size to
64 bit
, otherwise
32\n"
1617 " use
'counter=off' to force a
'cut-down' L2TPv3 with no counter
\n"
1618 " use
'pincounter=on' to work around broken counter handling
in peer
\n"
1619 " use
'offset=X' to add an extra offset between header and data
\n"
1621 "-netdev socket
,id
=str
[,fd
=h
][,listen
=[host
]:port
][,connect
=host
:port
]\n"
1622 " configure a network backend to connect to another network
\n"
1623 " using a socket connection
\n"
1624 "-netdev socket
,id
=str
[,fd
=h
][,mcast
=maddr
:port
[,localaddr
=addr
]]\n"
1625 " configure a network backend to connect to a multicast maddr and port
\n"
1626 " use
'localaddr=addr' to specify the host address to send packets from
\n"
1627 "-netdev socket
,id
=str
[,fd
=h
][,udp
=host
:port
][,localaddr
=host
:port
]\n"
1628 " configure a network backend to connect to another network
\n"
1629 " using an UDP tunnel
\n"
1631 "-netdev vde
,id
=str
[,sock
=socketpath
][,port
=n
][,group
=groupname
][,mode
=octalmode
]\n"
1632 " configure a network backend to connect to port
'n' of a vde
switch\n"
1633 " running on host and listening
for incoming connections on
'socketpath'.\n"
1634 " Use group
'groupname' and mode
'octalmode' to change
default\n"
1635 " ownership and permissions
for communication port
.\n"
1637 #ifdef CONFIG_NETMAP
1638 "-netdev netmap
,id
=str
,ifname
=name
[,devname
=nmname
]\n"
1639 " attach to the existing netmap
-enabled network
interface 'name', or to a
\n"
1640 " VALE
port (created on the fly
) called
'name' ('nmname' is name of the
\n"
1641 " netmap device
, defaults to
'/dev/netmap')\n"
1643 "-netdev vhost
-user
,id
=str
,chardev
=dev
[,vhostforce
=on|off
]\n"
1644 " configure a vhost
-user network
, backed by a chardev
'dev'\n"
1645 "-netdev hubport
,id
=str
,hubid
=n
\n"
1646 " configure a hub port on QEMU VLAN
'n'\n", QEMU_ARCH_ALL)
1647 DEF("net
", HAS_ARG, QEMU_OPTION_net,
1648 "-net nic
[,vlan
=n
][,macaddr
=mac
][,model
=type
][,name
=str
][,addr
=str
][,vectors
=v
]\n"
1649 " old way to create a
new NIC and connect it to VLAN
'n'\n"
1650 " (use the
'-device devtype,netdev=str' option
if possible instead
)\n"
1651 "-net dump
[,vlan
=n
][,file
=f
][,len
=n
]\n"
1652 " dump traffic on vlan
'n' to file
'f' (max n bytes per packet
)\n"
1653 "-net none use it alone to have zero network devices
. If no
-net option
\n"
1654 " is provided
, the
default is
'-net nic -net user'\n"
1664 #ifdef CONFIG_NETMAP
1667 "socket
][,vlan
=n
][,option
][,option
][,...]\n"
1668 " old way to initialize a host network
interface\n"
1669 " (use the
-netdev option
if possible instead
)\n", QEMU_ARCH_ALL)
1671 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1673 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1674 = 0 is the default). The NIC is an e1000 by default on the PC
1675 target. Optionally, the MAC address can be changed to @var{mac}, the
1676 device address set to @var{addr} (PCI cards only),
1677 and a @var{name} can be assigned for use in monitor commands.
1678 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1679 that the card should have; this option currently only affects virtio cards; set
1680 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1681 NIC is created. QEMU can emulate several different models of network card.
1682 Valid values for @var{type} are
1683 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1684 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1685 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1686 Not all devices are supported on all targets. Use @code{-net nic,model=help}
1687 for a list of available devices for your target.
1689 @item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
1691 @item -net user[,@var{option}][,@var{option}][,...]
1692 Use the user mode network stack which requires no administrator
1693 privilege to run. Valid options are:
1697 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1700 @itemx name=@var{name}
1701 Assign symbolic name for use in monitor commands.
1703 @item net=@var{addr}[/@var{mask}]
1704 Set IP network address the guest will see. Optionally specify the netmask,
1705 either in the form a.b.c.d or as number of valid top-most bits. Default is
1708 @item host=@var{addr}
1709 Specify the guest-visible address of the host. Default is the 2nd IP in the
1710 guest network, i.e. x.x.x.2.
1712 @item restrict=on|off
1713 If this option is enabled, the guest will be isolated, i.e. it will not be
1714 able to contact the host and no guest IP packets will be routed over the host
1715 to the outside. This option does not affect any explicitly set forwarding rules.
1717 @item hostname=@var{name}
1718 Specifies the client hostname reported by the built-in DHCP server.
1720 @item dhcpstart=@var{addr}
1721 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1722 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1724 @item dns=@var{addr}
1725 Specify the guest-visible address of the virtual nameserver. The address must
1726 be different from the host address. Default is the 3rd IP in the guest network,
1729 @item dnssearch=@var{domain}
1730 Provides an entry for the domain-search list sent by the built-in
1731 DHCP server. More than one domain suffix can be transmitted by specifying
1732 this option multiple times. If supported, this will cause the guest to
1733 automatically try to append the given domain suffix(es) in case a domain name
1734 can not be resolved.
1738 qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...]
1741 @item tftp=@var{dir}
1742 When using the user mode network stack, activate a built-in TFTP
1743 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1744 The TFTP client on the guest must be configured in binary mode (use the command
1745 @code{bin} of the Unix TFTP client).
1747 @item bootfile=@var{file}
1748 When using the user mode network stack, broadcast @var{file} as the BOOTP
1749 filename. In conjunction with @option{tftp}, this can be used to network boot
1750 a guest from a local directory.
1752 Example (using pxelinux):
1754 qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1757 @item smb=@var{dir}[,smbserver=@var{addr}]
1758 When using the user mode network stack, activate a built-in SMB
1759 server so that Windows OSes can access to the host files in @file{@var{dir}}
1760 transparently. The IP address of the SMB server can be set to @var{addr}. By
1761 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1763 In the guest Windows OS, the line:
1767 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1768 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1770 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1772 Note that a SAMBA server must be installed on the host OS.
1773 QEMU was tested successfully with smbd versions from Red Hat 9,
1774 Fedora Core 3 and OpenSUSE 11.x.
1776 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1777 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1778 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1779 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1780 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1781 be bound to a specific host interface. If no connection type is set, TCP is
1782 used. This option can be given multiple times.
1784 For example, to redirect host X11 connection from screen 1 to guest
1785 screen 0, use the following:
1789 qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1790 # this host xterm should open in the guest X11 server
1794 To redirect telnet connections from host port 5555 to telnet port on
1795 the guest, use the following:
1799 qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...]
1800 telnet localhost 5555
1803 Then when you use on the host @code{telnet localhost 5555}, you
1804 connect to the guest telnet server.
1806 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1807 @itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
1808 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1809 to the character device @var{dev} or to a program executed by @var{cmd:command}
1810 which gets spawned for each connection. This option can be given multiple times.
1812 You can either use a chardev directly and have that one used throughout QEMU's
1813 lifetime, like in the following example:
1816 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1817 # the guest accesses it
1818 qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...]
1821 Or you can execute a command on every TCP connection established by the guest,
1822 so that QEMU behaves similar to an inetd process for that virtual server:
1825 # call "netcat
10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1826 # and connect the TCP stream to its stdin/stdout
1827 qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1832 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1833 processed and applied to -net user. Mixing them with the new configuration
1834 syntax gives undefined results. Their use for new applications is discouraged
1835 as they will be removed from future versions.
1837 @item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1838 @itemx -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1839 Connect the host TAP network interface @var{name} to VLAN @var{n}.
1841 Use the network script @var{file} to configure it and the network script
1842 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1843 automatically provides one. The default network configure script is
1844 @file{/etc/qemu-ifup} and the default network deconfigure script is
1845 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1846 to disable script execution.
1848 If running QEMU as an unprivileged user, use the network helper
1849 @var{helper} to configure the TAP interface. The default network
1850 helper executable is @file{/path/to/qemu-bridge-helper}.
1852 @option{fd}=@var{h} can be used to specify the handle of an already
1853 opened host TAP interface.
1858 #launch a QEMU instance with the default network script
1859 qemu-system-i386 linux.img -net nic -net tap
1863 #launch a QEMU instance with two NICs, each one connected
1865 qemu-system-i386 linux.img \
1866 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1867 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1871 #launch a QEMU instance with the default network helper to
1872 #connect a TAP device to bridge br0
1873 qemu-system-i386 linux.img \
1874 -net nic -net tap,"helper
=/path
/to
/qemu
-bridge
-helper
"
1877 @item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
1878 @itemx -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1879 Connect a host TAP network interface to a host bridge device.
1881 Use the network helper @var{helper} to configure the TAP interface and
1882 attach it to the bridge. The default network helper executable is
1883 @file{/path/to/qemu-bridge-helper} and the default bridge
1884 device is @file{br0}.
1889 #launch a QEMU instance with the default network helper to
1890 #connect a TAP device to bridge br0
1891 qemu-system-i386 linux.img -net bridge -net nic,model=virtio
1895 #launch a QEMU instance with the default network helper to
1896 #connect a TAP device to bridge qemubr0
1897 qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio
1900 @item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1901 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1903 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1904 machine using a TCP socket connection. If @option{listen} is
1905 specified, QEMU waits for incoming connections on @var{port}
1906 (@var{host} is optional). @option{connect} is used to connect to
1907 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1908 specifies an already opened TCP socket.
1912 # launch a first QEMU instance
1913 qemu-system-i386 linux.img \
1914 -net nic,macaddr=52:54:00:12:34:56 \
1915 -net socket,listen=:1234
1916 # connect the VLAN 0 of this instance to the VLAN 0
1917 # of the first instance
1918 qemu-system-i386 linux.img \
1919 -net nic,macaddr=52:54:00:12:34:57 \
1920 -net socket,connect=127.0.0.1:1234
1923 @item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1924 @itemx -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1926 Create a VLAN @var{n} shared with another QEMU virtual
1927 machines using a UDP multicast socket, effectively making a bus for
1928 every QEMU with same multicast address @var{maddr} and @var{port}.
1932 Several QEMU can be running on different hosts and share same bus (assuming
1933 correct multicast setup for these hosts).
1935 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1936 @url{http://user-mode-linux.sf.net}.
1938 Use @option{fd=h} to specify an already opened UDP multicast socket.
1943 # launch one QEMU instance
1944 qemu-system-i386 linux.img \
1945 -net nic,macaddr=52:54:00:12:34:56 \
1946 -net socket,mcast=230.0.0.1:1234
1947 # launch another QEMU instance on same "bus
"
1948 qemu-system-i386 linux.img \
1949 -net nic,macaddr=52:54:00:12:34:57 \
1950 -net socket,mcast=230.0.0.1:1234
1951 # launch yet another QEMU instance on same "bus
"
1952 qemu-system-i386 linux.img \
1953 -net nic,macaddr=52:54:00:12:34:58 \
1954 -net socket,mcast=230.0.0.1:1234
1957 Example (User Mode Linux compat.):
1959 # launch QEMU instance (note mcast address selected
1961 qemu-system-i386 linux.img \
1962 -net nic,macaddr=52:54:00:12:34:56 \
1963 -net socket,mcast=239.192.168.1:1102
1965 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1968 Example (send packets from host's 1.2.3.4):
1970 qemu-system-i386 linux.img \
1971 -net nic,macaddr=52:54:00:12:34:56 \
1972 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1975 @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}]
1976 @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}]
1977 Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular
1978 protocol to transport Ethernet (and other Layer 2) data frames between
1979 two systems. It is present in routers, firewalls and the Linux kernel
1980 (from version 3.3 onwards).
1982 This transport allows a VM to communicate to another VM, router or firewall directly.
1984 @item src=@var{srcaddr}
1985 source address (mandatory)
1986 @item dst=@var{dstaddr}
1987 destination address (mandatory)
1989 select udp encapsulation (default is ip).
1990 @item srcport=@var{srcport}
1992 @item dstport=@var{dstport}
1993 destination udp port.
1995 force v6, otherwise defaults to v4.
1996 @item rxcookie=@var{rxcookie}
1997 @itemx txcookie=@var{txcookie}
1998 Cookies are a weak form of security in the l2tpv3 specification.
1999 Their function is mostly to prevent misconfiguration. By default they are 32
2002 Set cookie size to 64 bit instead of the default 32
2004 Force a 'cut-down' L2TPv3 with no counter as in
2005 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2007 Work around broken counter handling in peer. This may also help on
2008 networks which have packet reorder.
2009 @item offset=@var{offset}
2010 Add an extra offset between header and data
2012 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2013 on the remote Linux host 1.2.3.4:
2015 # Setup tunnel on linux host using raw ip as encapsulation
2017 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2018 encap udp udp_sport 16384 udp_dport 16384
2019 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2020 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2021 ifconfig vmtunnel0 mtu 1500
2022 ifconfig vmtunnel0 up
2023 brctl addif br-lan vmtunnel0
2027 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2029 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
2034 @item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2035 @itemx -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
2036 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
2037 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2038 and MODE @var{octalmode} to change default ownership and permissions for
2039 communication port. This option is only available if QEMU has been compiled
2040 with vde support enabled.
2045 vde_switch -F -sock /tmp/myswitch
2046 # launch QEMU instance
2047 qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch
2050 @item -netdev hubport,id=@var{id},hubid=@var{hubid}
2052 Create a hub port on QEMU "vlan
" @var{hubid}.
2054 The hubport netdev lets you connect a NIC to a QEMU "vlan
" instead of a single
2055 netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the
2056 required hub automatically.
2058 @item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
2060 Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2061 be a unix domain socket backed one. The vhost-user uses a specifically defined
2062 protocol to pass vhost ioctl replacement messages to an application on the other
2063 end of the socket. On non-MSIX guests, the feature can be forced with
2064 @var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2065 be created for multiqueue vhost-user.
2069 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2070 -numa node,memdev=mem \
2071 -chardev socket,path=/path/to/socket \
2072 -netdev type=vhost-user,id=net0,chardev=chr0 \
2073 -device virtio-net-pci,netdev=net0
2076 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
2077 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
2078 At most @var{len} bytes (64k by default) per packet are stored. The file format is
2079 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
2080 Note: For devices created with '-netdev', use '-object filter-dump,...' instead.
2083 Indicate that no network devices should be configured. It is used to
2084 override the default configuration (@option{-net nic -net user}) which
2085 is activated if no @option{-net} options are provided.
2093 DEFHEADING(Character device options:)
2096 The general form of a character device option is:
2100 DEF("chardev
", HAS_ARG, QEMU_OPTION_chardev,
2101 "-chardev
null,id
=id
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2102 "-chardev socket
,id
=id
[,host
=host
],port
=port
[,to
=to
][,ipv4
][,ipv6
][,nodelay
][,reconnect
=seconds
]\n"
2103 " [,server
][,nowait
][,telnet
][,reconnect
=seconds
][,mux
=on|off
]\n"
2104 " [,logfile
=PATH
][,logappend
=on|off
][,tls
-creds
=ID
] (tcp
)\n"
2105 "-chardev socket
,id
=id
,path
=path
[,server
][,nowait
][,telnet
][,reconnect
=seconds
]\n"
2106 " [,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
] (unix
)\n"
2107 "-chardev udp
,id
=id
[,host
=host
],port
=port
[,localaddr
=localaddr
]\n"
2108 " [,localport
=localport
][,ipv4
][,ipv6
][,mux
=on|off
]\n"
2109 " [,logfile
=PATH
][,logappend
=on|off
]\n"
2110 "-chardev msmouse
,id
=id
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2111 "-chardev vc
,id
=id
[[,width
=width
][,height
=height
]][[,cols
=cols
][,rows
=rows
]]\n"
2112 " [,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2113 "-chardev ringbuf
,id
=id
[,size
=size
][,logfile
=PATH
][,logappend
=on|off
]\n"
2114 "-chardev file
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2115 "-chardev pipe
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2117 "-chardev console
,id
=id
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2118 "-chardev serial
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2120 "-chardev pty
,id
=id
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2121 "-chardev stdio
,id
=id
[,mux
=on|off
][,signal
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2123 #ifdef CONFIG_BRLAPI
2124 "-chardev braille
,id
=id
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2126 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2127 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
2128 "-chardev serial
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2129 "-chardev tty
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2131 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
2132 "-chardev parallel
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2133 "-chardev parport
,id
=id
,path
=path
[,mux
=on|off
][,logfile
=PATH
][,logappend
=on|off
]\n"
2135 #if defined(CONFIG_SPICE)
2136 "-chardev spicevmc
,id
=id
,name
=name
[,debug
=debug
][,logfile
=PATH
][,logappend
=on|off
]\n"
2137 "-chardev spiceport
,id
=id
,name
=name
[,debug
=debug
][,logfile
=PATH
][,logappend
=on|off
]\n"
2143 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
2164 The specific backend will determine the applicable options.
2166 All devices must have an id, which can be any string up to 127 characters long.
2167 It is used to uniquely identify this device in other command line directives.
2169 A character device may be used in multiplexing mode by multiple front-ends.
2170 Specify @option{mux=on} to enable this mode.
2171 A multiplexer is a "1:N
" device, and here the "1" end is your specified chardev
2172 backend, and the "N
" end is the various parts of QEMU that can talk to a chardev.
2173 If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2174 create a multiplexer with your specified ID, and you can then configure multiple
2175 front ends to use that chardev ID for their input/output. Up to four different
2176 front ends can be connected to a single multiplexed chardev. (Without
2177 multiplexing enabled, a chardev can only be used by a single front end.)
2178 For instance you could use this to allow a single stdio chardev to be used by
2179 two serial ports and the QEMU monitor:
2182 -chardev stdio,mux=on,id=char0 \
2183 -mon chardev=char0,mode=readline,default \
2184 -serial chardev:char0 \
2185 -serial chardev:char0
2188 You can have more than one multiplexer in a system configuration; for instance
2189 you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2190 multiplexed between the QEMU monitor and a parallel port:
2193 -chardev stdio,mux=on,id=char0 \
2194 -mon chardev=char0,mode=readline,default \
2195 -parallel chardev:char0 \
2196 -chardev tcp,...,mux=on,id=char1 \
2197 -serial chardev:char1 \
2198 -serial chardev:char1
2201 When you're using a multiplexed character device, some escape sequences are
2202 interpreted in the input. @xref{mux_keys, Keys in the character backend
2205 Note that some other command line options may implicitly create multiplexed
2206 character backends; for instance @option{-serial mon:stdio} creates a
2207 multiplexed stdio backend connected to the serial port and the QEMU monitor,
2208 and @option{-nographic} also multiplexes the console and the monitor to
2211 There is currently no support for multiplexing in the other direction
2212 (where a single QEMU front end takes input and output from multiple chardevs).
2214 Every backend supports the @option{logfile} option, which supplies the path
2215 to a file to record all data transmitted via the backend. The @option{logappend}
2216 option controls whether the log file will be truncated or appended to when
2219 Further options to each backend are described below.
2221 @item -chardev null ,id=@var{id}
2222 A void device. This device will not emit any data, and will drop any data it
2223 receives. The null backend does not take any options.
2225 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] [,tls-creds=@var{id}]
2227 Create a two-way stream socket, which can be either a TCP or a unix socket. A
2228 unix socket will be created if @option{path} is specified. Behaviour is
2229 undefined if TCP options are specified for a unix socket.
2231 @option{server} specifies that the socket shall be a listening socket.
2233 @option{nowait} specifies that QEMU should not block waiting for a client to
2234 connect to a listening socket.
2236 @option{telnet} specifies that traffic on the socket should interpret telnet
2239 @option{reconnect} sets the timeout for reconnecting on non-server sockets when
2240 the remote end goes away. qemu will delay this many seconds and then attempt
2241 to reconnect. Zero disables reconnecting, and is the default.
2243 @option{tls-creds} requests enablement of the TLS protocol for encryption,
2244 and specifies the id of the TLS credentials to use for the handshake. The
2245 credentials must be previously created with the @option{-object tls-creds}
2248 TCP and unix socket options are given below:
2252 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
2254 @option{host} for a listening socket specifies the local address to be bound.
2255 For a connecting socket species the remote host to connect to. @option{host} is
2256 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2258 @option{port} for a listening socket specifies the local port to be bound. For a
2259 connecting socket specifies the port on the remote host to connect to.
2260 @option{port} can be given as either a port number or a service name.
2261 @option{port} is required.
2263 @option{to} is only relevant to listening sockets. If it is specified, and
2264 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2265 to and including @option{to} until it succeeds. @option{to} must be specified
2268 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2269 If neither is specified the socket may use either protocol.
2271 @option{nodelay} disables the Nagle algorithm.
2273 @item unix options: path=@var{path}
2275 @option{path} specifies the local path of the unix socket. @option{path} is
2280 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
2282 Sends all traffic from the guest to a remote host over UDP.
2284 @option{host} specifies the remote host to connect to. If not specified it
2285 defaults to @code{localhost}.
2287 @option{port} specifies the port on the remote host to connect to. @option{port}
2290 @option{localaddr} specifies the local address to bind to. If not specified it
2291 defaults to @code{0.0.0.0}.
2293 @option{localport} specifies the local port to bind to. If not specified any
2294 available local port will be used.
2296 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2297 If neither is specified the device may use either protocol.
2299 @item -chardev msmouse ,id=@var{id}
2301 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2304 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
2306 Connect to a QEMU text console. @option{vc} may optionally be given a specific
2309 @option{width} and @option{height} specify the width and height respectively of
2310 the console, in pixels.
2312 @option{cols} and @option{rows} specify that the console be sized to fit a text
2313 console with the given dimensions.
2315 @item -chardev ringbuf ,id=@var{id} [,size=@var{size}]
2317 Create a ring buffer with fixed size @option{size}.
2318 @var{size} must be a power of two, and defaults to @code{64K}).
2320 @item -chardev file ,id=@var{id} ,path=@var{path}
2322 Log all traffic received from the guest to a file.
2324 @option{path} specifies the path of the file to be opened. This file will be
2325 created if it does not already exist, and overwritten if it does. @option{path}
2328 @item -chardev pipe ,id=@var{id} ,path=@var{path}
2330 Create a two-way connection to the guest. The behaviour differs slightly between
2331 Windows hosts and other hosts:
2333 On Windows, a single duplex pipe will be created at
2334 @file{\\.pipe\@option{path}}.
2336 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2337 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2338 received by the guest. Data written by the guest can be read from
2339 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2342 @option{path} forms part of the pipe path as described above. @option{path} is
2345 @item -chardev console ,id=@var{id}
2347 Send traffic from the guest to QEMU's standard output. @option{console} does not
2350 @option{console} is only available on Windows hosts.
2352 @item -chardev serial ,id=@var{id} ,path=@option{path}
2354 Send traffic from the guest to a serial device on the host.
2356 On Unix hosts serial will actually accept any tty device,
2357 not only serial lines.
2359 @option{path} specifies the name of the serial device to open.
2361 @item -chardev pty ,id=@var{id}
2363 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2364 not take any options.
2366 @option{pty} is not available on Windows hosts.
2368 @item -chardev stdio ,id=@var{id} [,signal=on|off]
2369 Connect to standard input and standard output of the QEMU process.
2371 @option{signal} controls if signals are enabled on the terminal, that includes
2372 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2373 default, use @option{signal=off} to disable it.
2375 @option{stdio} is not available on Windows hosts.
2377 @item -chardev braille ,id=@var{id}
2379 Connect to a local BrlAPI server. @option{braille} does not take any options.
2381 @item -chardev tty ,id=@var{id} ,path=@var{path}
2383 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2384 DragonFlyBSD hosts. It is an alias for @option{serial}.
2386 @option{path} specifies the path to the tty. @option{path} is required.
2388 @item -chardev parallel ,id=@var{id} ,path=@var{path}
2389 @itemx -chardev parport ,id=@var{id} ,path=@var{path}
2391 @option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
2393 Connect to a local parallel port.
2395 @option{path} specifies the path to the parallel port device. @option{path} is
2398 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2400 @option{spicevmc} is only available when spice support is built in.
2402 @option{debug} debug level for spicevmc
2404 @option{name} name of spice channel to connect to
2406 Connect to a spice virtual machine channel, such as vdiport.
2408 @item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name}
2410 @option{spiceport} is only available when spice support is built in.
2412 @option{debug} debug level for spicevmc
2414 @option{name} name of spice port to connect to
2416 Connect to a spice port, allowing a Spice client to handle the traffic
2417 identified by a name (preferably a fqdn).
2425 DEFHEADING(Device URL Syntax:)
2428 In addition to using normal file images for the emulated storage devices,
2429 QEMU can also use networked resources such as iSCSI devices. These are
2430 specified using a special URL syntax.
2434 iSCSI support allows QEMU to access iSCSI resources directly and use as
2435 images for the guest storage. Both disk and cdrom images are supported.
2437 Syntax for specifying iSCSI LUNs is
2438 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
2440 By default qemu will use the iSCSI initiator-name
2441 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
2442 line or a configuration file.
2444 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
2445 stalled requests and force a reestablishment of the session. The timeout
2446 is specified in seconds. The default is 0 which means no timeout. Libiscsi
2447 1.15.0 or greater is required for this feature.
2449 Example (without authentication):
2451 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
2452 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
2453 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2456 Example (CHAP username/password via URL):
2458 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
2461 Example (CHAP username/password via environment variables):
2463 LIBISCSI_CHAP_USERNAME="user
" \
2464 LIBISCSI_CHAP_PASSWORD="password
" \
2465 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
2468 iSCSI support is an optional feature of QEMU and only available when
2469 compiled and linked against libiscsi.
2471 DEF("iscsi
", HAS_ARG, QEMU_OPTION_iscsi,
2472 "-iscsi
[user
=user
][,password
=password
]\n"
2473 " [,header
-digest
=CRC32C|CR32C
-NONE|NONE
-CRC32C|NONE
\n"
2474 " [,initiator
-name
=initiator
-iqn
][,id
=target
-iqn
]\n"
2475 " [,timeout
=timeout
]\n"
2476 " iSCSI session parameters
\n", QEMU_ARCH_ALL)
2479 iSCSI parameters such as username and password can also be specified via
2480 a configuration file. See qemu-doc for more information and examples.
2483 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
2484 as Unix Domain Sockets.
2486 Syntax for specifying a NBD device using TCP
2487 ``nbd:<server-ip>:<port>[:exportname=<export>]''
2489 Syntax for specifying a NBD device using Unix Domain Sockets
2490 ``nbd:unix:<domain-socket>[:exportname=<export>]''
2495 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
2498 Example for Unix Domain Sockets
2500 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
2504 QEMU supports SSH (Secure Shell) access to remote disks.
2508 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
2509 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
2512 Currently authentication must be done using ssh-agent. Other
2513 authentication methods may be supported in future.
2516 Sheepdog is a distributed storage system for QEMU.
2517 QEMU supports using either local sheepdog devices or remote networked
2520 Syntax for specifying a sheepdog device
2522 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
2527 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
2530 See also @url{http://http://www.osrg.net/sheepdog/}.
2533 GlusterFS is an user space distributed file system.
2534 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
2535 TCP, Unix Domain Sockets and RDMA transport protocols.
2537 Syntax for specifying a VM disk image on GlusterFS volume is
2539 gluster[+transport]://[server[:port]]/volname/image[?socket=...]
2545 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
2548 See also @url{http://www.gluster.org}.
2550 @item HTTP/HTTPS/FTP/FTPS/TFTP
2551 QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp.
2553 Syntax using a single filename:
2555 <protocol>://[<username>[:<password>]@@]<host>/<path>
2561 'http', 'https', 'ftp', 'ftps', or 'tftp'.
2564 Optional username for authentication to the remote server.
2567 Optional password for authentication to the remote server.
2570 Address of the remote server.
2573 Path on the remote server, including any query string.
2576 The following options are also supported:
2579 The full URL when passing options to the driver explicitly.
2582 The amount of data to read ahead with each range request to the remote server.
2583 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
2584 does not have a suffix, it will be assumed to be in bytes. The value must be a
2585 multiple of 512 bytes. It defaults to 256k.
2588 Whether to verify the remote server's certificate when connecting over SSL. It
2589 can have the value 'on' or 'off'. It defaults to 'on'.
2592 Send this cookie (it can also be a list of cookies separated by ';') with
2593 each outgoing request. Only supported when using protocols such as HTTP
2594 which support cookies, otherwise ignored.
2597 Set the timeout in seconds of the CURL connection. This timeout is the time
2598 that CURL waits for a response from the remote server to get the size of the
2599 image to be downloaded. If not set, the default timeout of 5 seconds is used.
2602 Note that when passing options to qemu explicitly, @option{driver} is the value
2605 Example: boot from a remote Fedora 20 live ISO image
2607 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
2609 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
2612 Example: boot from a remote Fedora 20 cloud image using a local overlay for
2613 writes, copy-on-read, and a readahead of 64k
2615 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
2617 qemu
-system
-x86_64
-drive file
=/tmp
/Fedora
-x86_64
-20-20131211.1-sda
.qcow2
,copy
-on
-read
=on
2620 Example
: boot from an image stored on a VMware vSphere server with a self
-signed
2621 certificate
using a local overlay
for writes
, a readahead of
64k and a timeout
2624 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
2626 qemu
-system
-x86_64
-drive file
=/tmp
/test
.qcow2
2634 DEFHEADING(Bluetooth(R
) options
:)
2639 DEF("bt", HAS_ARG
, QEMU_OPTION_bt
, \
2640 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
2641 "-bt hci,host[:id]\n" \
2642 " use host's HCI with the given name\n" \
2643 "-bt hci[,vlan=n]\n" \
2644 " emulate a standard HCI in virtual scatternet 'n'\n" \
2645 "-bt vhci[,vlan=n]\n" \
2646 " add host computer to virtual scatternet 'n' using VHCI\n" \
2647 "-bt device:dev[,vlan=n]\n" \
2648 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
2653 Defines the
function of the corresponding Bluetooth HCI
. -bt options
2654 are matched with the HCIs present
in the chosen machine type
. For
2655 example when emulating a machine with only one HCI built into it
, only
2656 the first @code
{-bt hci
[...]} option is valid and defines the HCI
's
2657 logic. The Transport Layer is decided by the machine type. Currently
2658 the machines @code{n800} and @code{n810} have one HCI and all other
2662 The following three types are recognized:
2666 (default) The corresponding Bluetooth HCI assumes no internal logic
2667 and will not respond to any HCI commands or emit events.
2669 @item -bt hci,host[:@var{id}]
2670 (@code{bluez} only) The corresponding HCI passes commands / events
2671 to / from the physical HCI identified by the name @var{id} (default:
2672 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
2673 capable systems like Linux.
2675 @item -bt hci[,vlan=@var{n}]
2676 Add a virtual, standard HCI that will participate in the Bluetooth
2677 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
2678 VLANs, devices inside a bluetooth network @var{n} can only communicate
2679 with other devices in the same network (scatternet).
2682 @item -bt vhci[,vlan=@var{n}]
2683 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
2684 to the host bluetooth stack instead of to the emulated target. This
2685 allows the host and target machines to participate in a common scatternet
2686 and communicate. Requires the Linux @code{vhci} driver installed. Can
2687 be used as following:
2690 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2693 @item -bt device:@var{dev}[,vlan=@var{n}]
2694 Emulate a bluetooth device @var{dev} and place it in network @var{n}
2695 (default @code{0}). QEMU can only emulate one type of bluetooth devices
2700 Virtual wireless keyboard implementing the HIDP bluetooth profile.
2710 DEFHEADING(TPM device options:)
2712 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
2713 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
2714 " use path to provide path to a character device; default is /dev/tpm0\n"
2715 " use cancel-path to provide path to TPM's cancel sysfs entry
; if\n"
2716 " not provided it will be searched
for in /sys
/class/misc
/tpm?
/device
\n",
2720 The general form of a TPM device option is:
2723 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
2725 Backend type must be:
2726 @option{passthrough}.
2728 The specific backend type will determine the applicable options.
2729 The @code{-tpmdev} option creates the TPM backend and requires a
2730 @code{-device} option that specifies the TPM frontend interface model.
2732 Options to each backend are described below.
2734 Use 'help' to print all available TPM backend types.
2739 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
2741 (Linux-host only) Enable access to the host's TPM using the passthrough
2744 @option{path} specifies the path to the host's TPM device, i.e., on
2745 a Linux host this would be @code{/dev/tpm0}.
2746 @option{path} is optional and by default @code{/dev/tpm0} is used.
2748 @option{cancel-path} specifies the path to the host TPM device's sysfs
2749 entry allowing for cancellation of an ongoing TPM command.
2750 @option{cancel-path} is optional and by default QEMU will search for the
2753 Some notes about using the host's TPM with the passthrough driver:
2755 The TPM device accessed by the passthrough driver must not be
2756 used by any other application on the host.
2758 Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
2759 the VM's firmware (BIOS/UEFI) will not be able to initialize the
2760 TPM again and may therefore not show a TPM-specific menu that would
2761 otherwise allow the user to configure the TPM, e.g., allow the user to
2762 enable/disable or activate/deactivate the TPM.
2763 Further, if TPM ownership is released from within a VM then the host's TPM
2764 will get disabled and deactivated. To enable and activate the
2765 TPM again afterwards, the host has to be rebooted and the user is
2766 required to enter the firmware's menu to enable and activate the TPM.
2767 If the TPM is left disabled and/or deactivated most TPM commands will fail.
2769 To create a passthrough TPM use the following two options:
2771 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2773 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
2774 @code{tpmdev=tpm0} in the device option.
2784 DEFHEADING(Linux/Multiboot boot specific:)
2787 When using these options, you can use a given Linux or Multiboot
2788 kernel without installing it in the disk image. It can be useful
2789 for easier testing of various kernels.
2794 DEF("kernel
", HAS_ARG, QEMU_OPTION_kernel, \
2795 "-kernel bzImage use
'bzImage' as kernel image
\n", QEMU_ARCH_ALL)
2797 @item -kernel @var{bzImage}
2799 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2800 or in multiboot format.
2803 DEF("append
", HAS_ARG, QEMU_OPTION_append, \
2804 "-append cmdline use
'cmdline' as kernel command line
\n", QEMU_ARCH_ALL)
2806 @item -append @var{cmdline}
2808 Use @var{cmdline} as kernel command line
2811 DEF("initrd
", HAS_ARG, QEMU_OPTION_initrd, \
2812 "-initrd file use
'file' as initial ram disk
\n", QEMU_ARCH_ALL)
2814 @item -initrd @var{file}
2816 Use @var{file} as initial ram disk.
2818 @item -initrd "@
var{file1
} arg
=foo
,@
var{file2
}"
2820 This syntax is only available with multiboot.
2822 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2826 DEF("dtb
", HAS_ARG, QEMU_OPTION_dtb, \
2827 "-dtb file use
'file' as device tree image
\n", QEMU_ARCH_ALL)
2829 @item -dtb @var{file}
2831 Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
2840 DEFHEADING(Debug/Expert options:)
2845 DEF("fw_cfg
", HAS_ARG, QEMU_OPTION_fwcfg,
2846 "-fw_cfg
[name
=]<name
>,file
=<file
>\n"
2847 " add named fw_cfg entry from file
\n"
2848 "-fw_cfg
[name
=]<name
>,string
=<str
>\n"
2849 " add named fw_cfg entry from string
\n",
2852 @item -fw_cfg [name=]@var{name},file=@var{file}
2854 Add named fw_cfg entry from file. @var{name} determines the name of
2855 the entry in the fw_cfg file directory exposed to the guest.
2857 @item -fw_cfg [name=]@var{name},string=@var{str}
2858 Add named fw_cfg entry from string.
2861 DEF("serial
", HAS_ARG, QEMU_OPTION_serial, \
2862 "-serial dev redirect the serial port to char device
'dev'\n",
2865 @item -serial @var{dev}
2867 Redirect the virtual serial port to host character device
2868 @var{dev}. The default device is @code{vc} in graphical mode and
2869 @code{stdio} in non graphical mode.
2871 This option can be used several times to simulate up to 4 serial
2874 Use @code{-serial none} to disable all serial ports.
2876 Available character devices are:
2878 @item vc[:@var{W}x@var{H}]
2879 Virtual console. Optionally, a width and height can be given in pixel with
2883 It is also possible to specify width or height in characters:
2888 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2890 No device is allocated.
2893 @item chardev:@var{id}
2894 Use a named character device defined with the @code{-chardev} option.
2896 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2897 parameters are set according to the emulated ones.
2898 @item /dev/parport@var{N}
2899 [Linux only, parallel port only] Use host parallel port
2900 @var{N}. Currently SPP and EPP parallel port features can be used.
2901 @item file:@var{filename}
2902 Write output to @var{filename}. No character can be read.
2904 [Unix only] standard input/output
2905 @item pipe:@var{filename}
2906 name pipe @var{filename}
2908 [Windows only] Use host serial port @var{n}
2909 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2910 This implements UDP Net Console.
2911 When @var{remote_host} or @var{src_ip} are not specified
2912 they default to @code{0.0.0.0}.
2913 When not using a specified @var{src_port} a random port is automatically chosen.
2915 If you just want a simple readonly console you can use @code{netcat} or
2916 @code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
2917 @code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
2918 will appear in the netconsole session.
2920 If you plan to send characters back via netconsole or you want to stop
2921 and start QEMU a lot of times, you should have QEMU use the same
2922 source port each time by using something like @code{-serial
2923 udp::4555@@:4556} to QEMU. Another approach is to use a patched
2924 version of netcat which can listen to a TCP port and send and receive
2925 characters via udp. If you have a patched version of netcat which
2926 activates telnet remote echo and single char transfer, then you can
2927 use the following options to step up a netcat redirector to allow
2928 telnet on port 5555 to access the QEMU port.
2931 -serial udp::4555@@:4556
2932 @item netcat options:
2933 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2934 @item telnet options:
2938 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
2939 The TCP Net Console has two modes of operation. It can send the serial
2940 I/O to a location or wait for a connection from a location. By default
2941 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
2942 the @var{server} option QEMU will wait for a client socket application
2943 to connect to the port before continuing, unless the @code{nowait}
2944 option was specified. The @code{nodelay} option disables the Nagle buffering
2945 algorithm. The @code{reconnect} option only applies if @var{noserver} is
2946 set, if the connection goes down it will attempt to reconnect at the
2947 given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
2948 one TCP connection at a time is accepted. You can use @code{telnet} to
2949 connect to the corresponding character device.
2951 @item Example to send tcp console to 192.168.0.2 port 4444
2952 -serial tcp:192.168.0.2:4444
2953 @item Example to listen and wait on port 4444 for connection
2954 -serial tcp::4444,server
2955 @item Example to not wait and listen on ip 192.168.0.100 port 4444
2956 -serial tcp:192.168.0.100:4444,server,nowait
2959 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
2960 The telnet protocol is used instead of raw tcp sockets. The options
2961 work the same as if you had specified @code{-serial tcp}. The
2962 difference is that the port acts like a telnet server or client using
2963 telnet option negotiation. This will also allow you to send the
2964 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
2965 sequence. Typically in unix telnet you do it with Control-] and then
2966 type "send
break" followed by pressing the enter key.
2968 @item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
2969 A unix domain socket is used instead of a tcp socket. The option works the
2970 same as if you had specified @code{-serial tcp} except the unix domain socket
2971 @var{path} is used for connections.
2973 @item mon:@var{dev_string}
2974 This is a special option to allow the monitor to be multiplexed onto
2975 another serial port. The monitor is accessed with key sequence of
2976 @key{Control-a} and then pressing @key{c}.
2977 @var{dev_string} should be any one of the serial devices specified
2978 above. An example to multiplex the monitor onto a telnet server
2979 listening on port 4444 would be:
2981 @item -serial mon:telnet::4444,server,nowait
2983 When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
2984 QEMU any more but will be passed to the guest instead.
2987 Braille device. This will use BrlAPI to display the braille output on a real
2991 Three button serial mouse. Configure the guest to use Microsoft protocol.
2995 DEF("parallel
", HAS_ARG, QEMU_OPTION_parallel, \
2996 "-parallel dev redirect the parallel port to char device
'dev'\n",
2999 @item -parallel @var{dev}
3001 Redirect the virtual parallel port to host device @var{dev} (same
3002 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3003 be used to use hardware devices connected on the corresponding host
3006 This option can be used several times to simulate up to 3 parallel
3009 Use @code{-parallel none} to disable all parallel ports.
3012 DEF("monitor
", HAS_ARG, QEMU_OPTION_monitor, \
3013 "-monitor dev redirect the monitor to char device
'dev'\n",
3016 @item -monitor @var{dev}
3018 Redirect the monitor to host device @var{dev} (same devices as the
3020 The default device is @code{vc} in graphical mode and @code{stdio} in
3022 Use @code{-monitor none} to disable the default monitor.
3024 DEF("qmp
", HAS_ARG, QEMU_OPTION_qmp, \
3025 "-qmp dev like
-monitor but opens
in 'control' mode
\n",
3028 @item -qmp @var{dev}
3030 Like -monitor but opens in 'control' mode.
3032 DEF("qmp
-pretty
", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3033 "-qmp
-pretty dev like
-qmp but uses pretty JSON formatting
\n",
3036 @item -qmp-pretty @var{dev}
3038 Like -qmp but uses pretty JSON formatting.
3041 DEF("mon
", HAS_ARG, QEMU_OPTION_mon, \
3042 "-mon
[chardev
=]name
[,mode
=readline|control
][,default]\n", QEMU_ARCH_ALL)
3044 @item -mon [chardev=]name[,mode=readline|control][,default]
3046 Setup monitor on chardev @var{name}.
3049 DEF("debugcon
", HAS_ARG, QEMU_OPTION_debugcon, \
3050 "-debugcon dev redirect the debug console to char device
'dev'\n",
3053 @item -debugcon @var{dev}
3055 Redirect the debug console to host device @var{dev} (same devices as the
3056 serial port). The debug console is an I/O port which is typically port
3057 0xe9; writing to that I/O port sends output to this device.
3058 The default device is @code{vc} in graphical mode and @code{stdio} in
3062 DEF("pidfile
", HAS_ARG, QEMU_OPTION_pidfile, \
3063 "-pidfile file write PID to
'file'\n", QEMU_ARCH_ALL)
3065 @item -pidfile @var{file}
3067 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3071 DEF("singlestep
", 0, QEMU_OPTION_singlestep, \
3072 "-singlestep always run
in singlestep mode
\n", QEMU_ARCH_ALL)
3076 Run the emulation in single step mode.
3079 DEF("S
", 0, QEMU_OPTION_S, \
3080 "-S freeze CPU at
startup (use
'c' to start execution
)\n",
3085 Do not start CPU at startup (you must type 'c' in the monitor).
3088 DEF("realtime
", HAS_ARG, QEMU_OPTION_realtime,
3089 "-realtime
[mlock
=on|off
]\n"
3090 " run qemu with realtime features
\n"
3091 " mlock
=on|off controls mlock
support (default: on
)\n",
3094 @item -realtime mlock=on|off
3096 Run qemu with realtime features.
3097 mlocking qemu and guest memory can be enabled via @option{mlock=on}
3098 (enabled by default).
3101 DEF("gdb
", HAS_ARG, QEMU_OPTION_gdb, \
3102 "-gdb dev wait
for gdb connection on
'dev'\n", QEMU_ARCH_ALL)
3104 @item -gdb @var{dev}
3106 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3107 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
3108 stdio are reasonable use case. The latter is allowing to start QEMU from
3109 within gdb and establish the connection via a pipe:
3111 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
3115 DEF("s
", 0, QEMU_OPTION_s, \
3116 "-s shorthand
for -gdb tcp
::" DEFAULT_GDBSTUB_PORT "\n",
3121 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3122 (@pxref{gdb_usage}).
3125 DEF("d
", HAS_ARG, QEMU_OPTION_d, \
3126 "-d item1
,... enable logging of specified
items (use
'-d help' for a list of log items
)\n",
3129 @item -d @var{item1}[,...]
3131 Enable logging of specified items. Use '-d help' for a list of log items.
3134 DEF("D
", HAS_ARG, QEMU_OPTION_D, \
3135 "-D logfile output log to
logfile (default stderr
)\n",
3138 @item -D @var{logfile}
3140 Output log in @var{logfile} instead of to stderr
3143 DEF("L
", HAS_ARG, QEMU_OPTION_L, \
3144 "-L path set the directory
for the BIOS
, VGA BIOS and keymaps
\n",
3149 Set the directory for the BIOS, VGA BIOS and keymaps.
3152 DEF("bios
", HAS_ARG, QEMU_OPTION_bios, \
3153 "-bios file set the filename
for the BIOS
\n", QEMU_ARCH_ALL)
3155 @item -bios @var{file}
3157 Set the filename for the BIOS.
3160 DEF("enable
-kvm
", 0, QEMU_OPTION_enable_kvm, \
3161 "-enable
-kvm enable KVM full virtualization support
\n", QEMU_ARCH_ALL)
3165 Enable KVM full virtualization support. This option is only available
3166 if KVM support is enabled when compiling.
3169 DEF("xen
-domid
", HAS_ARG, QEMU_OPTION_xen_domid,
3170 "-xen
-domid id specify xen guest domain id
\n", QEMU_ARCH_ALL)
3171 DEF("xen
-create
", 0, QEMU_OPTION_xen_create,
3172 "-xen
-create create domain
using xen hypercalls
, bypassing xend
\n"
3173 " warning
: should not be used when xend is
in use
\n",
3175 DEF("xen
-attach
", 0, QEMU_OPTION_xen_attach,
3176 "-xen
-attach attach to existing xen domain
\n"
3177 " xend will use
this when starting QEMU
\n",
3180 @item -xen-domid @var{id}
3182 Specify xen guest domain @var{id} (XEN only).
3185 Create domain using xen hypercalls, bypassing xend.
3186 Warning: should not be used when xend is in use (XEN only).
3189 Attach to existing xen domain.
3190 xend will use this when starting QEMU (XEN only).
3193 DEF("no
-reboot
", 0, QEMU_OPTION_no_reboot, \
3194 "-no
-reboot exit instead of rebooting
\n", QEMU_ARCH_ALL)
3198 Exit instead of rebooting.
3201 DEF("no
-shutdown
", 0, QEMU_OPTION_no_shutdown, \
3202 "-no
-shutdown stop before shutdown
\n", QEMU_ARCH_ALL)
3205 @findex -no-shutdown
3206 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3207 This allows for instance switching to monitor to commit changes to the
3211 DEF("loadvm
", HAS_ARG, QEMU_OPTION_loadvm, \
3212 "-loadvm
[tag|id
]\n" \
3213 " start right away with a saved
state (loadvm
in monitor
)\n",
3216 @item -loadvm @var{file}
3218 Start right away with a saved state (@code{loadvm} in monitor)
3222 DEF("daemonize
", 0, QEMU_OPTION_daemonize, \
3223 "-daemonize daemonize QEMU after initializing
\n", QEMU_ARCH_ALL)
3228 Daemonize the QEMU process after initialization. QEMU will not detach from
3229 standard IO until it is ready to receive connections on any of its devices.
3230 This option is a useful way for external programs to launch QEMU without having
3231 to cope with initialization race conditions.
3234 DEF("option
-rom
", HAS_ARG, QEMU_OPTION_option_rom, \
3235 "-option
-rom rom load a file
, rom
, into the option ROM space
\n",
3238 @item -option-rom @var{file}
3240 Load the contents of @var{file} as an option ROM.
3241 This option is useful to load things like EtherBoot.
3244 HXCOMM Silently ignored for compatibility
3245 DEF("clock
", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL)
3247 HXCOMM Options deprecated by -rtc
3248 DEF("localtime
", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
3249 DEF("startdate
", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
3251 DEF("rtc
", HAS_ARG, QEMU_OPTION_rtc, \
3252 "-rtc
[base
=utc|localtime|date
][,clock
=host|rt|vm
][,driftfix
=none|slew
]\n" \
3253 " set the RTC base and clock
, enable drift fix
for clock
ticks (x86 only
)\n",
3258 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
3260 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3261 UTC or local time, respectively. @code{localtime} is required for correct date in
3262 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
3263 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3265 By default the RTC is driven by the host system time. This allows using of the
3266 RTC as accurate reference clock inside the guest, specifically if the host
3267 time is smoothly following an accurate external reference clock, e.g. via NTP.
3268 If you want to isolate the guest time from the host, you can set @option{clock}
3269 to @code{rt} instead. To even prevent it from progressing during suspension,
3270 you can set it to @code{vm}.
3272 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3273 specifically with Windows' ACPI HAL. This option will try to figure out how
3274 many timer interrupts were not processed by the Windows guest and will
3278 DEF("icount
", HAS_ARG, QEMU_OPTION_icount, \
3279 "-icount
[shift
=N|auto
][,align
=on|off
][,sleep
=on|off
,rr
=record|replay
,rrfile
=<filename
>]\n" \
3280 " enable virtual instruction counter with
2^N clock ticks per
\n" \
3281 " instruction
, enable aligning the host and virtual clocks
\n" \
3282 " or disable real time cpu sleeping
\n", QEMU_ARCH_ALL)
3284 @item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename}]
3286 Enable virtual instruction counter. The virtual cpu will execute one
3287 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
3288 then the virtual cpu speed will be automatically adjusted to keep virtual
3289 time within a few seconds of real time.
3291 When the virtual cpu is sleeping, the virtual time will advance at default
3292 speed unless @option{sleep=on|off} is specified.
3293 With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
3294 instantly whenever the virtual cpu goes to sleep mode and will not advance
3295 if no timer is enabled. This behavior give deterministic execution times from
3296 the guest point of view.
3298 Note that while this option can give deterministic behavior, it does not
3299 provide cycle accurate emulation. Modern CPUs contain superscalar out of
3300 order cores with complex cache hierarchies. The number of instructions
3301 executed often has little or no correlation with actual performance.
3303 @option{align=on} will activate the delay algorithm which will try
3304 to synchronise the host clock and the virtual clock. The goal is to
3305 have a guest running at the real frequency imposed by the shift option.
3306 Whenever the guest clock is behind the host clock and if
3307 @option{align=on} is specified then we print a message to the user
3308 to inform about the delay.
3309 Currently this option does not work when @option{shift} is @code{auto}.
3310 Note: The sync algorithm will work for those shift values for which
3311 the guest clock runs ahead of the host clock. Typically this happens
3312 when the shift value is high (how high depends on the host machine).
3314 When @option{rr} option is specified deterministic record/replay is enabled.
3315 Replay log is written into @var{filename} file in record mode and
3316 read from this file in replay mode.
3319 DEF("watchdog
", HAS_ARG, QEMU_OPTION_watchdog, \
3320 "-watchdog model
\n" \
3321 " enable virtual hardware watchdog
[default=none
]\n",
3324 @item -watchdog @var{model}
3326 Create a virtual hardware watchdog device. Once enabled (by a guest
3327 action), the watchdog must be periodically polled by an agent inside
3328 the guest or else the guest will be restarted. Choose a model for
3329 which your guest has drivers.
3331 The @var{model} is the model of hardware watchdog to emulate. Use
3332 @code{-watchdog help} to list available hardware models. Only one
3333 watchdog can be enabled for a guest.
3335 The following models may be available:
3338 iBASE 700 is a very simple ISA watchdog with a single timer.
3340 Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3341 dual-timer watchdog.
3343 A virtual watchdog for s390x backed by the diagnose 288 hypercall
3344 (currently KVM only).
3348 DEF("watchdog
-action
", HAS_ARG, QEMU_OPTION_watchdog_action, \
3349 "-watchdog
-action reset|shutdown|poweroff|pause|debug|none
\n" \
3350 " action when watchdog fires
[default=reset
]\n",
3353 @item -watchdog-action @var{action}
3354 @findex -watchdog-action
3356 The @var{action} controls what QEMU will do when the watchdog timer
3359 @code{reset} (forcefully reset the guest).
3360 Other possible actions are:
3361 @code{shutdown} (attempt to gracefully shutdown the guest),
3362 @code{poweroff} (forcefully poweroff the guest),
3363 @code{pause} (pause the guest),
3364 @code{debug} (print a debug message and continue), or
3365 @code{none} (do nothing).
3367 Note that the @code{shutdown} action requires that the guest responds
3368 to ACPI signals, which it may not be able to do in the sort of
3369 situations where the watchdog would have expired, and thus
3370 @code{-watchdog-action shutdown} is not recommended for production use.
3375 @item -watchdog i6300esb -watchdog-action pause
3376 @itemx -watchdog ib700
3380 DEF("echr
", HAS_ARG, QEMU_OPTION_echr, \
3381 "-echr chr set terminal escape character instead of ctrl
-a
\n",
3385 @item -echr @var{numeric_ascii_value}
3387 Change the escape character used for switching to the monitor when using
3388 monitor and serial sharing. The default is @code{0x01} when using the
3389 @code{-nographic} option. @code{0x01} is equal to pressing
3390 @code{Control-a}. You can select a different character from the ascii
3391 control keys where 1 through 26 map to Control-a through Control-z. For
3392 instance you could use the either of the following to change the escape
3393 character to Control-t.
3400 DEF("virtioconsole
", HAS_ARG, QEMU_OPTION_virtiocon, \
3401 "-virtioconsole c
\n" \
3402 " set virtio console
\n", QEMU_ARCH_ALL)
3404 @item -virtioconsole @var{c}
3405 @findex -virtioconsole
3408 This option is maintained for backward compatibility.
3410 Please use @code{-device virtconsole} for the new way of invocation.
3413 DEF("show
-cursor
", 0, QEMU_OPTION_show_cursor, \
3414 "-show
-cursor show cursor
\n", QEMU_ARCH_ALL)
3417 @findex -show-cursor
3421 DEF("tb
-size
", HAS_ARG, QEMU_OPTION_tb_size, \
3422 "-tb
-size n set TB size
\n", QEMU_ARCH_ALL)
3424 @item -tb-size @var{n}
3429 DEF("incoming
", HAS_ARG, QEMU_OPTION_incoming, \
3430 "-incoming tcp
:[host
]:port
[,to
=maxport
][,ipv4
][,ipv6
]\n" \
3431 "-incoming rdma
:host
:port
[,ipv4
][,ipv6
]\n" \
3432 "-incoming unix
:socketpath
\n" \
3433 " prepare
for incoming migration
, listen on
\n" \
3434 " specified protocol and socket address
\n" \
3435 "-incoming fd
:fd
\n" \
3436 "-incoming exec
:cmdline
\n" \
3437 " accept incoming migration on given file descriptor
\n" \
3438 " or from given external command
\n" \
3439 "-incoming defer
\n" \
3440 " wait
for the URI to be specified via migrate_incoming
\n",
3443 @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
3444 @itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
3446 Prepare for incoming migration, listen on a given tcp port.
3448 @item -incoming unix:@var{socketpath}
3449 Prepare for incoming migration, listen on a given unix socket.
3451 @item -incoming fd:@var{fd}
3452 Accept incoming migration from a given filedescriptor.
3454 @item -incoming exec:@var{cmdline}
3455 Accept incoming migration as an output from specified external command.
3457 @item -incoming defer
3458 Wait for the URI to be specified via migrate_incoming. The monitor can
3459 be used to change settings (such as migration parameters) prior to issuing
3460 the migrate_incoming to allow the migration to begin.
3463 DEF("nodefaults
", 0, QEMU_OPTION_nodefaults, \
3464 "-nodefaults don
't create default devices\n", QEMU_ARCH_ALL)
3468 Don't create
default devices
. Normally
, QEMU sets the
default devices like serial
3469 port
, parallel port
, virtual console
, monitor device
, VGA adapter
, floppy and
3470 CD
-ROM drive and others
. The @code
{-nodefaults
} option will disable all those
3475 DEF("chroot", HAS_ARG
, QEMU_OPTION_chroot
, \
3476 "-chroot dir chroot to dir just before starting the VM\n",
3480 @item
-chroot @
var{dir
}
3482 Immediately before starting guest execution
, chroot to the specified
3483 directory
. Especially useful
in combination with
-runas
.
3487 DEF("runas", HAS_ARG
, QEMU_OPTION_runas
, \
3488 "-runas user change to user id user just before starting the VM\n",
3492 @item
-runas @
var{user
}
3494 Immediately before starting guest execution
, drop root privileges
, switching
3495 to the specified user
.
3498 DEF("prom-env", HAS_ARG
, QEMU_OPTION_prom_env
,
3499 "-prom-env variable=value\n"
3500 " set OpenBIOS nvram variables\n",
3501 QEMU_ARCH_PPC | QEMU_ARCH_SPARC
)
3503 @item
-prom
-env @
var{variable
}=@
var{value
}
3505 Set OpenBIOS nvram @
var{variable
} to given @
var{value
} (PPC
, SPARC only
).
3507 DEF("semihosting", 0, QEMU_OPTION_semihosting
,
3508 "-semihosting semihosting mode\n",
3509 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3513 @findex
-semihosting
3514 Enable semihosting
mode (ARM
, M68K
, Xtensa
, MIPS only
).
3516 DEF("semihosting-config", HAS_ARG
, QEMU_OPTION_semihosting_config
,
3517 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3518 " semihosting configuration\n",
3519 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
3522 @item
-semihosting
-config
[enable
=on|off
][,target
=native|gdb|auto
][,arg
=str
[,...]]
3523 @findex
-semihosting
-config
3524 Enable and configure
semihosting (ARM
, M68K
, Xtensa
, MIPS only
).
3526 @item target
=@code
{native|gdb|auto
}
3527 Defines where the semihosting calls will be addressed
, to
QEMU (@code
{native
})
3528 or to
GDB (@code
{gdb
}). The
default is @code
{auto
}, which means @code
{gdb
}
3529 during debug sessions and @code
{native
} otherwise
.
3530 @item arg
=@
var{str1
},arg
=@
var{str2
},...
3531 Allows the user to pass input arguments
, and can be used multiple times to build
3532 up a list
. The old
-style @code
{-kernel
}/@code
{-append
} method of passing a
3533 command line is still supported
for backward compatibility
. If both the
3534 @code
{--semihosting
-config arg
} and the @code
{-kernel
}/@code
{-append
} are
3535 specified
, the former is passed to semihosting as it always takes precedence
.
3538 DEF("old-param", 0, QEMU_OPTION_old_param
,
3539 "-old-param old param mode\n", QEMU_ARCH_ARM
)
3542 @findex
-old
-param (ARM
)
3543 Old param
mode (ARM only
).
3546 DEF("sandbox", HAS_ARG
, QEMU_OPTION_sandbox
, \
3547 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n",
3550 @item
-sandbox @
var{arg
}
3552 Enable Seccomp mode
2 system call filter
. 'on' will enable syscall filtering and
'off' will
3553 disable it
. The
default is
'off'.
3556 DEF("readconfig", HAS_ARG
, QEMU_OPTION_readconfig
,
3557 "-readconfig <file>\n", QEMU_ARCH_ALL
)
3559 @item
-readconfig @
var{file
}
3561 Read device configuration from @
var{file
}. This approach is useful when you want to spawn
3562 QEMU process with many command line options but you don
't want to exceed the command line
3565 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
3566 "-writeconfig <file>\n"
3567 " read/write config file\n", QEMU_ARCH_ALL)
3569 @item -writeconfig @var{file}
3570 @findex -writeconfig
3571 Write device configuration to @var{file}. The @var{file} can be either filename to save
3572 command line and device configuration into file or dash @code{-}) character to print the
3573 output to stdout. This can be later used as input file for @code{-readconfig} option.
3575 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
3577 " do not load default config files at startup\n",
3581 @findex -nodefconfig
3582 Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup.
3583 The @code{-nodefconfig} option will prevent QEMU from loading any of those config files.
3585 DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
3587 " do not load user-provided config files at startup\n",
3590 @item -no-user-config
3591 @findex -no-user-config
3592 The @code{-no-user-config} option makes QEMU not load any of the user-provided
3593 config files on @var{sysconfdir}, but won't make it skip the QEMU
-provided config
3594 files from @
var{datadir
}.
3596 DEF("trace", HAS_ARG
, QEMU_OPTION_trace
,
3597 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
3598 " specify tracing options\n",
3601 HXCOMM This line is not accurate
, as some sub
-options are backend
-specific but
3602 HXCOMM HX does not support conditional compilation of text
.
3603 @item
-trace [events
=@
var{file
}][,file
=@
var{file
}]
3606 Specify tracing options
.
3609 @item
[enable
=]@
var{pattern
}
3610 Immediately enable events matching @
var{pattern
}.
3611 The file must contain one event
name (as listed
in the @file
{trace-events
} file
)
3612 per line
; globbing patterns are accepted too
. This option is only
3613 available
if QEMU has been compiled with the @
var{simple
}, @
var{stderr
}
3614 or @
var{ftrace
} tracing backend
. To specify multiple events or patterns
,
3615 specify the @option
{-trace} option multiple times
.
3617 Use @code
{-trace help
} to print a list of names of
trace points
.
3619 @item events
=@
var{file
}
3620 Immediately enable events listed
in @
var{file
}.
3621 The file must contain one event
name (as listed
in the @file
{trace-events
} file
)
3622 per line
; globbing patterns are accepted too
. This option is only
3623 available
if QEMU has been compiled with the @
var{simple
}, @
var{stderr
} or
3624 @
var{ftrace
} tracing backend
.
3626 @item file
=@
var{file
}
3627 Log output traces to @
var{file
}.
3628 This option is only available
if QEMU has been compiled with
3629 the @
var{simple
} tracing backend
.
3634 DEF("qtest", HAS_ARG
, QEMU_OPTION_qtest
, "", QEMU_ARCH_ALL
)
3635 DEF("qtest-log", HAS_ARG
, QEMU_OPTION_qtest_log
, "", QEMU_ARCH_ALL
)
3638 DEF("enable-fips", 0, QEMU_OPTION_enablefips
,
3639 "-enable-fips enable FIPS 140-2 compliance\n",
3644 @findex
-enable
-fips
3645 Enable FIPS
140-2 compliance mode
.
3648 HXCOMM Deprecated by
-machine accel
=tcg property
3649 DEF("no-kvm", 0, QEMU_OPTION_no_kvm
, "", QEMU_ARCH_I386
)
3651 HXCOMM Deprecated by kvm
-pit driver properties
3652 DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection
,
3655 HXCOMM
Deprecated (ignored
)
3656 DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit
, "", QEMU_ARCH_I386
)
3658 HXCOMM Deprecated by
-machine kernel_irqchip
=on|off property
3659 DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip
, "", QEMU_ARCH_I386
)
3661 HXCOMM
Deprecated (ignored
)
3662 DEF("tdf", 0, QEMU_OPTION_tdf
,"", QEMU_ARCH_ALL
)
3664 DEF("msg", HAS_ARG
, QEMU_OPTION_msg
,
3665 "-msg timestamp[=on|off]\n"
3666 " change the format of messages\n"
3667 " on|off controls leading timestamps (default:on)\n",
3670 @item
-msg timestamp
[=on|off
]
3672 prepend a timestamp to each log message
.(default:on
)
3675 DEF("dump-vmstate", HAS_ARG
, QEMU_OPTION_dump_vmstate
,
3676 "-dump-vmstate <file>\n"
3677 " Output vmstate information in JSON format to file.\n"
3678 " Use the scripts/vmstate-static-checker.py file to\n"
3679 " check for possible regressions in migration code\n"
3680 " by comparing two such vmstate dumps.\n",
3683 @item
-dump
-vmstate @
var{file
}
3684 @findex
-dump
-vmstate
3685 Dump json
-encoded vmstate information
for current machine type to file
3689 DEFHEADING(Generic object creation
)
3691 DEF("object", HAS_ARG
, QEMU_OPTION_object
,
3692 "-object TYPENAME[,PROP1=VALUE1,...]\n"
3693 " create a new object of type TYPENAME setting properties\n"
3694 " in the order they are specified. Note that the 'id'\n"
3695 " property must be set. These objects are placed in the\n"
3696 " '/objects' path.\n",
3699 @item
-object @
var{typename
}[,@
var{prop1
}=@
var{value1
},...]
3701 Create a
new object of type @
var{typename
} setting properties
3702 in the order they are specified
. Note that the
'id'
3703 property must be set
. These objects are placed
in the
3708 @item
-object memory
-backend
-file
,id
=@
var{id
},size
=@
var{size
},mem
-path
=@
var{dir
},share
=@
var{on|off
}
3710 Creates a memory file backend object
, which can be used to back
3711 the guest RAM with huge pages
. The @option
{id
} parameter is a
3712 unique ID that will be used to reference
this memory region
3713 when configuring the @option
{-numa
} argument
. The @option
{size
}
3714 option provides the size of the memory region
, and accepts
3715 common suffixes
, eg @option
{500M
}. The @option
{mem
-path
} provides
3716 the path to either a shared memory or huge page filesystem mount
.
3717 The @option
{share
} boolean option determines whether the memory
3718 region is marked as
private to QEMU
, or shared
. The latter allows
3719 a co
-operating external process to access the QEMU memory region
.
3721 @item
-object rng
-random
,id
=@
var{id
},filename
=@
var{/dev
/random
}
3723 Creates a random number generator backend which obtains entropy from
3724 a device on the host
. The @option
{id
} parameter is a unique ID that
3725 will be used to reference
this entropy backend from the @option
{virtio
-rng
}
3726 device
. The @option
{filename
} parameter specifies which file to obtain
3727 entropy from and
if omitted defaults to @option
{/dev
/random
}.
3729 @item
-object rng
-egd
,id
=@
var{id
},chardev
=@
var{chardevid
}
3731 Creates a random number generator backend which obtains entropy from
3732 an external daemon running on the host
. The @option
{id
} parameter is
3733 a unique ID that will be used to reference
this entropy backend from
3734 the @option
{virtio
-rng
} device
. The @option
{chardev
} parameter is
3735 the unique ID of a character device backend that provides the connection
3738 @item
-object tls
-creds
-anon
,id
=@
var{id
},endpoint
=@
var{endpoint
},dir
=@
var{/path
/to
/cred
/dir
},verify
-peer
=@
var{on|off
}
3740 Creates a TLS anonymous credentials object
, which can be used to provide
3741 TLS support on network backends
. The @option
{id
} parameter is a unique
3742 ID which network backends will use to access the credentials
. The
3743 @option
{endpoint
} is either @option
{server
} or @option
{client
} depending
3744 on whether the QEMU network backend that uses the credentials will be
3745 acting as a client or as a server
. If @option
{verify
-peer
} is enabled
3746 (the
default) then once the handshake is completed
, the peer credentials
3747 will be verified
, though
this is a no
-op
for anonymous credentials
.
3749 The @
var{dir
} parameter tells QEMU where to find the credential
3750 files
. For server endpoints
, this directory may contain a file
3751 @
var{dh
-params
.pem
} providing diffie
-hellman parameters to use
3752 for the TLS server
. If the file is missing
, QEMU will generate
3753 a set of DH parameters at startup
. This is a computationally
3754 expensive operation that consumes random pool entropy
, so it is
3755 recommended that a persistent set of parameters be generated
3758 @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
}
3760 Creates a TLS anonymous credentials object
, which can be used to provide
3761 TLS support on network backends
. The @option
{id
} parameter is a unique
3762 ID which network backends will use to access the credentials
. The
3763 @option
{endpoint
} is either @option
{server
} or @option
{client
} depending
3764 on whether the QEMU network backend that uses the credentials will be
3765 acting as a client or as a server
. If @option
{verify
-peer
} is enabled
3766 (the
default) then once the handshake is completed
, the peer credentials
3767 will be verified
. With x509 certificates
, this implies that the clients
3768 must be provided with valid client certificates too
.
3770 The @
var{dir
} parameter tells QEMU where to find the credential
3771 files
. For server endpoints
, this directory may contain a file
3772 @
var{dh
-params
.pem
} providing diffie
-hellman parameters to use
3773 for the TLS server
. If the file is missing
, QEMU will generate
3774 a set of DH parameters at startup
. This is a computationally
3775 expensive operation that consumes random pool entropy
, so it is
3776 recommended that a persistent set of parameters be generated
3779 For x509 certificate credentials the directory will contain further files
3780 providing the x509 certificates
. The certificates must be stored
3781 in PEM format
, in filenames @
var{ca
-cert
.pem
}, @
var{ca
-crl
.pem
} (optional
),
3782 @
var{server
-cert
.pem
} (only servers
), @
var{server
-key
.pem
} (only servers
),
3783 @
var{client
-cert
.pem
} (only clients
), and @
var{client
-key
.pem
} (only clients
).
3785 For the @
var{server
-key
.pem
} and @
var{client
-key
.pem
} files which
3786 contain sensitive
private keys
, it is possible to use an encrypted
3787 version by providing the @
var{passwordid
} parameter
. This provides
3788 the ID of a previously created @code
{secret
} object containing the
3789 password
for decryption
.
3791 @item
-object filter
-buffer
,id
=@
var{id
},netdev
=@
var{netdevid
},interval
=@
var{t
}[,queue
=@
var{all|rx|tx
}]
3793 Interval @
var{t
} can
't be 0, this filter batches the packet delivery: all
3794 packets arriving in a given interval on netdev @var{netdevid} are delayed
3795 until the end of the interval. Interval is in microseconds.
3797 queue @var{all|rx|tx} is an option that can be applied to any netfilter.
3799 @option{all}: the filter is attached both to the receive and the transmit
3800 queue of the netdev (default).
3802 @option{rx}: the filter is attached to the receive queue of the netdev,
3803 where it will receive packets sent to the netdev.
3805 @option{tx}: the filter is attached to the transmit queue of the netdev,
3806 where it will receive packets sent by the netdev.
3808 @item -object filter-dump,id=@var{id},netdev=@var{dev},file=@var{filename}][,maxlen=@var{len}]
3810 Dump the network traffic on netdev @var{dev} to the file specified by
3811 @var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
3812 The file format is libpcap, so it can be analyzed with tools such as tcpdump
3815 @item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
3816 @item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
3818 Defines a secret to store a password, encryption key, or some other sensitive
3819 data. The sensitive data can either be passed directly via the @var{data}
3820 parameter, or indirectly via the @var{file} parameter. Using the @var{data}
3821 parameter is insecure unless the sensitive data is encrypted.
3823 The sensitive data can be provided in raw format (the default), or base64.
3824 When encoded as JSON, the raw format only supports valid UTF-8 characters,
3825 so base64 is recommended for sending binary data. QEMU will convert from
3826 which ever format is provided to the format it needs internally. eg, an
3827 RBD password can be provided in raw format, even though it will be base64
3828 encoded when passed onto the RBD sever.
3830 For added protection, it is possible to encrypt the data associated with
3831 a secret using the AES-256-CBC cipher. Use of encryption is indicated
3832 by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
3833 parameter provides the ID of a previously defined secret that contains
3834 the AES-256 decryption key. This key should be 32-bytes long and be
3835 base64 encoded. The @var{iv} parameter provides the random initialization
3836 vector used for encryption of this particular secret and should be a
3837 base64 encrypted string of the 32-byte IV.
3839 The simplest (insecure) usage is to provide the secret inline
3843 # $QEMU -object secret,id=sec0,data=letmein,format=raw
3847 The simplest secure usage is to provide the secret via a file
3849 # echo -n "letmein" > mypasswd.txt
3850 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
3852 For greater security, AES-256-CBC should be used. To illustrate usage,
3853 consider the openssl command line tool which can encrypt the data. Note
3854 that when encrypting, the plaintext must be padded to the cipher block
3855 size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
3857 First a master key needs to be created in base64 encoding:
3860 # openssl rand -base64 32 > key.b64
3861 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
3864 Each secret to be encrypted needs to have a random initialization vector
3865 generated. These do not need to be kept secret
3868 # openssl rand -base64 16 > iv.b64
3869 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
3872 The secret to be defined can now be encrypted, in this case we're
3873 telling openssl to base64 encode the result
, but it could be left
3874 as raw bytes
if desired
.
3877 # SECRET
=$
(echo
-n
"letmein" |
3878 openssl enc
-aes
-256-cbc
-a
-K $KEY
-iv $IV
)
3881 When launching QEMU
, create a master secret pointing to @code
{key
.b64
}
3882 and specify that to be used to decrypt the user password
. Pass the
3883 contents of @code
{iv
.b64
} to the second secret
3887 -object secret
,id
=secmaster0
,format
=base64
,file
=key
.b64 \
3888 -object secret
,id
=sec0
,keyid
=secmaster0
,format
=base64
,\
3889 data
=$SECRET
,iv
=$
(<iv
.b64
)
3897 HXCOMM This is the last statement
. Insert
new options before
this line
!