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 controls emulation of vmport (default: on)\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
@item vmport=on|off
Enables emulation of VMWare IO port, for vmmouse etc. (enabled by default)
57 58
@item kvm_shadow_mem=size
Defines the size of the KVM shadow MMU.
59 60
@item dump-guest-core=on|off
Include guest memory in a core dump. The default is on.
61 62 63 64
@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).
65 66
@item iommu=on|off
Enables or disables emulated Intel IOMMU (VT-d) support. The default is off.
67
@end table
68 69
ETEXI

70 71 72
HXCOMM Deprecated by -machine
DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)

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

DEF("smp", HAS_ARG, QEMU_OPTION_smp,
82
    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
83 84
    "                set the number of CPUs to 'n' [default=1]\n"
    "                maxcpus= maximum number of total cpus, including\n"
85
    "                offline CPUs for hotplug, etc\n"
86 87
    "                cores= number of CPU cores on one socket\n"
    "                threads= number of threads on one CPU core\n"
88 89
    "                sockets= number of discrete sockets in the system\n",
        QEMU_ARCH_ALL)
90
STEXI
91
@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
92
@findex -smp
93 94 95
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.
96 97 98 99 100
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.
101 102
ETEXI

103
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
104 105
    "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
    "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
106
STEXI
Luiz Capitulino's avatar
Luiz Capitulino committed
107
@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
108
@item -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
109
@findex -numa
110
Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev}
Luiz Capitulino's avatar
Luiz Capitulino committed
111 112 113 114
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
115 116 117 118 119
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.
120 121
ETEXI

122 123 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
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

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

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

@example
170
qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
171 172 173 174 175
@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}.
176 177
ETEXI

178
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
179
    "-boot [order=drives][,once=drives][,menu=on|off]\n"
180
    "      [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
181 182
    "                '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"
183 184
    "                '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",
185
    QEMU_ARCH_ALL)
186
STEXI
187
@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]
188
@findex -boot
189 190 191 192 193 194 195 196 197 198
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.

199 200 201 202 203 204 205
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.

206 207 208 209 210
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.

211 212 213 214
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.

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

DEF("m", HAS_ARG, QEMU_OPTION_m,
229
    "-m[emory] [size=]megs[,slots=n,maxmem=size]\n"
230 231
    "                configure guest RAM\n"
    "                size: initial amount of guest memory (default: "
232 233
    stringify(DEFAULT_RAM_SIZE) "MiB)\n"
    "                slots: number of hotplug slots (default: none)\n"
234 235
    "                maxmem: maximum amount of guest memory (default: none)\n"
    "NOTE: Some architectures might enforce a specific granularity\n",
236
    QEMU_ARCH_ALL)
237
STEXI
238
@item -m [size=]@var{megs}
239
@findex -m
240 241
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
242 243
gigabytes respectively. Optional pair @var{slots}, @var{maxmem} could be used
to set amount of hotluggable memory slots and possible maximum amount of memory.
244 245
ETEXI

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

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

263
DEF("k", HAS_ARG, QEMU_OPTION_k,
264 265
    "-k language     use keyboard layout (for example 'fr' for French)\n",
    QEMU_ARCH_ALL)
266 267
STEXI
@item -k @var{language}
268
@findex -k
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
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,
287 288
    "-audio-help     print list of audio drivers and their options\n",
    QEMU_ARCH_ALL)
289 290
STEXI
@item -audio-help
291
@findex -audio-help
292 293 294 295 296 297 298
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"
299 300
    "                use '-soundhw help' to get the list of supported cards\n"
    "                use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
301 302
STEXI
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
303
@findex -soundhw
304
Enable audio and selected sound hardware. Use 'help' to print all
305 306 307
available sound hardware.

@example
308 309 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
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,
354
    "-name string1[,process=string2][,debug-threads=on|off]\n"
355
    "                set the name of the guest\n"
356 357 358
    "                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",
359 360 361 362 363 364 365 366
    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.
367
Naming of individual threads can also be enabled on Linux to aid debugging.
368 369 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
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"
434 435
    "       [,serial=s][,addr=A][,rerror=ignore|stop|report]\n"
    "       [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
