How to mount qcow2 disk image on Linux

Question: I have a qcow2-type disk image which is used by one my guest VMs on QEMU/KVM. I want to modify the content of the disk image without powering on the VM, and for this I need to mount the disk image somewhere. Is there a way to mount a qcow2 disk image on Linux?

When you run a guest virtual machine (VM) on a hypervisor, you create one or more disk images dedicated to the VM. As a "virtual" disk volume, a disk image represents the content and structure of a storage device (e.g., a hard disk drive or flash drive) attached to the VM. If you want to modify files in a VM's disk image without powering on the VM, you could "mount" the disk image. You then would be able to modify the content of the disk image before unmounting it.

In Linux, there are ways to mount a disk image, and different types of disk images require different approaches. If you are using qcow2-type disk images (used by QEMU/KVM), there are at least two ways to mount them on Linux.

Method One: libguestfs

The first method to mount a qcow2 disk image is by using libguestfs which provides (among other things) a suite of tools for accessing and editing VM disk images. libguestfs supports pretty much all kinds of disk images including qcow2. You can install the libguestfs toolset on Linux as follows.

On Debian-based system:

$ sudo apt-get install libguestfs-tools

On Red Hat-based system:

$ sudo yum install libguestfs-tools

Once the libguestfs toolset is installed, you can mount a qcow2 image using a command-line tool called guestmount as follows. Note that when a VM is running, you must *not* mount its disk image in "read-write" mode. Otherwise, you run the risk of damaging the disk image. Thus, it is safe to always turn off a VM before mounting its disk image.

$ sudo guestmount -a /path/to/qcow2/image -m <device> /path/to/mount/point

The "-m <device>" option is used to specify a partition within the disk image, that you want to mount (e.g., /dev/sda1). If you are not sure what partitions exist in the disk image, you can supply any bogus device name. The guestmount tool will then show you available device names to choose from.

For example, to mount /dev/sda1 in the disk image 'xenserver.qcow2' at /mnt mount point, run the following.

$ sudo guestmount -a /var/lib/libvirt/images/xenserver.qcow2 -m /dev/sda1 /mnt

By default, the disk image is mounted in "read-write" mode. So you can modify any file in /mnt after mounting it.

If you want to mount it in "read-only" mode:

$ sudo guestmount -a /var/lib/libvirt/images/xenserver.qcow2 -m /dev/sda1 --ro /mnt

To unmount it:

$ sudo guestunmount /mnt

Method Two: qemu-nbd

Another method to mount a qcow2 disk image is via qemu-nbd, a command-line tool that exports a disk image as a "network block device (nbd)".

You can install qemu-nbd on Linux as follows.

On Debian-based system:

$ sudo apt-get install qemu-utils

On Red Hat-based system:

$ sudo yum install qemu-img

To mount a qcow2 disk image, first export the image to nbd as follows.

$ sudo modprobe nbd max_part=8
$ sudo qemu-nbd --connect=/dev/nbd0 /path/to/qcow2/image

The first command loads the nbd kernel module. The "max_part=N" option specifies the maximum number of partitions we want to manage with nbd. The second command exports the specified disk image as a network block device (/dev/nbd0). As a network block device, you can use /dev/nbd0, /dev/nbd1, /dev/nbd2, etc. whichever is unused. As for the disk image, make sure to specify its "full" path.

For example, to export the image 'xenserver.qcow2' as /dev/nbd0:

$ sudo qemu-nbd --connect=/dev/nbd0 /var/lib/libvirt/images/xenserver.qcow2

After this, existing disk partitions in the disk image will be mapped to /dev/nbd0p1, /dev/nbd0p2, /dev/nbd0p3, etc.

To check the list of nbd-mapped partitions, use fdisk:

$ sudo fdisk /dev/nbd0 -l

Finally, choose any one partition (e.g., /dev/nbd0p1) and mount it to a local mount point (e.g., /mnt).

$ sudo mount /dev/nbd0p1 /mnt

Now you will be able to access and modify the content of the disk image's mounted partition via /mnt mount point.

Once you are done, unmount it, and disconnect the disk image as follows.

$ sudo umount /mnt
$ sudo qemu-nbd --disconnect /dev/nbd0

Download this article as ad-free PDF (made possible by your kind donation): 
Download PDF

Subscribe to Ask Xmodulo

Do you want to receive Linux related questions & answers published at Ask Xmodulo? Enter your email address below, and we will deliver our Linux Q&A straight to your email box, for free. Delivery powered by Google Feedburner.

Support Xmodulo

Did you find this tutorial helpful? Then please be generous and support Xmodulo!

2 thoughts on “How to mount qcow2 disk image on Linux

  1. Maybe just on Centos 6, but guestunmount is not installed together with guestmount, according to yum whatprovides, no package provides it, and a regular umount will work just fine.

Leave a comment

Your email address will not be published. Required fields are marked *