-drive option[,option[,option[,...]]]
Define a new drive. This includes creating a block driver node (the backend) as well as a guest device, and is mostly a shortcut for defining the corresponding -blockdev and -device options.
-drive accepts all options that are accepted by -blockdev. In addition, it knows the following options:
file=file
This option defines which disk image (see the Disk Images chapter in the System Emulation Users Guide) 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.
if=interface
This option defines on which type on interface the drive is connected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
bus=bus,unit=unit
These options define where is connected the drive 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.
media=media
This option defines the type of the media: disk or cdrom.
snapshot=snapshot
snapshot is “on” or “off” and controls snapshot mode for the given drive (see -snapshot).
cache=cache
cache is “none”, “writeback”, “unsafe”, “directsync” or “writethrough” and controls how the host cache is used to access block data. This is a shortcut that sets the cache.direct and cache.no-flush options (as in -blockdev), and additionally cache.writeback, which provides a default for the write-cache option of block guest devices (as in -device). The modes correspond to the following settings:
(Table removed see link)
The default mode is cache=writeback.
aio=aio
aio is “threads”, “native”, or “io_uring” and selects between pthread based disk I/O, native Linux AIO, or Linux io_uring API.
format=format
Specify which disk format will be used rather than detecting the format. Can be used to specify format=raw to avoid interpreting an untrusted format header.
werror=action,rerror=action
Specify which 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 werror=enospc and rerror=report.
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.
bps=b,bps_rd=r,bps_wr=w
Specify bandwidth throttling limits in bytes per second, either for all request types or for reads or writes only. Small values can lead to timeouts or hangs inside the guest. A safe minimum for disks is 2 MB/s.
bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
Specify bursts in bytes per second, either for all request types or for reads or writes only. Bursts allow the guest I/O to spike above the limit temporarily.
iops=i,iops_rd=r,iops_wr=w
Specify request rate limits in requests per second, either for all request types or for reads or writes only.
iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
Specify bursts in requests per second, either for all request types or for reads or writes only. Bursts allow the guest I/O to spike above the limit temporarily.
iops_size=is
Let every is bytes of a request count as a new request for iops throttling purposes. Use this option to prevent guests from circumventing iops limits by sending fewer but larger requests.
group=g
Join a throttling quota group with given name g. All drives that are members of the same group are accounted for together. Use this option to prevent guests from circumventing throttling limits by using many small disks instead of a single larger disk.
By default, the cache.writeback=on 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.writeback=off. 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.
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.
Instead of -cdrom you can use:
qemu-system-x86_64 -drive file=file,index=2,media=cdrom
Instead of -hda, -hdb, -hdc, -hdd, you can use:
qemu-system-x86_64 -drive file=file,index=0,media=disk
qemu-system-x86_64 -drive file=file,index=1,media=disk
qemu-system-x86_64 -drive file=file,index=2,media=disk
qemu-system-x86_64 -drive file=file,index=3,media=disk
You can open an image using pre-opened file descriptors from an fd set:
qemu-system-x86_64 \
-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
You can connect a CDROM to the slave of ide0:
qemu-system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
If you don’t specify the “file=” argument, you define an empty drive:
qemu-system-x86_64 -drive if=ide,index=1,media=cdrom
Instead of -fda, -fdb, you can use:
qemu-system-x86_64 -drive file=file,index=0,if=floppy
qemu-system-x86_64 -drive file=file,index=1,if=floppy
By default, interface is “ide” and index is automatically incremented:
qemu-system-x86_64 -drive file=a -drive file=b
is interpreted like:
qemu-system-x86_64 -hda a -hdb b