436
    "       [,readonly=on|off][,copy-on-read=on|off]\n"
437
    "       [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
438 439 440 441
    "       [[,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"
442
    "       [[,iops_size=is]]\n"
443 444 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
    "                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}
472 473
@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
(see @option{-snapshot}).
474 475 476 477
@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.
478 479
@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.
480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498
@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.
499 500 501 502 503
@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.
504 505 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
@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
564 565
@end example

566 567 568 569
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
570

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

576 577 578 579 580
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
581

582 583 584 585 586 587 588 589 590
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
591 592
ETEXI

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

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

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

618 619
DEF("snapshot", 0, QEMU_OPTION_snapshot,
    "-snapshot       write to temporary files instead of disk image files\n",
620 621
    QEMU_ARCH_ALL)
STEXI
622 623 624 625 626
@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}).
627 628
ETEXI

629 630 631 632
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",
633
    QEMU_ARCH_ALL)
634
STEXI
635 636 637 638 639 640 641
@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.
642
ETEXI
643 644

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

STEXI

651
@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}]
652
@findex -fsdev
653 654 655 656
Define a new file system device. Valid options are:
@table @option
@item @var{fsdriver}
This option specifies the fs driver backend to use.
657
Currently "local", "handle" and "proxy" file system drivers are supported.
658 659 660 661 662 663 664
@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.
665
Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
666
In "passthrough" security model, files are stored using the same
667
credentials as they are created on the guest. This requires QEMU
668
to run as root. In "mapped-xattr" security model, some of the file
669
attributes like uid, gid, mode bits and link target are stored as
670 671
file attributes. For "mapped-file" these attributes are stored in the
hidden .virtfs_metadata directory. Directories exported by this security model cannot
672 673
interact with other unix tools. "none" security model is same as
passthrough except the sever won't report failures if it fails to
674
set file attributes like ownership. Security model is mandatory
675
only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
676
security model as a parameter.
677 678 679 680 681
@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.
682 683 684
@item readonly
Enables exporting 9p share as a readonly mount for guests. By default
read-write access is given.
685 686 687
@item socket=@var{socket}
Enables proxy filesystem driver to use passed socket file for communicating
with virtfs-proxy-helper
688 689 690 691
@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
692
@end table
693

694 695 696 697 698 699 700 701
-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
702
@end table
703

704 705
ETEXI

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

STEXI

713
@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}]
714 715
@findex -virtfs

716 717 718 719
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.
720
Currently "local", "handle" and "proxy" file system drivers are supported.
721 722 723 724 725 726 727
@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.
728
Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
729
In "passthrough" security model, files are stored using the same
730
credentials as they are created on the guest. This requires QEMU
731
to run as root. In "mapped-xattr" security model, some of the file
732
attributes like uid, gid, mode bits and link target are stored as
733 734
file attributes. For "mapped-file" these attributes are stored in the
hidden .virtfs_metadata directory. Directories exported by this security model cannot
735 736
interact with other unix tools. "none" security model is same as
passthrough except the sever won't report failures if it fails to
737
set file attributes like ownership. Security model is mandatory only
738
for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
739
model as a parameter.
740 741 742 743 744
@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.
745 746 747
@item readonly
Enables exporting 9p share as a readonly mount for guests. By default
read-write access is given.
748 749 750 751
@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
752 753 754
@item sock_fd
Enables proxy filesystem driver to use passed 'sock_fd' as the socket
descriptor for interfacing with virtfs-proxy-helper
755 756 757
@end table
ETEXI

758 759 760 761 762 763 764 765 766
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

767 768 769 770 771
STEXI
@end table
ETEXI
DEFHEADING()

772 773 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
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()

836 837 838 839 840
DEFHEADING(Display options:)
STEXI
@table @option
ETEXI

