/qcow2-fuse

Gain access to qcow2 virtual disk images as a user-space filesystem

Primary LanguageRustMIT LicenseMIT

qcow2-fuse

This program allows you to mount qcow2 virtual disk images as FUSE filesystems.

Usage

Mount a myimage.qcow2 onto the directory mnt with:

qcow2-fuse myimage.qcow2 mnt

The directory will now contain a file mnt/myimage that lets you read the virtual disk contents.

Using the mounted image

Your virtual disk may contain just one partition, in which case you can mount it like a device:

mount mnt/myimage /mnt/myimage

# Or with another FUSE filesystem:
ext4fuse mnt/myimage /mnt/myimage

By default, FUSE filesystems are only available to the current user. If you want to mount the virtual filesystem as root, you'll need to pass the -o allow_root option to qcow2-fuse.

Partitions

Sometimes your virtual disk contains multiple partitions, so you can't just mount it directly. Instead, ask your OS to take care of reading the partitions:

# On Linux:
kpartx -a mnt/myimage

# On macOS
hdiutil attach -imagekey diskimage-class=CRawDiskImage \
  -nomount mnt/myimage

This will generate new entries in /dev that you can then mount as above.

Options

Several options to this program are available. You can see descriptions of some of them by running qcow2-fuse --help.

Many options starting with -o will be passed through to FUSE. You can read about these options for Linux and for macOS.

Installation

The best way to install this right now is using cargo, the Rust package manager.

First, you'll need Rust and Cargo themselves. You can download them here.

Second, you'll need to have FUSE installed, and pkg-config so that we can find it. Here are some examples of how to get those:

  • Ubuntu: sudo apt-get install libfuse-dev pkg-config
  • macOS: Install MacPorts, then sudo port install osxfuse pkgconfig

Finally, you can install this program: cargo install qcow2-fuse

Binaries

I'll try to make these available when I have the bandwidth.

Features

This program can mount only certain qcow2 images:

  • Only version 3 (aka "qcow2 1.1") is supported; version 2 is not supported.
  • This program provides read-only access, writing is not supported.
  • Compressed blocks are not supported.
  • Encryption is not supported.
  • Backing files are not supported.
  • It's ok if the image contains snapshots. But this program will only provide access to the main image, not the snapshots.
  • Repairing damaged images is not supported.

License

This program is available under the MIT license.

See also