ferrosys

A pure-Rust ext2/ext3/ext4 filesystem: it builds and reads filesystem images in userspace, over ordinary byte streams, in safe Rust.

This Cargo workspace holds two crates:

• ferrosys — the library: a formatter and reader with resize-safe, byte-reproducible on-disk geometry.
• ferrosys-cli — the ferrosys binary, which puts the library on the command line.

Both build on Rust 1.88 or newer.

Status: under active development. The APIs are not yet stable. Following Cargo's 0.x semantics, a breaking change bumps the minor version, and a 0.x requirement resolves only within that minor — so a breaking release reaches no one unasked.

Highlights

• ext2, ext3, and ext4 — one formatter and one reader across the lineage, from the classic direct/indirect block map to extent trees of any depth.
• Resize-safe geometry — descriptor backups and reserved GDT blocks, sized by a grow reservation, let the image grow in place without relocating its descriptor table.
• Byte-reproducible — the UUID, hash seed, and timestamps are inputs, so the same inputs write the same image every time.
• Full fidelity — every file type, ownership and mode bits, nanosecond timestamps, extended attributes, POSIX ACLs, metadata checksums, a jbd2 journal, and an orphan file.
• A robust reader — bounds-checks every field into typed errors, reads foreign images other tools wrote, and scans a whole image into typed anomalies rendered as JSON, SARIF, or a table, allocating in proportion to the bytes an image holds rather than to what it claims.
• Built for scale — streaming in both directions: a format writes only the blocks the filesystem uses, so an image stays sparse and may be larger than memory, and a read windows its way through a file rather than holding it, so pulling a multi-gigabyte file out of an image costs a working set. 64-bit block addressing reaches past 16 TiB.
• Sources — a programmatic tree, a tar archive, or a directory on this machine, each handing a file's bytes over as a handle so a format's peak memory is the largest single file rather than the sum of them all.

The crate README and the guide carry the complete feature list.

The command line

$ cargo install --path crates/ferrosys-cli

$ ferrosys format --size 512M --uuid "$(uuidgen)" --time 1700000000 \
      --from-tar rootfs.tar rootfs.img
$ ferrosys inspect rootfs.img
$ ferrosys extract rootfs.img --to-tar - | tar -tv

format writes a filesystem — from a tar archive, a directory tree, or empty — inspect reports on one and says whether it is sound, extract reads the contents back out as a tar archive, one file's bytes, one path's metadata, or a listing, and detect says which filesystem an image holds. The identifiers and timestamps are inputs, so the same inputs write the same image every time. The exit codes mirror e2fsck's. See the guide's command-line chapter.

Build and test

cargo build
cargo test
cargo doc --no-deps            # clean under RUSTDOCFLAGS="-D warnings"

Documentation

The guide and the API reference are published together to GitHub Pages:

• The guide — a narrative introduction, built with mdbook from book/. Build it locally with mdbook serve book (or mdbook build book).
• The API reference — rustdoc for the crate, generated by cargo doc --no-deps. The guide's code examples compile against the crate with mdbook test book -L target/debug/deps, so they stay in step with the API.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.