qemu-options.hx 126 KB
Newer Older
1 2 3
HXCOMM Use DEFHEADING() to define headings in both help text and texi
HXCOMM Text between STEXI and ETEXI are copied to texi version and
HXCOMM discarded from C version
4 5 6
HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
HXCOMM construct option structures, enums and help message for specified
HXCOMM architectures.
7 8 9 10 11 12 13 14
HXCOMM HXCOMM can be used for comments, discarded from both texi and C

DEFHEADING(Standard options:)
STEXI
@table @option
ETEXI

DEF("help", 0, QEMU_OPTION_h,
15
    "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
16 17
STEXI
@item -h
18
@findex -h
19 20 21
Display help and exit
ETEXI

pbrook's avatar
pbrook committed
22
DEF("version", 0, QEMU_OPTION_version,
23
    "-version        display version information and exit\n", QEMU_ARCH_ALL)
pbrook's avatar
pbrook committed
24 25
STEXI
@item -version
26
@findex -version
pbrook's avatar
pbrook committed
27 28 29
Display version information and exit
ETEXI

30 31
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
    "-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
    "                vmport=on|off|auto controls emulation of vmport (default: auto)\n"
37
    "                kvm_shadow_mem=size of KVM shadow MMU\n"
38
    "                dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
39 40
    "                mem-merge=on|off controls memory merge support (default: on)\n"
    "                iommu=on|off controls emulated Intel IOMMU (VT-d) support (default=off)\n",
41
    QEMU_ARCH_ALL)
42
STEXI
43 44
@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
@findex -machine
45
Select the emulated machine by @var{name}. Use @code{-machine help} to list
46 47 48 49 50 51 52
available machines. Supported machine properties are:
@table @option
@item accel=@var{accels1}[:@var{accels2}[:...]]
This is used to enable an accelerator. Depending on the target architecture,
kvm, xen, or tcg can be available. By default, tcg is used. If there is more
than one accelerator specified, the next one is used if the previous one fails
to initialize.
53 54
@item kernel_irqchip=on|off
Enables in-kernel irqchip support for the chosen accelerator when available.
55 56 57 58
@item vmport=on|off|auto
Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
value based on accel. For accel=xen the default is off otherwise the default
is on.
59 60
@item kvm_shadow_mem=size
Defines the size of the KVM shadow MMU.
61 62
@item dump-guest-core=on|off
Include guest memory in a core dump. The default is on.
63 64 65 66
@item mem-merge=on|off
Enables or disables memory merge support. This feature, when supported by
the host, de-duplicates identical memory pages among VMs instances
(enabled by default).
67 68
@item iommu=on|off
Enables or disables emulated Intel IOMMU (VT-d) support. The default is off.
69
@end table
70 71
ETEXI

72 73 74
HXCOMM Deprecated by -machine
DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)

75
DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
76
    "-cpu cpu        select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
77 78
STEXI
@item -cpu @var{model}
79
@findex -cpu
80
Select CPU model (@code{-cpu help} for list and additional feature selection)
81 82 83
ETEXI

DEF("smp", HAS_ARG, QEMU_OPTION_smp,
84
    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
85 86
    "                set the number of CPUs to 'n' [default=1]\n"
    "                maxcpus= maximum number of total cpus, including\n"
87
    "                offline CPUs for hotplug, etc\n"
88 89
    "                cores= number of CPU cores on one socket\n"
    "                threads= number of threads on one CPU core\n"
90 91
    "                sockets= number of discrete sockets in the system\n",
        QEMU_ARCH_ALL)
92
STEXI
93
@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
94
@findex -smp
95 96 97
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
to 4.
98 99 100 101 102
For the PC target, the number of @var{cores} per socket, the number
of @var{threads} per cores and the total number of @var{sockets} can be
specified. Missing values will be computed. If any on the three values is
given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
specifies the maximum number of hotpluggable CPUs.
103 104
ETEXI

105
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
106 107
    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
    "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
108
STEXI
Luiz Capitulino's avatar
Luiz Capitulino committed
109
@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
110
@item -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
111
@findex -numa
112
Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
Luiz Capitulino's avatar
Luiz Capitulino committed
113 114 115 116
and @samp{cpus} are omitted, resources are split equally. Also, note
that the -@option{numa} option doesn't allocate any of the specified
resources. That is, it just assigns existing resources to NUMA nodes. This
means that one still has to use the @option{-m}, @option{-smp} options
117 118 119 120 121
to allocate RAM and VCPUs respectively, and possibly @option{-object}
to specify the memory backend for the @samp{memdev} suboption.

@samp{mem} and @samp{memdev} are mutually exclusive.  Furthermore, if one
node uses @samp{memdev}, all of them have to use it.
122 123
ETEXI

124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
    "-add-fd fd=fd,set=set[,opaque=opaque]\n"
    "                Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
STEXI
@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
@findex -add-fd

Add a file descriptor to an fd set.  Valid options are:

@table @option
@item fd=@var{fd}
This option defines the file descriptor of which a duplicate is added to fd set.
The file descriptor cannot be stdin, stdout, or stderr.
@item set=@var{set}
This option defines the ID of the fd set to add the file descriptor to.
@item opaque=@var{opaque}
This option defines a free-form string that can be used to describe @var{fd}.
@end table

You can open an image using pre-opened file descriptors from an fd set:
@example
qemu-system-i386
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
-drive file=/dev/fdset/2,index=0,media=disk
@end example
ETEXI

152 153 154
DEF("set", HAS_ARG, QEMU_OPTION_set,
    "-set group.id.arg=value\n"
    "                set <arg> parameter for item <id> of type <group>\n"
155
    "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
156
STEXI
157
@item -set @var{group}.@var{id}.@var{arg}=@var{value}
158
@findex -set
159
Set parameter @var{arg} for item @var{id} of type @var{group}\n"
160 161 162
ETEXI

DEF("global", HAS_ARG, QEMU_OPTION_global,
163
    "-global driver.prop=value\n"
164 165
    "                set a global default for a driver property\n",
    QEMU_ARCH_ALL)
166
STEXI
167
@item -global @var{driver}.@var{prop}=@var{value}
168
@findex -global
169 170 171
Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:

@example
172
qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
173 174 175 176 177
@end example

In particular, you can use this to set driver properties for devices which are 
created automatically by the machine model. To create a device which is not 
created automatically and set properties on it, use -@option{device}.
178 179
ETEXI

180
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
181
    "-boot [order=drives][,once=drives][,menu=on|off]\n"
182
    "      [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
183 184
    "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
    "                'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
185 186
    "                'sp_time': the period that splash picture last if menu=on, unit is ms\n"
    "                'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
187
    QEMU_ARCH_ALL)
