{"id":50319475,"url":"https://github.com/arcboxlabs/ext4-rs","last_synced_at":"2026-05-29T02:30:19.905Z","repository":{"id":348158537,"uuid":"1196274277","full_name":"arcboxlabs/ext4-rs","owner":"arcboxlabs","description":"Pure-Rust ext4 filesystem formatter and reader. No kernel mount, no FUSE, no C dependencies.","archived":false,"fork":false,"pushed_at":"2026-04-22T08:56:29.000Z","size":97,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-23T02:34:45.877Z","etag":null,"topics":["container","ext4","filesystem","mkfs","oci","rust","userspace"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arcboxlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T14:38:41.000Z","updated_at":"2026-04-22T08:56:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arcboxlabs/ext4-rs","commit_stats":null,"previous_names":["arcboxlabs/ext4-rs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arcboxlabs/ext4-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcboxlabs%2Fext4-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcboxlabs%2Fext4-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcboxlabs%2Fext4-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcboxlabs%2Fext4-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arcboxlabs","download_url":"https://codeload.github.com/arcboxlabs/ext4-rs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcboxlabs%2Fext4-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33634611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","ext4","filesystem","mkfs","oci","rust","userspace"],"created_at":"2026-05-29T02:30:18.893Z","updated_at":"2026-05-29T02:30:19.883Z","avatar_url":"https://github.com/arcboxlabs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003earcbox-ext4\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    Pure-Rust ext4 filesystem formatter and reader.\u003cbr\u003e\n    No kernel mount. No FUSE. No C dependencies.\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://crates.io/crates/arcbox-ext4\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/arcbox-ext4.svg\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.rs/arcbox-ext4\"\u003e\u003cimg src=\"https://docs.rs/arcbox-ext4/badge.svg\" alt=\"docs.rs\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE-MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n`arcbox-ext4` creates and reads ext4 filesystem images entirely in userspace. It is designed for one job: converting OCI container image layers into mountable ext4 block devices on macOS and Linux, without needing `mkfs.ext4`, `libext2fs`, or any Linux tools on the host.\n\nThis is the first pure-Rust ext4 mkfs implementation.\n\n## Why\n\nContainer runtimes on macOS need to build ext4 root filesystems from OCI image layers. The standard approach requires either shelling out to Linux `mkfs.ext4` (not available on macOS) or linking against C libraries like `lwext4`. This crate does it in pure Rust.\n\nInspired by [Apple's ContainerizationEXT4](https://github.com/apple/containerization) (the Swift ext4 implementation in Apple's open-source container runtime), then audited line-by-line against it and the ext4 spec.\n\n## Features\n\n| | |\n|---|---|\n| **Formatter** | Create ext4 images from scratch -- superblock, group descriptors, inode table, bitmaps, extent trees |\n| **Reader** | Open existing ext4 images -- path resolution, symlink following, file reading |\n| **OCI Unpack** | Stream tar layers directly into ext4 with full OCI whiteout support |\n| **Extended Attributes** | Inline (in-inode) and block-level xattrs with name compression |\n| **Hard Links** | Correct reference counting with deferred block reclamation |\n| **Symlinks** | Fast symlinks (inline, \u003c 60 bytes) and slow symlinks (data blocks) |\n\n## Quick Start\n\n```toml\n[dependencies]\narcbox-ext4 = \"0.1\"\n```\n\n### Create an ext4 image\n\n```rust\nuse std::path::Path;\nuse arcbox_ext4::{Formatter, constants::{make_mode, file_mode}};\n\nlet mut fmt = Formatter::new(Path::new(\"rootfs.ext4\"), 4096, 64 * 1024 * 1024)?;\n\n// Create directories and files.\nfmt.create(\"/etc\", make_mode(file_mode::S_IFDIR, 0o755),\n    None, None, None, None, None, None)?;\nfmt.create(\"/etc/hostname\", make_mode(file_mode::S_IFREG, 0o644),\n    None, None, Some(\u0026mut b\"arcbox\\n\".as_slice()), None, None, None)?;\n\n// Create a symlink.\nfmt.create(\"/etc/localtime\", make_mode(file_mode::S_IFLNK, 0o777),\n    Some(\"/usr/share/zoneinfo/UTC\"), None, None, None, None, None)?;\n\n// Finalize -- writes superblock, group descriptors, bitmaps, inode table.\nfmt.close()?;\n```\n\n### Read an ext4 image\n\n```rust\nuse arcbox_ext4::Reader;\n\nlet mut reader = Reader::new(std::path::Path::new(\"rootfs.ext4\"))?;\n\n// Check existence, list directories, read files.\nassert!(reader.exists(\"/etc/hostname\"));\nlet entries = reader.list_dir(\"/etc\")?;\nlet data = reader.read_file(\"/etc/hostname\", 0, None)?;\nassert_eq!(\u0026data, b\"arcbox\\n\");\n```\n\n### Unpack OCI layers\n\n```rust\nuse arcbox_ext4::Formatter;\n\nlet mut fmt = Formatter::new(path, 4096, 512 * 1024 * 1024)?;\n\n// Apply layers in order. Whiteouts (.wh.* and .wh..wh..opq) are handled.\nfmt.unpack_tar(layer1_reader)?;\nfmt.unpack_tar(layer2_reader)?;\n\nfmt.close()?;\n```\n\n## Architecture\n\n```\n                    ┌─────────────┐\n  OCI tar layers ──▶│  unpack.rs  │\n                    └──────┬──────┘\n                           ▼\n                    ┌─────────────┐         ┌─────────────┐\n    user code ────▶ │ formatter.rs│────────▶│   .ext4     │\n                    └─────────────┘  close()│   image     │\n                                            └──────┬──────┘\n                                                   ▼\n                                            ┌─────────────┐\n                    user code ────────────▶ │  reader.rs  │\n                                            └─────────────┘\n```\n\nInternally, the formatter writes data sequentially (files, then directories, then metadata) and computes the final layout at `close()` time:\n\n1. File/symlink data blocks are appended as `create()` is called\n2. Directory entries are committed in BFS order (sorted for `e2fsck`)\n3. Block group layout is optimized to minimize group count\n4. Inode table, block/inode bitmaps, group descriptors, and superblock are written last\n\n## ext4 Feature Flags\n\n| Flag | Status |\n|------|--------|\n| `extents` | Enabled (extent trees, not legacy block maps) |\n| `filetype` | Enabled (directory entries store file type) |\n| `flex_bg` | Enabled (flexible block groups) |\n| `sparse_super2` | Enabled |\n| `huge_file` | Enabled (block-unit `i_blocks` counting) |\n| `extra_isize` | Enabled (256-byte inodes with inline xattrs) |\n| `ext_attr` | Enabled |\n| `has_journal` | Not supported (not needed for container rootfs) |\n| `metadata_csum` | Not supported |\n| `64bit` | Not supported (32-bit block addresses, max 16 TiB) |\n\n## Limitations\n\n- Block size is fixed at **4096 bytes**\n- Maximum file size: **128 GiB**\n- Extent tree depth limited to **1** (sufficient for 128 GiB)\n- No journal -- images are meant to be built once and mounted read-only (or read-write without crash recovery)\n\n## Testing\n\n133 tests covering:\n- Struct serialization round-trips for all on-disk types\n- Formatter + Reader end-to-end (files, dirs, symlinks, hardlinks, xattrs)\n- OCI two-layer rootfs simulation (Alpine-like)\n- Low-level struct validation (superblock fields, group descriptors, bitmaps, inode table)\n- Error paths, symlink loops, boundary conditions\n- Bug regression tests (hardlink reclaim, symlink classification, block counting)\n\n```sh\ncargo test\n```\n\n## Acknowledgments\n\nArchitecture inspired by Apple's [ContainerizationEXT4](https://github.com/apple/containerization) Swift implementation, then audited line-by-line against it and the [ext4 disk layout specification](https://ext4.wiki.kernel.org/index.php/Ext4_Disk_Layout).\n\n## License\n\nLicensed under either of\n\n- [Apache License, Version 2.0](LICENSE-APACHE)\n- [MIT License](LICENSE-MIT)\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcboxlabs%2Fext4-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farcboxlabs%2Fext4-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcboxlabs%2Fext4-rs/lists"}