841 842
DEF("display", HAS_ARG, QEMU_OPTION_display,
    "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
843
    "            [,window_close=on|off]|curses|none|\n"
844
    "            gtk[,grab_on_hover=on|off]|\n"
845
    "            vnc=<display>[,<optargs>]\n"
846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861
    "                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
862 863 864 865 866 867
@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.
868 869 870 871
@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.
872 873
@item vnc
Start a VNC server on display <arg>
874 875 876
@end table
ETEXI

877
DEF("nographic", 0, QEMU_OPTION_nographic,
878 879
    "-nographic      disable graphical output and redirect serial I/Os to console\n",
    QEMU_ARCH_ALL)
880 881
STEXI
@item -nographic
882
@findex -nographic
883 884 885
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
886 887
the console and muxed with the monitor (unless redirected elsewhere
explicitly). Therefore, you can still use QEMU to debug a Linux kernel
888 889
with a serial console.  Use @key{C-a h} for help on switching between
the console and monitor.
890 891 892
ETEXI

DEF("curses", 0, QEMU_OPTION_curses,
893 894
    "-curses         use a curses/ncurses interface instead of SDL\n",
    QEMU_ARCH_ALL)
895 896
STEXI
@item -curses
897
@findex -curses
898 899 900 901 902 903
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,
904 905
    "-no-frame       open SDL window without a frame and window decorations\n",
    QEMU_ARCH_ALL)
906 907
STEXI
@item -no-frame
908
@findex -no-frame
909 910 911 912 913 914
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,
915 916
    "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
    QEMU_ARCH_ALL)
917 918
STEXI
@item -alt-grab
919
@findex -alt-grab
920 921
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).
922 923
ETEXI

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

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

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

Gerd Hoffmann's avatar
Gerd Hoffmann committed
950
DEF("spice", HAS_ARG, QEMU_OPTION_spice,
951 952 953 954 955 956 957 958 959 960 961 962
    "-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"
963 964
    "       [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
    "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
965 966 967
    "   enable spice\n"
    "   at least one of {port, tls-port} is mandatory\n",
    QEMU_ARCH_ALL)
Gerd Hoffmann's avatar
Gerd Hoffmann committed
968 969 970 971 972 973 974 975
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
976
Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann's avatar
Gerd Hoffmann committed
977

978 979 980 981 982 983 984
@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
985 986 987
@item password=<secret>
Set the password you need to authenticate.

988 989 990 991 992 993 994 995 996 997 998 999 1000
@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
1001 1002 1003
@item disable-ticketing
Allow client connects without authentication.

1004 1005 1006
@item disable-copy-paste
Disable copy paste between the client and the guest.

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

Gerd Hoffmann's avatar
Gerd Hoffmann committed
1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025
@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.

1026 1027
@item tls-channel=[main|display|cursor|inputs|record|playback]
@item plaintext-channel=[main|display|cursor|inputs|record|playback]
1028 1029 1030 1031 1032 1033
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.

1034 1035 1036 1037 1038 1039 1040 1041 1042
@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.

1043 1044 1045 1046 1047 1048 1049 1050 1051
@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.

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

Gerd Hoffmann's avatar
Gerd Hoffmann committed
1055 1056 1057
@end table
ETEXI

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

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

1076
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
1077
    "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|none]\n"
1078
    "                select video card type\n", QEMU_ARCH_ALL)
1079
STEXI
1080
@item -vga @var{type}
1081
@findex -vga
1082
Select type of VGA card to emulate. Valid values for @var{type} are
1083
@table @option
1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097
@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
1098 1099 1100 1101
@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.
1102 1103 1104 1105 1106 1107 1108 1109
@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.
1110 1111 1112 1113 1114 1115
@item none
Disable VGA card.
@end table
ETEXI

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

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

DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
1133
    "-vnc display    start a VNC server on display\n", QEMU_ARCH_ALL)
1134 1135
STEXI
@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
1136
@findex -vnc
1137 1138 1139 1140 1141 1142 1143 1144
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

1145
@table @option
1146 1147 1148 1149 1150 1151 1152

@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.

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

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

1168
@table @option
1169 1170 1171 1172 1173 1174 1175 1176

@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.

1177 1178 1179
@item websocket

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

1187 1188 1189
@item password

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

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.
1205 1206 1207 1208 1209 1210