188
STEXI
189
@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]
190
@findex -boot
191 192 193 194 195 196 197 198 199 200
Specify boot order @var{drives} as a string of drive letters. Valid
drive letters depend on the target achitecture. The x86 PC uses: a, b
(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
from network adapter 1-4), hard disk boot is the default. To apply a
particular boot order only on the first startup, specify it via
@option{once}.

Interactive boot menus/prompts can be enabled via @option{menu=on} as far
as firmware/BIOS supports them. The default is non-interactive boot.

201 202 203 204 205 206 207
A splash picture could be passed to bios, enabling user to show it as logo,
when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
supports them. Currently Seabios for X86 system support it.
limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
format(true color). The resolution should be supported by the SVGA mode, so
the recommended is 320x240, 640x480, 800x640.

208 209 210 211 212
A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
system support it.

213 214 215 216
Do strict boot via @option{strict=on} as far as firmware/BIOS
supports it. This only effects when boot priority is changed by
bootindex options. The default is non-strict boot.

217 218
@example
# try to boot from network first, then from hard disk
219
qemu-system-i386 -boot order=nc
220
# boot from CD-ROM first, switch back to default order after reboot
221
qemu-system-i386 -boot once=d
222
# boot with a splash picture for 5 seconds.
223
qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
224 225 226 227
@end example

Note: The legacy format '-boot @var{drives}' is still supported but its
use is discouraged as it may be removed from future versions.
228 229 230
ETEXI

DEF("m", HAS_ARG, QEMU_OPTION_m,
231
    "-m[emory] [size=]megs[,slots=n,maxmem=size]\n"
232 233
    "                configure guest RAM\n"
    "                size: initial amount of guest memory (default: "
234 235
    stringify(DEFAULT_RAM_SIZE) "MiB)\n"
    "                slots: number of hotplug slots (default: none)\n"
236 237
    "                maxmem: maximum amount of guest memory (default: none)\n"
    "NOTE: Some architectures might enforce a specific granularity\n",
238
    QEMU_ARCH_ALL)
239
STEXI
240
@item -m [size=]@var{megs}
241
@findex -m
242 243
Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
244 245
gigabytes respectively. Optional pair @var{slots}, @var{maxmem} could be used
to set amount of hotluggable memory slots and possible maximum amount of memory.
246 247
ETEXI

248
DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
249
    "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
250 251
STEXI
@item -mem-path @var{path}
252
@findex -mem-path
253 254 255 256
Allocate guest RAM from a temporarily created file in @var{path}.
ETEXI

DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
257 258
    "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
    QEMU_ARCH_ALL)
259 260
STEXI
@item -mem-prealloc
261
@findex -mem-prealloc
262 263 264
Preallocate memory when using -mem-path.
ETEXI

265
DEF("k", HAS_ARG, QEMU_OPTION_k,
266 267
    "-k language     use keyboard layout (for example 'fr' for French)\n",
    QEMU_ARCH_ALL)
268 269
STEXI
@item -k @var{language}
270
@findex -k
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
Use keyboard layout @var{language} (for example @code{fr} for
French). This option is only needed where it is not easy to get raw PC
keycodes (e.g. on Macs, with some X11 servers or with a VNC
display). You don't normally need to use it on PC/Linux or PC/Windows
hosts.

The available layouts are:
@example
ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
@end example

The default is @code{en-us}.
ETEXI


DEF("audio-help", 0, QEMU_OPTION_audio_help,
289 290
    "-audio-help     print list of audio drivers and their options\n",
    QEMU_ARCH_ALL)
291 292
STEXI
@item -audio-help
293
@findex -audio-help
294 295 296 297 298 299 300
Will show the audio subsystem help: list of drivers, tunable
parameters.
ETEXI

DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
    "-soundhw c1,... enable audio support\n"
    "                and only specified sound cards (comma separated list)\n"
301 302
    "                use '-soundhw help' to get the list of supported cards\n"
    "                use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
303 304
STEXI
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
305
@findex -soundhw
306
Enable audio and selected sound hardware. Use 'help' to print all
307 308 309
available sound hardware.

@example
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355
qemu-system-i386 -soundhw sb16,adlib disk.img
qemu-system-i386 -soundhw es1370 disk.img
qemu-system-i386 -soundhw ac97 disk.img
qemu-system-i386 -soundhw hda disk.img
qemu-system-i386 -soundhw all disk.img
qemu-system-i386 -soundhw help
@end example

Note that Linux's i810_audio OSS kernel (for AC97) module might
require manually specifying clocking.

@example
modprobe i810_audio clocking=48000
@end example
ETEXI

DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
    "-balloon none   disable balloon device\n"
    "-balloon virtio[,addr=str]\n"
    "                enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
STEXI
@item -balloon none
@findex -balloon
Disable balloon device.
@item -balloon virtio[,addr=@var{addr}]
Enable virtio balloon device (default), optionally with PCI address
@var{addr}.
ETEXI

DEF("device", HAS_ARG, QEMU_OPTION_device,
    "-device driver[,prop[=value][,...]]\n"
    "                add device (based on driver)\n"
    "                prop=value,... sets driver properties\n"
    "                use '-device help' to print all possible drivers\n"
    "                use '-device driver,help' to print all possible properties\n",
    QEMU_ARCH_ALL)
STEXI
@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
@findex -device
Add device @var{driver}.  @var{prop}=@var{value} sets driver
properties.  Valid properties depend on the driver.  To get help on
possible drivers and properties, use @code{-device help} and
@code{-device @var{driver},help}.
ETEXI

DEF("name", HAS_ARG, QEMU_OPTION_name,
356
    "-name string1[,process=string2][,debug-threads=on|off]\n"
357
    "                set the name of the guest\n"
358 359 360
    "                string1 sets the window title and string2 the process name (on Linux)\n"
    "                When debug-threads is enabled, individual threads are given a separate name (on Linux)\n"
    "                NOTE: The thread names are for debugging and not a stable API.\n",
361 362 363 364 365 366 367 368
    QEMU_ARCH_ALL)
STEXI
@item -name @var{name}
@findex -name
Sets the @var{name} of the guest.
This name will be displayed in the SDL window caption.
The @var{name} will also be used for the VNC server.
Also optionally set the top visible process name in Linux.
369
Naming of individual threads can also be enabled on Linux to aid debugging.
370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435
ETEXI

DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
    "-uuid %08x-%04x-%04x-%04x-%012x\n"
    "                specify machine UUID\n", QEMU_ARCH_ALL)
STEXI
@item -uuid @var{uuid}
@findex -uuid
Set system UUID.
ETEXI

STEXI
@end table
ETEXI
DEFHEADING()

DEFHEADING(Block device options:)
STEXI
@table @option
ETEXI

DEF("fda", HAS_ARG, QEMU_OPTION_fda,
    "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
STEXI
@item -fda @var{file}
@item -fdb @var{file}
@findex -fda
@findex -fdb
Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
ETEXI

DEF("hda", HAS_ARG, QEMU_OPTION_hda,
    "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
    "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
STEXI
@item -hda @var{file}
@item -hdb @var{file}
@item -hdc @var{file}
@item -hdd @var{file}
@findex -hda
@findex -hdb
@findex -hdc
@findex -hdd
Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
ETEXI

DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
    "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
    QEMU_ARCH_ALL)
STEXI
@item -cdrom @var{file}
@findex -cdrom
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
@option{-cdrom} at the same time). You can use the host CD-ROM by
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
ETEXI

DEF("drive", HAS_ARG, QEMU_OPTION_drive,
    "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
    "       [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
    "       [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
436 437
    "       [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
    "       [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
438
    "       [,readonly=on|off][,copy-on-read=on|off]\n"
439
    "       [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
440 441 442 443
    "       [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
    "       [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
    "       [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
    "       [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
444
    "       [[,iops_size=is]]\n"
445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473
    "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
STEXI
@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
@findex -drive

Define a new drive. Valid options are:

@table @option
@item file=@var{file}
This option defines which disk image (@pxref{disk_images}) to use with
this drive. If the filename contains comma, you must double it
(for instance, "file=my,,file" to use file "my,file").

Special files such as iSCSI devices can be specified using protocol
specific URLs. See the section for "Device URL Syntax" for more information.
@item if=@var{interface}
This option defines on which type on interface the drive is connected.
Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
@item bus=@var{bus},unit=@var{unit}
These options define where is connected the drive by defining the bus number and
the unit id.
@item index=@var{index}
This option defines where is connected the drive by using an index in the list
of available connectors of a given interface type.
@item media=@var{media}
This option defines the type of the media: disk or cdrom.
@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
These options have the same definition as they have in @option{-hdachs}.
@item snapshot=@var{snapshot}
474 475
@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
(see @option{-snapshot}).
476 477 478 479
@item cache=@var{cache}
@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data.
@item aio=@var{aio}
@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
480 481
@item discard=@var{discard}
@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.
482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
@item format=@var{format}
Specify which disk @var{format} will be used rather than detecting
the format.  Can be used to specifiy format=raw to avoid interpreting
an untrusted format header.
@item serial=@var{serial}
This option specifies the serial number to assign to the device.
@item addr=@var{addr}
Specify the controller's PCI address (if=virtio only).
@item werror=@var{action},rerror=@var{action}
Specify which @var{action} to take on write and read errors. Valid actions are:
"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
"report" (report the error to the guest), "enospc" (pause QEMU only if the
host disk is full; report the error to the guest otherwise).
The default setting is @option{werror=enospc} and @option{rerror=report}.
@item readonly
Open drive @option{file} as read-only. Guest write attempts will fail.
@item copy-on-read=@var{copy-on-read}
@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
file sectors into the image file.
501 502 503 504 505
@item detect-zeroes=@var{detect-zeroes}
@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
conversion of plain zero writes by the OS to driver specific optimized
zero write commands. You may even choose "unmap" if @var{discard} is set
to "unmap" to allow a zero write to be converted to an UNMAP operation.
506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565
@end table

By default, the @option{cache=writeback} mode is used. It will report data
writes as completed as soon as the data is present in the host page cache.
This is safe as long as your guest OS makes sure to correctly flush disk caches
where needed. If your guest OS does not handle volatile disk write caches
correctly and your host crashes or loses power, then the guest may experience
data corruption.

For such guests, you should consider using @option{cache=writethrough}. This
means that the host page cache will be used to read and write data, but write
notification will be sent to the guest only after QEMU has made sure to flush
each write to the disk. Be aware that this has a major impact on performance.

The host page cache can be avoided entirely with @option{cache=none}.  This will
attempt to do disk IO directly to the guest's memory.  QEMU may still perform
an internal copy of the data. Note that this is considered a writeback mode and
the guest OS must handle the disk write cache correctly in order to avoid data
corruption on host crashes.

The host page cache can be avoided while only sending write notifications to
the guest when the data has been flushed to the disk using
@option{cache=directsync}.

In case you don't care about data integrity over host failures, use
@option{cache=unsafe}. This option tells QEMU that it never needs to write any
data to the disk but can instead keep things in cache. If anything goes wrong,
like your host losing power, the disk storage getting disconnected accidentally,
etc. your image will most probably be rendered unusable.   When using
the @option{-snapshot} option, unsafe caching is always used.

Copy-on-read avoids accessing the same backing file sectors repeatedly and is
useful when the backing file is over a slow network.  By default copy-on-read
is off.

Instead of @option{-cdrom} you can use:
@example
qemu-system-i386 -drive file=file,index=2,media=cdrom
@end example

Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
use:
@example
qemu-system-i386 -drive file=file,index=0,media=disk
qemu-system-i386 -drive file=file,index=1,media=disk
qemu-system-i386 -drive file=file,index=2,media=disk
qemu-system-i386 -drive file=file,index=3,media=disk
@end example

You can open an image using pre-opened file descriptors from an fd set:
@example
qemu-system-i386
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
-drive file=/dev/fdset/2,index=0,media=disk
@end example

You can connect a CDROM to the slave of ide0:
@example
qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
566 567
@end example

568 569 570 571
If you don't specify the "file=" argument, you define an empty drive:
@example
qemu-system-i386 -drive if=ide,index=1,media=cdrom
@end example
572

573
You can connect a SCSI disk with unit ID 6 on the bus #0:
574
@example
575
qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6
576 577
@end example

578 579 580 581 582
Instead of @option{-fda}, @option{-fdb}, you can use:
@example
qemu-system-i386 -drive file=file,index=0,if=floppy
qemu-system-i386 -drive file=file,index=1,if=floppy
@end example
583

584 585 586 587 588 589 590 591 592
By default, @var{interface} is "ide" and @var{index} is automatically
incremented:
@example
qemu-system-i386 -drive file=a -drive file=b"
@end example
is interpreted like:
@example
qemu-system-i386 -hda a -hdb b
@end example
593 594
ETEXI

595 596
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
    "-mtdblock file  use 'file' as on-board Flash memory image\n",
597 598
    QEMU_ARCH_ALL)
