qemu-system-x86_64 -drive options

In an attempt to make the qemu -drive command line options more accessible, here is an extract from the qemu-system-x86_64 man page. You can get the complete man page by entering the following in a terminal window:
man qemu-system-x86_64

The options below are valid for qemu-system-x86_64 version 2.5.0. Please refer to the qemu documentation at qemu.weilnetz.de – look for the version you got and select the corresponding sub-folder. You find the latest documentation (qemu 3.0.0) here.

(Note: The latest qemu syntax can also be found here. For -device and -drive options, see qdev-device-use.txt. For the syntax of your current qemu version, change the branch from “Master” to your qemu release.)

Note: For recommendations on drive configuration, see Tuning VM Disk Performance.

The -drive definition has many options:

-drive option[,option[,option[,...]]]
Define a new drive.

Here some of the more useful ones:

file=file
This option defines which disk image to use with this drive.

if=interface
This option defines to which type of interface the drive is
connected. Available types are: ide, scsi, sd, mtd, floppy,
pflash, virtio. We use virtio for performance.

bus=bus,unit=unit
These options define where the drive is connected by defining
the bus number and the unit id.

index=index
This option defines where the drive is connected by using an
index in the list of available connectors of a given interface
type. [Comment: It’s usually not necessary to specify this.]

media=media
This option defines the type of the media: disk or cdrom. Default is disk.

cache=cache
cache is “none”, “writeback”, “unsafe”, “directsync” or
“writethrough” and controls how the host cache is used to
access block data. Use none or writeback and see which performs better. More explanations on cache settings below.

aio=aio
aio is “threads”, or “native” and selects between pthread based
disk I/O and native Linux AIO. Try native.

discard=discard
discard is one of “ignore” (or “off”) or “unmap” (or “on”) and
controls whether discard (also known as trim or unmap) requests
are ignored or passed to the filesystem. Some machine types
may not support discard requests.

format=format
Specify which disk format will be used rather than detecting
the format. Can be used to specifiy format=raw to avoid
interpreting an untrusted format header.

serial=serial
This option specifies the serial number to assign to the
device.

addr=addr
Specify the controller’s PCI address (if=virtio only).

readonly
Open drive file as read-only. Guest write attempts will fail.

copy-on-read=copy-on-read
copy-on-read is “on” or “off” and enables whether to copy read
backing file sectors into the image file.

detect-zeroes=detect-zeroes
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 discard is set to “unmap” to allow a zero write to
be converted to an UNMAP operation.

By default, the 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 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 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 cache=directsync.

In case you don’t care about data integrity over host failures, use
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 -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.

Important: Note that there are some more options with -drive that I haven’t listed here.

One thought on “qemu-system-x86_64 -drive options”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.