@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
1211
@option{x509} or @option{x509verify} options.
1212 1213 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

@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
1263 1264 1265 1266 1267 1268 1269
@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.

1270 1271 1272 1273 1274
@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).
1275
This can be really helpful to save bandwidth when playing videos. Disabling
1276
adaptive encodings restores the original static behavior of encodings
1277 1278
like Tight.

1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289
@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
1290
spec but is traditional QEMU behavior.
1291

1292 1293 1294 1295 1296 1297
@end table
ETEXI

STEXI
@end table
ETEXI
1298
ARCHHEADING(, QEMU_ARCH_I386)
1299

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

DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1306 1307
    "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
    QEMU_ARCH_I386)
1308 1309
STEXI
@item -win2k-hack
1310
@findex -win2k-hack
1311 1312 1313 1314 1315
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

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

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

DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1330
           "-no-acpi        disable ACPI\n", QEMU_ARCH_I386)
1331 1332
STEXI
@item -no-acpi
1333
@findex -no-acpi
1334 1335 1336 1337 1338 1339
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,
1340
    "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
1341 1342
STEXI
@item -no-hpet
1343
@findex -no-hpet
1344 1345 1346 1347
Disable HPET support.
ETEXI

DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1348
    "-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"
1349
    "                ACPI table description\n", QEMU_ARCH_I386)
1350 1351
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}]...]
1352
@findex -acpitable
1353
Add ACPI table with specified header fields and context from specified files.
1354 1355 1356 1357 1358
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.
1359 1360
ETEXI

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

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

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

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

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

1391 1392
HXCOMM Legacy slirp options (now moved to -net user):
#ifdef CONFIG_SLIRP
1393 1394 1395
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)
1396
#ifndef _WIN32
1397
DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1398 1399 1400
#endif
#endif

Blue Swirl's avatar
Blue Swirl committed
1401
DEF("net", HAS_ARG, QEMU_OPTION_net,
1402
    "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1403 1404
    "                create a new Network Interface Card and connect it to VLAN 'n'\n"
#ifdef CONFIG_SLIRP
1405
    "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
1406 1407
    "         [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n"
    "         [,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
1408
#ifndef _WIN32
1409
                                             "[,smb=dir[,smbserver=addr]]\n"
1410 1411 1412
#endif
    "                connect the user mode network stack to VLAN 'n', configure its\n"
    "                DHCP server and enabled optional services\n"
1413 1414 1415 1416 1417
#endif
#ifdef _WIN32
    "-net tap[,vlan=n][,name=str],ifname=name\n"
    "                connect the host TAP network interface to VLAN 'n'\n"
#else
1418
    "-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"
1419
    "                connect the host TAP network interface to VLAN 'n'\n"
1420 1421 1422
    "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
    "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
    "                to deconfigure it\n"
1423
    "                use '[down]script=no' to disable script execution\n"
1424 1425
    "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
    "                configure it\n"
1426
    "                use 'fd=h' to connect to an already opened TAP interface\n"
1427
    "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
1428
    "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1429
    "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1430 1431
    "                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"
1432
    "                use vhost=on to enable experimental in kernel accelerator\n"
1433 1434
    "                    (only has effect for virtio guests which use MSIX)\n"
    "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1435
    "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
1436
    "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
1437
    "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
1438 1439 1440 1441
    "-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
1442 1443 1444 1445 1446
#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"
1447
    "                L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov's avatar
Anton Ivanov committed
1448 1449 1450 1451 1452 1453
    "                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"
1454
    "                use 'srcport=' to specify source udp port\n"
Anton Ivanov's avatar
Anton Ivanov committed
1455 1456 1457 1458 1459 1460 1461 1462 1463 1464
    "                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"
1465 1466 1467
#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"
1468
    "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1469
    "                connect the vlan 'n' to multicast maddr and port\n"
1470
    "                use 'localaddr=addr' to specify the host address to send packets from\n"
1471 1472
    "-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"
1473 1474 1475 1476 1477 1478
#ifdef CONFIG_VDE
    "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
    "                connect the vlan 'n' to port 'n' of a vde switch running\n"