STEXI
599 600 601
@item -mtdblock @var{file}
@findex -mtdblock
Use @var{file} as on-board Flash memory image.
602 603
ETEXI

604 605
DEF("sd", HAS_ARG, QEMU_OPTION_sd,
    "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
606
STEXI
607 608 609
@item -sd @var{file}
@findex -sd
Use @var{file} as SecureDigital card image.
610 611
ETEXI

612 613
DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
    "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
614
STEXI
615 616 617
@item -pflash @var{file}
@findex -pflash
Use @var{file} as a parallel flash image.
618
ETEXI
619

620 621
DEF("snapshot", 0, QEMU_OPTION_snapshot,
    "-snapshot       write to temporary files instead of disk image files\n",
622 623
    QEMU_ARCH_ALL)
STEXI
624 625 626 627 628
@item -snapshot
@findex -snapshot
Write to temporary files instead of disk image files. In this case,
the raw disk image you use is not written back. You can however force
the write back by pressing @key{C-a s} (@pxref{disk_images}).
629 630
ETEXI

631 632 633 634
DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
    "-hdachs c,h,s[,t]\n" \
    "                force hard disk 0 physical geometry and the optional BIOS\n" \
    "                translation (t=none or lba) (usually QEMU can guess them)\n",
635
    QEMU_ARCH_ALL)
636
STEXI
637 638 639 640 641 642 643
@item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
@findex -hdachs
Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
all those parameters. This option is useful for old MS-DOS disk
images.
644
ETEXI
645 646

DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
647
    "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
648
    " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
649 650 651 652
    QEMU_ARCH_ALL)

STEXI

653
@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}]
654
@findex -fsdev
655 656 657 658
Define a new file system device. Valid options are:
@table @option
@item @var{fsdriver}
This option specifies the fs driver backend to use.
659
Currently "local", "handle" and "proxy" file system drivers are supported.
660 661 662 663 664 665 666
@item id=@var{id}
Specifies identifier for this device
@item path=@var{path}
Specifies the export path for the file system device. Files under
this path will be available to the 9p client on the guest.
@item security_model=@var{security_model}
Specifies the security model to be used for this export path.
667
Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
668
In "passthrough" security model, files are stored using the same
669
credentials as they are created on the guest. This requires QEMU
670
to run as root. In "mapped-xattr" security model, some of the file
671
attributes like uid, gid, mode bits and link target are stored as
672 673
file attributes. For "mapped-file" these attributes are stored in the
hidden .virtfs_metadata directory. Directories exported by this security model cannot
674 675
interact with other unix tools. "none" security model is same as
passthrough except the sever won't report failures if it fails to
676
set file attributes like ownership. Security model is mandatory
677
only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
678
security model as a parameter.
679 680 681 682 683
@item writeout=@var{writeout}
This is an optional argument. The only supported value is "immediate".
This means that host page cache will be used to read and write data but
write notification will be sent to the guest only when the data has been
reported as written by the storage subsystem.
684 685 686
@item readonly
Enables exporting 9p share as a readonly mount for guests. By default
read-write access is given.
687 688 689
@item socket=@var{socket}
Enables proxy filesystem driver to use passed socket file for communicating
with virtfs-proxy-helper
690 691 692 693
@item sock_fd=@var{sock_fd}
Enables proxy filesystem driver to use passed socket descriptor for
communicating with virtfs-proxy-helper. Usually a helper like libvirt
will create socketpair and pass one of the fds as sock_fd
694
@end table
695

696 697 698 699 700 701 702 703
-fsdev option is used along with -device driver "virtio-9p-pci".
@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
Options for virtio-9p-pci driver are:
@table @option
@item fsdev=@var{id}
Specifies the id value specified along with -fsdev option
@item mount_tag=@var{mount_tag}
Specifies the tag name to be used by the guest to mount this export point
704
@end table
705

706 707
ETEXI

708
DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
709
    "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
710
    "        [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
711 712 713 714
    QEMU_ARCH_ALL)

STEXI

715
@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}]
716 717
@findex -virtfs

718 719 720 721
The general form of a Virtual File system pass-through options are:
@table @option
@item @var{fsdriver}
This option specifies the fs driver backend to use.
722
Currently "local", "handle" and "proxy" file system drivers are supported.
723 724 725 726 727 728 729
@item id=@var{id}
Specifies identifier for this device
@item path=@var{path}
Specifies the export path for the file system device. Files under
this path will be available to the 9p client on the guest.
@item security_model=@var{security_model}
Specifies the security model to be used for this export path.
730
Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
731
In "passthrough" security model, files are stored using the same
732
credentials as they are created on the guest. This requires QEMU
733
to run as root. In "mapped-xattr" security model, some of the file
734
attributes like uid, gid, mode bits and link target are stored as
735 736
file attributes. For "mapped-file" these attributes are stored in the
hidden .virtfs_metadata directory. Directories exported by this security model cannot
737 738
interact with other unix tools. "none" security model is same as
passthrough except the sever won't report failures if it fails to
739
set file attributes like ownership. Security model is mandatory only
740
for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
741
model as a parameter.
742 743 744 745 746
@item writeout=@var{writeout}
This is an optional argument. The only supported value is "immediate".
This means that host page cache will be used to read and write data but
write notification will be sent to the guest only when the data has been
reported as written by the storage subsystem.
747 748 749
@item readonly
Enables exporting 9p share as a readonly mount for guests. By default
read-write access is given.
750 751 752 753
@item socket=@var{socket}
Enables proxy filesystem driver to use passed socket file for
communicating with virtfs-proxy-helper. Usually a helper like libvirt
will create socketpair and pass one of the fds as sock_fd
754 755 756
@item sock_fd
Enables proxy filesystem driver to use passed 'sock_fd' as the socket
descriptor for interfacing with virtfs-proxy-helper
757 758 759
@end table
ETEXI

760 761 762 763 764 765 766 767 768
DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
    "-virtfs_synth Create synthetic file system image\n",
    QEMU_ARCH_ALL)
STEXI
@item -virtfs_synth
@findex -virtfs_synth
Create synthetic file system image
ETEXI

