ublk-seekable-zstd

A read-only ublk block device backed by seekable zstd images. This tool allows you to mount zstd-compressed disk images as block devices without decompressing them entirely, enabling random access to the compressed data.

Features

• Read-only block device: Exposes a zstd-compressed file as a block device.
• Seekable Zstd: Uses a frame-based approach with a seek table to allow efficient random access.
• ublk: Utilizes the userspace block device (ublk) framework for high performance and flexibility.

Prerequisites

• Linux Kernel 6.0+: Requires a kernel with ublk_drv support. Try sudo modprobe ublk_drv. Tested on Linux 6.16.
• Rust Toolchain: Required to build the project.

Installation

Clone the repository and build the project:

cargo build --release

Manual Testing

1. If you don't have a seekable zstd disk image, create one

First, you need to convert your raw disk image into a seekable zstd image using the provided example tool.

# Create a dummy raw image (e.g., 40MB)
dd if=/dev/urandom of=test.img bs=1M count=40

# Convert it to seekable zstd format
cargo run --example create_seekable_zstd -- --input test.img --output test.img.zst

2. Run the Block Device

Start the ublk device backed by the compressed image.

# Run the ublk device (requires root or appropriate permissions)
sudo ./target/release/ublk-seekable-zstd --backing-file test.img.zst --dev-id 10

This will create a block device (e.g., /dev/ublkb10).

3. Verify

You can now read from the device:

sudo dd if=/dev/ublkb10 of=/dev/null status=progress

Command Line Arguments

Usage: ublk-seekable-zstd [OPTIONS] --backing-file <BACKING_FILE>

Options:
  -b, --backing-file <BACKING_FILE>  Path to the seekable zstd backing file
  -d, --dev-id <DEV_ID>              Device ID (optional, auto-allocated if not provided)
  -q, --queue-depth <QUEUE_DEPTH>    Queue depth [default: 64]
  -h, --help                         Print help
  -V, --version                      Print version

License

Apache License 2.0

Other Notes

This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.