inclusionAI/distill-fs

inclusionAI/distill-fs

Description: Read-only FUSE filesystem for raw disk images and Nydus RAFS images.

Language: Rust

License: Apache-2.0

Stars: 1

Forks: 1

Open issues: 0

Created: 2026-07-11T12:34:07Z

Pushed: 2026-07-21T14:36:55Z

Default branch: main

Fork: no

Archived: no

README:

distill_fs

distill_fs is a read-only FUSE filesystem for raw disk images and Nydus RAFS images. The current implementation combines:

• on-demand reads from local or remote storage
• sparse local cache files with bitmap sidecars
• optional chunk-level deduplication backed by LMDB
• an optional local/peer chunk server for chunk sharing
• optional OTLP metrics export

What The Current Code Actually Supports

• mount is implemented on Linux only. On non-Linux targets, mounting returns

an unsupported-operation error.

• --src local mounts a single raw file from the local filesystem.
• --src oss mounts a single raw file from a remote backend created from a

Nydus BackendConfigV2 JSON file. Despite the flag name, this path is not OSS-only. With the current build features it can use OSS, S3, registry, and HTTP-proxy backends exposed by nydus-storage.

• --src nydus mounts a Nydus RAFS v5 filesystem from a bootstrap plus backend

config.

• Optional dedup uses:
• ChunkDB: global content-addressed chunk storage
• IndexDB: per-image offset-to-checksum metadata
• serve-chunk exposes a local ChunkDB over both TCP and a Unix socket, and

can cooperate with peers plus an optional Redis-backed chunk ownership index.

• gc-chunk and stats-chunk operate on ChunkDB.

Important Behavior And Constraints

• The filesystem is read-only.
• Raw-image mounts expose exactly one file at the mountpoint root. That file is

named by --name.

• For raw-image mounts, --name must be a single path component. The current

implementation reuses it as both the mounted filename and the raw-image backend identifier.

• For raw-image mounts, --name is also used as the dedup metadata identity.

Reuse the same --name only for the same image namespace/content lineage when sharing an image_meta_dir.

• --chunk-db-dir and --image-meta-dir must be configured together or both

omitted.

• The cache layer creates a sidecar bitmap file next to each cache file:

.bitmap.

• --src local opens the source file read-write. When dedup is enabled, chunks

that have been persisted to ChunkDB may be hole-punched from that file. Use a dedicated writable cache copy if you need to preserve the original file byte-for-byte.

• In Nydus mode, --name is still required by the CLI parser, but it is not

used by the mounted filesystem.

• In Nydus mode, --cache-dir is optional. If set, blob payloads are cached on

disk and wrapped in the same cache/dedup stack. If omitted, blob ranges are fetched directly from the backend, while decompressed chunks can still be served from and stored into ChunkDB when dedup is enabled.

• The current Nydus read path supports RAFS v5. RAFS v6 images are rejected

with an unsupported-operation error until the read path is moved to Nydus' BlobDevice flow.

• The current Nydus read path does not support encrypted chunks or batched

chunks.

• gc-chunk --dry-run only skips deletion. It does not print a deletion plan.

Build

Prerequisites:

• Rust 1.85.0; rust-toolchain.toml installs the matching formatter
• Linux with /dev/fuse access for mount
• writable directories for cache files, bitmap sidecars, LMDB data, and Unix

sockets

• optional Redis if you want dynamic peer discovery or a Redis-backed chunk

index

Build the main binary:

cargo build --bin distill_fs

Run the CLI help:

cargo run --bin distill_fs -- --help

CLI Overview

The main binary exposes four subcommands:

| Command | Purpose | | --- | --- | | mount | Mount a raw image or Nydus filesystem | | serve-chunk | Serve local chunks over TCP and Unix socket, optionally with peer coordination | | gc-chunk | Garbage-collect old/LRU chunks from ChunkDB | | stats-chunk | Print lightweight JSON stats for ChunkDB |

Global flags:

• -d, --verbose: enable debug logging

Common operational flags:

• --daemon: daemonize the process
• --pid-file: PID file path to use with --daemon
• --log-file: log file path; if set, logs go through the rotating file writer
• --otel-endpoint: enable OTLP metrics export

Mount Modes

--src local

Mount an existing local raw file as a single file in the mountpoint.

Required arguments:

• --name: filename exposed inside the mountpoint and dedup metadata key
• --mountpoint: FUSE mountpoint
• --cache-file: path to the existing local raw file

Example:

mkdir -p /mnt/raw

cargo run --bin distill_fs -- mount \
--src local \
--name disk.raw \
--cache-file /data/disk.raw \
--mountpoint /mnt/raw

--src oss

Mount a remote raw file as a single file in the mountpoint. The implementation uses GeneralBackend, which loads a Nydus BackendConfigV2 JSON file. The build enables local filesystem, OSS, S3, registry, and HTTP-proxy backends.

Required arguments:

• --name: remote object/blob identifier and mounted filename; it must still

be valid as a single filename inside the mountpoint

• --mountpoint: FUSE mountpoint
• --cfg: backend config JSON
• --cache-file: writable local cache file path

Example:

mkdir -p /mnt/raw /var/cache/distill

cargo run --bin distill_fs -- mount \
--src oss \
--name rootfs.raw \
--cfg /etc/distill/backend.json \
--cache-file /var/cache/distill/rootfs.raw \
--mountpoint /mnt/raw

--src nydus

Mount a Nydus RAFS filesystem from a bootstrap file plus backend config.

Required arguments:

• --name: required by the CLI, but ignored by the Nydus mount logic
• --mountpoint: FUSE mountpoint
• --bootstrap: Nydus bootstrap path
• --cfg: backend config JSON

Optional but common:

• --cache-dir: writable directory for blob cache files

Example:

mkdir -p /mnt/nydus /var/cache/distill/blobs

cargo run --bin distill_fs -- mount \
--src nydus \
--name nydus-image \
--bootstrap /images/bootstrap.rafs \
--cfg /etc/distill/backend.json \
--cache-dir /var/cache/distill/blobs \
--mountpoint /mnt/nydus

Enabling Dedup

Dedup is optional for both raw and Nydus mounts. To enable it, configure both:

• --chunk-db-dir
• --image-meta-dir

When enabled:

• ChunkDB stores chunk payloads globally by checksum
• IndexDB stores per-image range metadata
• raw-image...