769 770 771 772 773
STEXI
@end table
ETEXI
DEFHEADING()

774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837
DEFHEADING(USB options:)
STEXI
@table @option
ETEXI

DEF("usb", 0, QEMU_OPTION_usb,
    "-usb            enable the USB driver (will be the default soon)\n",
    QEMU_ARCH_ALL)
STEXI
@item -usb
@findex -usb
Enable the USB driver (will be the default soon)
ETEXI

DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
    "-usbdevice name add the host or guest USB device 'name'\n",
    QEMU_ARCH_ALL)
STEXI

@item -usbdevice @var{devname}
@findex -usbdevice
Add the USB device @var{devname}. @xref{usb_devices}.

@table @option

@item mouse
Virtual Mouse. This will override the PS/2 mouse emulation when activated.

@item tablet
Pointer device that uses absolute coordinates (like a touchscreen). This
means QEMU is able to report the mouse position without having to grab the
mouse. Also overrides the PS/2 mouse emulation when activated.

@item disk:[format=@var{format}]:@var{file}
Mass storage device based on file. The optional @var{format} argument
will be used rather than detecting the format. Can be used to specifiy
@code{format=raw} to avoid interpreting an untrusted format header.

@item host:@var{bus}.@var{addr}
Pass through the host device identified by @var{bus}.@var{addr} (Linux only).

@item host:@var{vendor_id}:@var{product_id}
Pass through the host device identified by @var{vendor_id}:@var{product_id}
(Linux only).

@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
Serial converter to host character device @var{dev}, see @code{-serial} for the
available devices.

@item braille
Braille device.  This will use BrlAPI to display the braille output on a real
or fake device.

@item net:@var{options}
Network adapter that supports CDC ethernet and RNDIS protocols.

@end table
ETEXI

STEXI
@end table
ETEXI
DEFHEADING()

838 839 840 841 842
DEFHEADING(Display options:)
STEXI
@table @option
ETEXI

843 844
DEF("display", HAS_ARG, QEMU_OPTION_display,
    "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
845
    "            [,window_close=on|off]|curses|none|\n"
846
    "            gtk[,grab_on_hover=on|off]|\n"
847
    "            vnc=<display>[,<optargs>]\n"
848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863
    "                select display type\n", QEMU_ARCH_ALL)
STEXI
@item -display @var{type}
@findex -display
Select type of display to use. This option is a replacement for the
old style -sdl/-curses/... options. Valid values for @var{type} are
@table @option
@item sdl
Display video output via SDL (usually in a separate graphics
window; see the SDL documentation for other possibilities).
@item curses
Display video output via curses. For graphics device models which
support a text mode, QEMU can display this output using a
curses/ncurses interface. Nothing is displayed when the graphics
device is in graphical mode or if the graphics device does not support
a text mode. Generally only the VGA device models support text mode.
Jes Sorensen's avatar
Jes Sorensen committed
864 865 866 867 868 869
@item none
Do not display video output. The guest will still see an emulated
graphics card, but its output will not be displayed to the QEMU
user. This option differs from the -nographic option in that it
only affects what is done with video output; -nographic also changes
the destination of the serial and parallel port data.
870 871 872 873
@item gtk
Display video output in a GTK window. This interface provides drop-down
menus and other UI elements to configure and control the VM during
runtime.
874 875
@item vnc
Start a VNC server on display <arg>
876 877 878
@end table
ETEXI

879
DEF("nographic", 0, QEMU_OPTION_nographic,
880 881
    "-nographic      disable graphical output and redirect serial I/Os to console\n",
    QEMU_ARCH_ALL)
882 883
STEXI
@item -nographic
884
@findex -nographic
885 886 887
Normally, QEMU uses SDL to display the VGA output. With this option,
you can totally disable graphical output so that QEMU is a simple
command line application. The emulated serial port is redirected on
888 889
the console and muxed with the monitor (unless redirected elsewhere
explicitly). Therefore, you can still use QEMU to debug a Linux kernel
890 891
with a serial console.  Use @key{C-a h} for help on switching between
the console and monitor.
892 893 894
ETEXI

DEF("curses", 0, QEMU_OPTION_curses,
895 896
    "-curses         use a curses/ncurses interface instead of SDL\n",
    QEMU_ARCH_ALL)
897 898
STEXI
@item -curses
899
@findex -curses
900 901 902 903 904 905
Normally, QEMU uses SDL to display the VGA output.  With this option,
QEMU can display the VGA output when in text mode using a
curses/ncurses interface.  Nothing is displayed in graphical mode.
ETEXI

DEF("no-frame", 0, QEMU_OPTION_no_frame,
906 907
    "-no-frame       open SDL window without a frame and window decorations\n",
    QEMU_ARCH_ALL)
908 909
STEXI
@item -no-frame
910
@findex -no-frame
911 912 913 914 915 916
Do not use decorations for SDL windows and start them using the whole
available screen space. This makes the using QEMU in a dedicated desktop
workspace more convenient.
ETEXI

DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
917 918
    "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
    QEMU_ARCH_ALL)
919 920
STEXI
@item -alt-grab
921
@findex -alt-grab
922 923
Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
affects the special keys (for fullscreen, monitor-mode switching, etc).
924 925
ETEXI

926
DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
927 928
    "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
    QEMU_ARCH_ALL)
929 930
STEXI
@item -ctrl-grab
931
@findex -ctrl-grab
932 933
Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
affects the special keys (for fullscreen, monitor-mode switching, etc).
934 935
ETEXI

