arcbox-ext4 0.1.0

Pure-Rust ext4 filesystem formatter and reader for container images
Documentation

arcbox-ext4

Pure-Rust ext4 filesystem formatter and reader. Creates and reads ext4 images entirely in userspace -- no kernel mount, no FUSE, no C dependencies.

Designed for converting OCI container image layers into ext4 block device images on macOS and Linux.

Features

  • Formatter -- create ext4 images from scratch (mkfs + file population)
  • Reader -- parse and read existing ext4 images (files, directories, symlinks)
  • OCI unpack -- stream tar layers into ext4 with whiteout semantics (.wh.*, .wh..wh..opq)
  • Extended attributes (inline + block)
  • Extent trees (depth 0 and 1)
  • Hard links with correct reference counting
  • Symlinks (inline for targets < 60 bytes, data-block otherwise)
  • No journal (not needed for container rootfs)

Quick start

use std::path::Path;
use arcbox_ext4::Formatter;

// Create a new ext4 image.
let mut fmt = Formatter::new(Path::new("rootfs.ext4"), 4096, 256 * 1024)?;
fmt.create("/hello.txt", 0x8000 | 0o644, None, None,
    Some(&mut "hello world".as_bytes()), None, None, None)?;
fmt.close()?;

// Read it back.
let mut reader = arcbox_ext4::Reader::new(Path::new("rootfs.ext4"))?;
let data = reader.read_file("/hello.txt", 0, None)?;
assert_eq!(&data, b"hello world");

OCI layer unpacking

use std::io::Cursor;
use arcbox_ext4::Formatter;

let mut fmt = Formatter::new(path, 4096, 512 * 1024 * 1024)?;
fmt.unpack_tar(Cursor::new(&layer1_tar))?;
fmt.unpack_tar(Cursor::new(&layer2_tar))?; // overlay with whiteouts
fmt.close()?;

Limitations

  • Block size is fixed at 4096 bytes
  • Maximum file size: 128 GiB
  • No journal support
  • No metadata checksumming (metadata_csum)
  • Extent tree depth limited to 1

License

Licensed under either of

at your option.