Often you want to access an image file from the host to:
- Copy files in before starting a new virtual machine.
- Customize configuration like setting a hostname or networking details.
- Troubleshoot a virtual machine that fails to boot.
- Retrieve files after you've decided to stop using a virtual machine.
There is actually a toolkit for accessing image files called libguestfs. Take a look at that first but what follows is the poor man's version using tools that come with QEMU.
Required packages
The required programs are the qemu-nbd tool and (optionally) kpartx for detecting partitions.
On Debian-based distros the packages are called qemu-utils and kpartx.
On RHEL 6 nbd support is not available out-of-the-box but you can build from source if you wish.
Please leave package names for other distros in the comments!
Remember to back up important data
Consider making a backup copy of the image file before trying this out. Especially if you don't work with disk images often it can be easy to lose data with a wrong command.
Attaching an image file
The goal is to make an image file appear on the host as a block device so it can be mounted or accessed with tools like fdisk or fsck. The image file can be in any format that QEMU supports including raw, qcow2, qed, vdi, vmdk, vpc, and others.
1. Ensure the nbd driver is loaded
The Network Block Device driver in Linux needs to be loaded:
modprobe nbd
The qemu-nbd tool will use the nbd driver to create block devices and perform I/O.
2. Connect qemu-nbd
Before you do this, make sure the virtual machine is not running! It is generally not safe to access file systems from two machines at once and this applies for virtual machines and the host.
There should be many /dev/nbdX devices available now and you can pick an unused one as the block device through which to access the image:
sudo qemu-nbd -c /dev/nbd0 path/to/image/file
Don't be surprised that there is no output from this command. On success the qemu-nbd tool exits and leaves a daemon running in the background to perform I/O. You can now access /dev/nbd0 or whichever nbd device you picked like a regular block device using mount, fdisk, fsck, and other tools.
3. (Optionally) detect partitions
The kpartx utility automatically sets up partitions for the disk image:
sudo kpartx -a /dev/nbd0
They would be named /dev/nbd0p1, /dev/nbd0p2, and so on.
Detaching an image file
When all block devices and partitions are no longer mounted or in use you can clean up as follows.
1. (Optionally) forget partitions
sudo kpartx -d /dev/nbd0
2. Disconnect qemu-nbd
sudo qemu-nbd -d /dev/nbd0
3. Remove the nbd driver
Once there are no more attached nbd devices you may wish to unload the nbd driver:
sudo rmmod nbd
More features: read-only, throwaway snapshots, and friends
The qemu-nbd tool has more features that are worth looking at:
- Ensuring read-only access using the --read-only option.
- Allowing write access but not saving changes to the image file using the --snapshot option. You can think of this as throwaway snapshots.
- Exporting the image file over the network using the --bind and --port options. Drop the -c option because no local nbd device is used in this case. Only do this on secure private networks because there is no access control.
Hopefully this has helped you quickstart qemu-nbd for accessing image files from the host. Feel free to leave questions in the comments below.