936
DEF("no-quit", 0, QEMU_OPTION_no_quit,
937
    "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
938 939
STEXI
@item -no-quit
940
@findex -no-quit
941 942 943 944
Disable SDL window close capability.
ETEXI

DEF("sdl", 0, QEMU_OPTION_sdl,
945
    "-sdl            enable SDL\n", QEMU_ARCH_ALL)
946 947
STEXI
@item -sdl
948
@findex -sdl
949 950 951
Enable SDL.
ETEXI

Gerd Hoffmann's avatar
Gerd Hoffmann committed
952
DEF("spice", HAS_ARG, QEMU_OPTION_spice,
953 954 955 956 957 958 959 960 961 962 963 964
    "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
    "       [,x509-key-file=<file>][,x509-key-password=<file>]\n"
    "       [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
    "       [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6]\n"
    "       [,tls-ciphers=<list>]\n"
    "       [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
    "       [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
    "       [,sasl][,password=<secret>][,disable-ticketing]\n"
    "       [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
    "       [,jpeg-wan-compression=[auto|never|always]]\n"
    "       [,zlib-glz-wan-compression=[auto|never|always]]\n"
    "       [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
965 966
    "       [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
    "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
967 968 969
    "   enable spice\n"
    "   at least one of {port, tls-port} is mandatory\n",
    QEMU_ARCH_ALL)
Gerd Hoffmann's avatar
Gerd Hoffmann committed
970 971 972 973 974 975 976 977
STEXI
@item -spice @var{option}[,@var{option}[,...]]
@findex -spice
Enable the spice remote desktop protocol. Valid options are

@table @option

@item port=<nr>
Gerd Hoffmann's avatar
Gerd Hoffmann committed
978
Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann's avatar
Gerd Hoffmann committed
979

980 981 982 983 984 985 986
@item addr=<addr>
Set the IP address spice is listening on.  Default is any address.

@item ipv4
@item ipv6
Force using the specified IP version.

Gerd Hoffmann's avatar
Gerd Hoffmann committed
987 988 989
@item password=<secret>
Set the password you need to authenticate.

990 991 992 993 994 995 996 997 998 999 1000 1001 1002
@item sasl
Require that the client use SASL to authenticate with the spice.
The exact choice of authentication method used is controlled from the
system / user's SASL configuration file for the 'qemu' service. This
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
unprivileged user, an environment variable SASL_CONF_PATH can be used
to make it search alternate locations for the service config.
While some SASL auth methods can also provide data encryption (eg GSSAPI),
it is recommended that SASL always be combined with the 'tls' and
'x509' settings to enable use of SSL and server certificates. This
ensures a data encryption preventing compromise of authentication
credentials.

Gerd Hoffmann's avatar
Gerd Hoffmann committed
1003 1004 1005
@item disable-ticketing
Allow client connects without authentication.

1006 1007 1008
@item disable-copy-paste
Disable copy paste between the client and the guest.

1009 1010 1011
@item disable-agent-file-xfer
Disable spice-vdagent based file-xfer between the client and the guest.

Gerd Hoffmann's avatar
Gerd Hoffmann committed
1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027
@item tls-port=<nr>
Set the TCP port spice is listening on for encrypted channels.

@item x509-dir=<dir>
Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir

@item x509-key-file=<file>
@item x509-key-password=<file>
@item x509-cert-file=<file>
@item x509-cacert-file=<file>
@item x509-dh-key-file=<file>
The x509 file names can also be configured individually.

@item tls-ciphers=<list>
Specify which ciphers to use.

1028 1029
@item tls-channel=[main|display|cursor|inputs|record|playback]
@item plaintext-channel=[main|display|cursor|inputs|record|playback]
1030 1031 1032 1033 1034 1035
Force specific channel to be used with or without TLS encryption.  The
options can be specified multiple times to configure multiple
channels.  The special name "default" can be used to set the default
mode.  For channels which are not explicitly forced into one mode the
spice client is allowed to pick tls/plaintext as he pleases.

1036 1037 1038 1039 1040 1041 1042 1043 1044
@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
Configure image compression (lossless).
Default is auto_glz.

@item jpeg-wan-compression=[auto|never|always]
@item zlib-glz-wan-compression=[auto|never|always]
Configure wan image compression (lossy for slow links).
Default is auto.

1045 1046 1047 1048 1049 1050 1051 1052 1053
@item streaming-video=[off|all|filter]
Configure video stream detection.  Default is filter.

@item agent-mouse=[on|off]
Enable/disable passing mouse events via vdagent.  Default is on.

@item playback-compression=[on|off]
Enable/disable audio stream compression (using celt 0.5.1).  Default is on.

1054 1055 1056
@item seamless-migration=[on|off]
Enable/disable spice seamless migration. Default is off.

Gerd Hoffmann's avatar
Gerd Hoffmann committed
1057 1058 1059
@end table
ETEXI

1060
DEF("portrait", 0, QEMU_OPTION_portrait,
1061 1062
    "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
    QEMU_ARCH_ALL)
1063 1064
STEXI
@item -portrait
1065
@findex -portrait
1066 1067 1068
Rotate graphical output 90 deg left (only PXA LCD).
ETEXI

1069 1070 1071 1072
DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
    "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
    QEMU_ARCH_ALL)
STEXI
1073
@item -rotate @var{deg}
1074 1075 1076 1077
@findex -rotate
Rotate graphical output some deg left (only PXA LCD).
ETEXI

1078
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
1079
    "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|none]\n"
1080
    "                select video card type\n", QEMU_ARCH_ALL)
