partclone-nbd

partclone-nbd exposes a Partclone or Clonezilla partition image as a read-only Network Block Device (NBD). This makes it possible to inspect and mount a filesystem directly without restoring the complete image first.

Version 0.0.4 supports Partclone image formats 0001 and 0002, including BIT, BYTE, and NONE bitmap layouts. The Partclone image block size is kept separate from the NBD logical block size, so images using 16 KiB filesystem blocks work on conventional Linux systems with 4 KiB pages.

Requirements

• Linux with the NBD kernel module
• a seekable, decoded Partclone image stream
• root privileges for local NBD device configuration
• an unused /dev/nbdN device

Compressed or split Clonezilla images must first be joined and decoded into a seekable file or block-device stream. A decoded block-device stream must preserve and pad the full image byte length, including any padding at the end.

Partclone data-block checksums are not verified. Header and bitmap CRCs are verified when present.

Installation

Debian package

Build a binary package with:

dpkg-buildpackage -us -uc -b
sudo apt install ../partclone-nbd_0.0.4-1_amd64.deb

The package installs the program, manual page, and Bash completion.

CMake

cmake -S . -B build
cmake --build build
sudo cmake --install build

Local Client Mode

Client mode is preferred when the image is consumed on the same machine. partclone-nbd remains in the foreground while the device is connected.

sudo modprobe nbd
sudo partclone-nbd --client-mode --device=/dev/nbd0 image.partclone

In another terminal, inspect and mount the exported filesystem read-only:

sudo blockdev --getro /dev/nbd0
sudo blockdev --getsize64 /dev/nbd0
sudo mount -o ro,nosuid,nodev,noexec /dev/nbd0 /mnt/image

Disconnect cleanly when finished:

sudo umount /mnt/image
sudo nbd-client -d /dev/nbd0

Server Mode

Server mode listens on 127.0.0.1 by default and serves one client at a time:

partclone-nbd --server-mode image.partclone
sudo nbd-client 127.0.0.1 10809 /dev/nbd0

Remote access must be enabled explicitly:

partclone-nbd --server-mode --address=0.0.0.0 --port=10809 image.partclone

Server mode does not provide authentication or encryption. Do not expose it to an untrusted network. Prefer an SSH tunnel, WireGuard, or another protected transport for remote use.

Options

Short	Long	Description
-c	--client-mode	Attach the image to a local NBD device
-s	--server-mode	Serve the image over TCP
-a	--address=ADDRESS	Server-only IPv4 listen address; default 127.0.0.1
-p	--port=NUM	Server-only TCP port; default 10809
-d	--device=DEV	Client-only local NBD device; default /dev/nbd0
-x	--elems-per-cache=NUM	Bitmap cache grouping; default 512; higher values use less RAM but make random access slower
-L	--log-file=FILE	Log file path; default partclone-nbd.log
-D	--debug	Print debug messages
-q	--quiet	Write messages only to the log
-h	--help	Display command help
-V	--version	Display the program version

Only one of client mode and server mode may be selected. Client mode rejects explicit --address and --port; server mode rejects explicit --device.

Bash Completion

The Debian package installs completion at:

/usr/share/bash-completion/completions/partclone-nbd

Start a new shell after installation, or load it immediately with:

source /usr/share/bash-completion/completions/partclone-nbd

Validation

Version 0.0.4 has been tested on Debian 13 with Linux 6.12 using:

• a Btrfs Partclone v2 image with a 16 KiB image block size
• CRC32 and no-data-checksum images
• 4096-byte and 512-byte NBD logical block sizes
• exact byte-capacity and read-only checks
• reads across Partclone block boundaries and at the end of the device
• read-only mount, fixture SHA-256 verification, and clean disconnect
• malformed, truncated, and checksum-corrupted images

Authors

• Przemyslaw Kusiak, original author
• crims0n crims0n@minios.dev, current maintainer

License

The project is distributed under the MIT License. See LICENSE. The CRC32 implementation in src/crc.c retains its applicable zlib terms.