1081
STEXI
1082
@item -vga @var{type}
1083
@findex -vga
1084
Select type of VGA card to emulate. Valid values for @var{type} are
1085
@table @option
1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099
@item cirrus
Cirrus Logic GD5446 Video card. All Windows versions starting from
Windows 95 should recognize and use this graphic card. For optimal
performances, use 16 bit color depth in the guest and the host OS.
(This one is the default)
@item std
Standard VGA card with Bochs VBE extensions.  If your guest OS
supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
to use high resolution modes (>= 1280x1024x16) then you should use
this option.
@item vmware
VMWare SVGA-II compatible adapter. Use it if you have sufficiently
recent XFree86/XOrg server or Windows guest with a driver for this
card.
Gerd Hoffmann's avatar
Gerd Hoffmann committed
1100 1101 1102 1103
@item qxl
QXL paravirtual graphic card.  It is VGA compatible (including VESA
2.0 VBE support).  Works best with qxl guest drivers installed though.
Recommended choice when using the spice protocol.
1104 1105 1106 1107 1108 1109 1110 1111
@item tcx
(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
sun4m machines and offers both 8-bit and 24-bit colour depths at a
fixed resolution of 1024x768.
@item cg3
(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
resolutions aimed at people wishing to run older Solaris versions.
1112 1113 1114 1115 1116 1117
@item none
Disable VGA card.
@end table
ETEXI

DEF("full-screen", 0, QEMU_OPTION_full_screen,
1118
    "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
1119 1120
STEXI
@item -full-screen
1121
@findex -full-screen
1122 1123 1124 1125
Start in full screen.
ETEXI

DEF("g", 1, QEMU_OPTION_g ,
1126 1127
    "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
    QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
1128
STEXI
1129
@item -g @var{width}x@var{height}[x@var{depth}]
1130
@findex -g
1131
Set the initial graphical resolution and depth (PPC, SPARC only).
1132 1133 1134
ETEXI

DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1135
    "-vnc display    start a VNC server on display\n", QEMU_ARCH_ALL)
1136 1137
STEXI
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1138
@findex -vnc
1139 1140 1141 1142 1143 1144 1145 1146
Normally, QEMU uses SDL to display the VGA output.  With this option,
you can have QEMU listen on VNC display @var{display} and redirect the VGA
display over the VNC session.  It is very useful to enable the usb
tablet device when using this option (option @option{-usbdevice
tablet}). When using the VNC display, you must use the @option{-k}
parameter to set the keyboard layout if you are not using en-us. Valid
syntax for the @var{display} is

1147
@table @option
1148 1149 1150 1151 1152 1153 1154

@item @var{host}:@var{d}

TCP connections will only be allowed from @var{host} on display @var{d}.
By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
be omitted in which case the server will accept connections from any host.

1155
@item unix:@var{path}
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169

Connections will be allowed over UNIX domain sockets where @var{path} is the
location of a unix socket to listen for connections on.

@item none

VNC is initialized but not started. The monitor @code{change} command
can be used to later start the VNC server.

@end table

Following the @var{display} value there may be one or more @var{option} flags
separated by commas. Valid options are

1170
@table @option
1171 1172 1173 1174 1175 1176 1177 1178

@item reverse

Connect to a listening VNC client via a ``reverse'' connection. The
client is specified by the @var{display}. For reverse network
connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
is a TCP port number, not a display number.

1179 1180 1181
@item websocket

Opens an additional TCP listening port dedicated to VNC Websocket connections.
1182
By definition the Websocket port is 5700+@var{display}. If @var{host} is
1183 1184 1185
specified connections will only be allowed from this host.
As an alternative the Websocket port could be specified by using
@code{websocket}=@var{port}.
1186 1187
TLS encryption for the Websocket connection is supported if the required
certificates are specified with the VNC option @option{x509}.
1188

1189 1190 1191
@item password

Require that password based authentication is used for client connections.
1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206

The password must be set separately using the @code{set_password} command in
the @ref{pcsys_monitor}. The syntax to change your password is:
@code{set_password <protocol> <password>} where <protocol> could be either
"vnc" or "spice".

If you would like to change <protocol> password expiration, you should use
@code{expire_password <protocol> <expiration-time>} where expiration time could
be one of the following options: now, never, +seconds or UNIX time of
expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
date and time).

You can also use keywords "now" or "never" for the expiration time to
allow <protocol> password to expire immediately or never expire.
1207 1208 1209 1210 1211 1212

@item tls

Require that client use TLS when communicating with the VNC server. This
uses anonymous TLS credentials so is susceptible to a man-in-the-middle
attack. It is recommended that this option be combined with either the
1213
@option{x509} or @option{x509verify} options.
1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264

@item x509=@var{/path/to/certificate/dir}

Valid if @option{tls} is specified. Require that x509 credentials are used
for negotiating the TLS session. The server will send its x509 certificate
to the client. It is recommended that a password be set on the VNC server
to provide authentication of the client when this is used. The path following
this option specifies where the x509 certificates are to be loaded from.
See the @ref{vnc_security} section for details on generating certificates.

@item x509verify=@var{/path/to/certificate/dir}

Valid if @option{tls} is specified. Require that x509 credentials are used
for negotiating the TLS session. The server will send its x509 certificate
to the client, and request that the client send its own x509 certificate.
The server will validate the client's certificate against the CA certificate,
and reject clients when validation fails. If the certificate authority is
trusted, this is a sufficient authentication mechanism. You may still wish
to set a password on the VNC server as a second authentication layer. The
path following this option specifies where the x509 certificates are to
be loaded from. See the @ref{vnc_security} section for details on generating
certificates.

@item sasl

Require that the client use SASL to authenticate with the VNC server.
The exact choice of authentication method used is controlled from the
system / user's SASL configuration file for the 'qemu' service. This
is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
unprivileged user, an environment variable SASL_CONF_PATH can be used
to make it search alternate locations for the service config.
While some SASL auth methods can also provide data encryption (eg GSSAPI),
it is recommended that SASL always be combined with the 'tls' and
'x509' settings to enable use of SSL and server certificates. This
ensures a data encryption preventing compromise of authentication
credentials. See the @ref{vnc_security} section for details on using
SASL authentication.

@item acl

Turn on access control lists for checking of the x509 client certificate
and SASL party. For x509 certs, the ACL check is made against the
certificate's distinguished name. This is something that looks like
@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
made against the username, which depending on the SASL plugin, may
include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
When the @option{acl} flag is set, the initial access list will be
empty, with a @code{deny} policy. Thus no one will be allowed to
use the VNC server until the ACLs have been loaded. This can be
achieved using the @code{acl} monitor command.

Corentin Chary's avatar
Corentin Chary committed
1265 1266 1267 1268 1269 1270 1271
@item lossy

Enable lossy compression methods (gradient, JPEG, ...). If this
option is set, VNC client may receive lossy framebuffer updates
depending on its encoding settings. Enabling this option can save
a lot of bandwidth at the expense of quality.

1272 1273 1274 1275 1276
@item non-adaptive

Disable adaptive encodings. Adaptive encodings are enabled by default.
An adaptive encoding will try to detect frequently updated screen regions,
and send updates in these regions using a lossy encoding (like JPEG).
1277
This can be really helpful to save bandwidth when playing videos. Disabling
1278
adaptive encodings restores the original static behavior of encodings
1279 1280
like Tight.

1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291
@item share=[allow-exclusive|force-shared|ignore]

Set display sharing policy.  'allow-exclusive' allows clients to ask
for exclusive access.  As suggested by the rfb spec this is
implemented by dropping other connections.  Connecting multiple
clients in parallel requires all clients asking for a shared session
(vncviewer: -shared switch).  This is the default.  'force-shared'
disables exclusive client access.  Useful for shared desktop sessions,
where you don't want someone forgetting specify -shared disconnect
everybody else.  'ignore' completely ignores the shared flag and
allows everybody connect unconditionally.  Doesn't conform to the rfb
1292
spec but is traditional QEMU behavior.
1293

1294 1295 1296 1297 1298 1299
@end table
ETEXI

STEXI
@end table
ETEXI
1300
ARCHHEADING(, QEMU_ARCH_I386)
1301

1302
ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1303 1304 1305 1306 1307
STEXI
@table @option
ETEXI

DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1308 1309
    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
    QEMU_ARCH_I386)
1310 1311
STEXI
@item -win2k-hack
1312
@findex -win2k-hack
1313 1314 1315 1316 1317
Use it when installing Windows 2000 to avoid a disk full bug. After
Windows 2000 is installed, you no longer need this option (this option
slows down the IDE transfers).
ETEXI

1318
HXCOMM Deprecated by -rtc
1319
DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1320 1321

DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1322 1323
    "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
    QEMU_ARCH_I386)
1324 1325
STEXI
@item -no-fd-bootchk
1326
@findex -no-fd-bootchk
1327
Disable boot signature checking for floppy disks in BIOS. May
1328 1329 1330 1331
be needed to boot from old floppy disks.
ETEXI

DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1332
           "-no-acpi        disable ACPI\n", QEMU_ARCH_I386)
1333 1334
STEXI
@item -no-acpi
1335
@findex -no-acpi
1336 1337 1338 1339 1340 1341
Disable ACPI (Advanced Configuration and Power Interface) support. Use
it if your guest OS complains about ACPI problems (PC target machine
only).
ETEXI

DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1342
    "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
1343 1344
STEXI
@item -no-hpet
1345
@findex -no-hpet
1346 1347 1348 1349
Disable HPET support.
ETEXI

DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1350
    "-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"
1351
    "                ACPI table description\n", QEMU_ARCH_I386)
1352 1353
STEXI
@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}]...]
1354
@findex -acpitable
1355
Add ACPI table with specified header fields and context from specified files.
1356 1357 1358 1359 1360
For file=, take whole ACPI table from the specified files, including all
ACPI headers (possible overridden by other options).
For data=, only data
portion of the table is used, all header information is specified in the
command line.
1361 1362
ETEXI

1363 1364
DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
    "-smbios file=binary\n"
1365
    "                load SMBIOS entry from binary file\n"
1366
    "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]\n"
1367
    "                specify SMBIOS type 0 fields\n"
1368 1369
    "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
    "              [,uuid=uuid][,sku=str][,family=str]\n"
1370
    "                specify SMBIOS type 1 fields\n", QEMU_ARCH_I386)
1371 1372
STEXI
@item -smbios file=@var{binary}
1373
@findex -smbios
1374 1375
Load SMBIOS entry from binary file.

1376
@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
1377 1378
Specify SMBIOS type 0 fields

Blue Swirl's avatar
Blue Swirl committed
1379
@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}]
1380 1381 1382
Specify SMBIOS type 1 fields
ETEXI

1383 1384 1385
STEXI
@end table
ETEXI
1386
DEFHEADING()
1387 1388 1389 1390 1391 1392

DEFHEADING(Network options:)
STEXI
@table @option
ETEXI

1393 1394
HXCOMM Legacy slirp options (now moved to -net user):
#ifdef CONFIG_SLIRP
1395 1396 1397
DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1398
#ifndef _WIN32
1399
DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1400 1401 1402
#endif
#endif

Blue Swirl's avatar
Blue Swirl committed
1403
DEF("net", HAS_ARG, QEMU_OPTION_net,
1404
    "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1405 1406
    "                create a new Network Interface Card and connect it to VLAN 'n'\n"
#ifdef CONFIG_SLIRP
1407
    "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
1408 1409
    "         [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n"
    "         [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
1410
#ifndef _WIN32
1411
                                             "[,smb=dir[,smbserver=addr]]\n"
1412 1413 1414
#endif
    "                connect the user mode network stack to VLAN 'n', configure its\n"
    "                DHCP server and enabled optional services\n"
1415 1416 1417 1418 1419
#endif
#ifdef _WIN32
    "-net tap[,vlan=n][,name=str],ifname=name\n"
    "                connect the host TAP network interface to VLAN 'n'\n"
#else
1420
    "-net tap[,vlan=n][,name=str][,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
1421
    "                connect the host TAP network interface to VLAN 'n'\n"
1422 1423 1424
    "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
    "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
    "                to deconfigure it\n"
1425
    "                use '[down]script=no' to disable script execution\n"
1426 1427
    "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
    "                configure it\n"
1428
    "                use 'fd=h' to connect to an already opened TAP interface\n"
1429
    "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
1430
    "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1431
    "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1432 1433
    "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
    "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1434
    "                use vhost=on to enable experimental in kernel accelerator\n"
1435 1436
    "                    (only has effect for virtio guests which use MSIX)\n"
    "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1437
    "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
1438
    "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
1439
    "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
1440 1441 1442 1443
    "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
    "                connects a host TAP network interface to a host bridge device 'br'\n"
    "                (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
    "                (default=" DEFAULT_BRIDGE_HELPER ")\n"
Anton Ivanov's avatar
Anton Ivanov committed
1444 1445 1446 1447 1448
#endif
#ifdef __linux__
    "-net l2tpv3[,vlan=n][,name=str],src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6=on/off][,udp=on/off][,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]\n"
    "                connect the VLAN to an Ethernet over L2TPv3 pseudowire\n"
    "                Linux kernel 3.3+ as well as most routers can talk\n"
1449
    "                L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov's avatar
Anton Ivanov committed
1450 1451 1452 1453 1454 1455
    "                VM to a router and even VM to Host. It is a nearly-universal\n"
    "                standard (RFC3391). Note - this implementation uses static\n"
    "                pre-configured tunnels (same as the Linux kernel).\n"
    "                use 'src=' to specify source address\n"
    "                use 'dst=' to specify destination address\n"
    "                use 'udp=on' to specify udp encapsulation\n"
1456
    "                use 'srcport=' to specify source udp port\n"
Anton Ivanov's avatar
Anton Ivanov committed
1457 1458 1459 1460 1461 1462 1463 1464 1465 1466
    "                use 'dstport=' to specify destination udp port\n"
    "                use 'ipv6=on' to force v6\n"
    "                L2TPv3 uses cookies to prevent misconfiguration as\n"
    "                well as a weak security measure\n"
    "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
    "                use 'txcookie=0x012345678' to specify a txcookie\n"
    "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
    "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
    "                use 'pincounter=on' to work around broken counter handling in peer\n"
    "                use 'offset=X' to add an extra offset between header and data\n"
1467 1468 1469
#endif
    "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
    "                connect the vlan 'n' to another VLAN using a socket connection\n"
1470
    "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1471
    "                connect the vlan 'n' to multicast maddr and port\n"
1472
    "                use 'localaddr=addr' to specify the host address to send packets from\n"
1473 1474
    "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
    "                connect the vlan 'n' to another VLAN using an UDP tunnel\n"
1475 1476 1477