Jump to content

EROFS

From Wikipedia, the free encyclopedia
EROFS
DeveloperEROFS filesystem community
Full nameEnhanced Read-Only File System
Introducedwith Linux 5.4
Structures
Directory contentsSorted directory entries
Limits
Max volume size1 EiB with 4 KiB blocks and 48-bit block addressing[1]
Max file size
  • 4 GiB minus 1 byte (compact inode)
  • 64-bit size field (extended inode; subject to filesystem and implementation limits)[2]
Max no. of filesDepends on image size and layout
Max filename length255 bytes
Features
Dates recordedModification time; representation depends on inode format and enabled features
Date resolution1 ns for extended-inode timestamps[2]
AttributesUnix attributes, extended file attributes
File system
permissions
Unix permissions, POSIX ACLs
Transparent
compression
Optional, per inode: LZ4, MicroLZMA, DEFLATE, Zstandard
Data deduplicationUncompressed chunks and compressed extents
Other
Supported
operating systems
Linux

EROFS (Enhanced Read-Only File System) is a modern immutable (read-only) file system for the Linux kernel. It was initially proposed by Huawei to address the performance and memory-use limitations of SquashFS on Android smartphones.[3] It is now maintained by an international open-source file system community.

EROFS and its userspace tools, receive contributions from developers at Alibaba Group, ByteDance, Coolpad, DeepSeek, Docker, Google, Huawei, NVIDIA, OPPO, Red Hat, Shanghai Jiao Tong University, Tencent, vivo, Xiaomi, and more.[4][5]

EROFS is designed for operating-system images, container images, application sandboxes, virtual-machine snapshot images, and dataset distribution.[1][6] It combines a compact, block-based format with optional transparent compression, data deduplication, and native layering, aiming to balance storage efficiency with read performance and memory use. Its security design minimizes redundant metadata and requires the implementation to handle corrupt or deliberately crafted images without compromising kernel safety.[1]

EROFS has been available in the Linux kernel since Linux 5.4.[7]

Features

[edit]

Core features

[edit]

EROFS supports Unix ownership and permissions, hard links, symbolic links, device nodes, extended file attributes, and POSIX access-control lists. Extended attributes can be stored inline or shared between inodes.

Uncompressed file data is block-aligned, except for inline data, allowing memory mapping, direct I/O, and filesystem direct access (DAX)[8] where supported by the backing device. Small files and file tails can be stored alongside inode metadata. Optional 48-bit block addressing, supported since Linux 6.15, permits filesystem capacities of up to 1 EiB with 4 KiB blocks.[1]

Compression

[edit]

Compression is optional and can be selected per inode. Supported algorithms include LZ4, MicroLZMA (since Linux 5.16), DEFLATE (since Linux 6.6), and Zstandard (since Linux 6.10). Optional metadata compression has been supported since Linux 6.17. Hardware-accelerated DEFLATE decompression using Intel QuickAssist Technology has been supported since Linux 6.16.[9]

EROFS primarily uses fixed-size output compression, compressing variable amounts of input into block-aligned physical clusters. In-place decompression reduces temporary buffering. Larger physical clusters can improve compression ratios, with potential costs in memory use and random-access performance. File tails can be inlined into metadata or packed together as fragments in a special inode.[10][1]

Deduplication

[edit]

Uncompressed inodes can share fixed-size data chunks. Compressed inodes can share variable-size extents, with rolling hashes used during image creation to identify reusable data and adjust extent boundaries. Both mechanisms allow portions of files to be shared without requiring the entire files to be identical.[10]

Mounting and layering

[edit]

EROFS images can be mounted from block devices or, since Linux 6.12, directly from regular files without a loop device. An earlier fscache-based mechanism was introduced in Linux 5.19 and deprecated in Linux 6.12.[9] It was removed in Linux 7.2.[11]

Inodes can reference external data on additional block devices or in file blobs, allowing images to share payloads. Native sub-filesystem merging can combine external payloads into a single filesystem view, using either a composite device or multiple backing devices. Explicit multiple-device support was introduced in Linux 5.16.[12] OverlayFS can provide a writable layer over an immutable EROFS image.[1]

Memory optimizations

[edit]

Since Linux 7.0, inode-based page-cache sharing, enabled with the inode_share mount option, allows inodes with identical content fingerprints to share cached file data. Sharing across mounts requires a common private domain identifier (domain_id), which is treated as sensitive and omitted from mount information.[1]

Large folios are supported for uncompressed inodes since Linux 6.2 and compressed inodes since Linux 6.11.[9]

On-disk format

[edit]

Layout

[edit]

EROFS uses a little-endian format whose core metadata consists of a superblock, inodes, and directory entries. The superblock begins at byte offset 1024. Inodes and directories do not require centralized tables, allowing metadata and file data to be interleaved and arranged for incremental image construction.

Inodes use either a 32-byte compact layout or a 64-byte extended layout. Compact inodes have 32-bit file-size fields and 16-bit user and group identifiers. Extended inodes have 64-bit file-size fields, 32-bit identifiers, and individual nanosecond-resolution timestamps. Directory entries are sorted lexicographically by filename within each directory block.

The core format supports uncompressed images, while features such as compression and chunk-based data layouts are optional extensions.[2] Compressed inode and shared extended-attribute metadata can be stored through a hidden inode called the metabox.[1]

Handling of crafted images

[edit]

The Linux kernel's general threat model treats bugs triggered by mounting corrupt or maliciously crafted filesystem images as ordinary bugs rather than security vulnerabilities, unless the filesystem is explicitly documented as hardened against hostile inputs. Mounting a block device is a privileged operation, and administrators are responsible for the media they mount.[13]

The EROFS on-disk format is designed with corrupt and deliberately crafted images in scope. The format minimizes redundant metadata representations to reduce cross-structure consistency invariants that the implementation must validate for runtime safety. Its safety requirement is that malformed metadata may produce invalid filesystem contents or errors, but its effects must remain confined to the data and metadata exposed to userspace. Upstream EROFS development therefore requires implementation hardening against crafted images, a stricter policy than the general Linux filesystem threat model.[1]

Adoption

[edit]

Android

[edit]

EROFS is used for read-only system partitions on Android devices from manufacturers including Coolpad, Honor, Huawei, Motorola, Samsung, OPPO, Xiaomi, and vivo.[14] The Android Open Source Project supports building EROFS partition images and using them with Virtual A/B updates.[15]

Container images

[edit]

Composefs, the EROFS snapshotter for containerd,[16] and Dragonfly Nydus use EROFS for immutable image storage and distribution. EROFS is also supported by gVisor and Kata Containers.[7]

AI infrastructure

[edit]

EROFS is used in sandbox systems for AI agents.[7] Ray Sandboxes cache container root filesystems as EROFS images mounted by gVisor.[17] DeepSeek Elastic Compute (DSec) stores immutable environment layers in EROFS and loads file data on demand from its 3FS distributed filesystem.[18] TencentOS EROX uses EROFS for a unified data plane covering images, disks, workspaces, and snapshots.[6]

Linux distributions

[edit]

Fedora Linux adopted EROFS for KIWI-produced live images and Fedora CoreOS live media beginning with Fedora 42.[19] Image-building tools supporting EROFS include Archiso, CoreOS Assembler, dracut-ng, and KIWI.[7]

See also

[edit]

References

[edit]
  1. 1 2 3 4 5 6 7 8 9 "EROFS - Enhanced Read-Only File System". The Linux Kernel documentation. Retrieved 2026-11-19.
  2. 1 2 3 "Core On-disk Format". EROFS filesystem project. Retrieved 2026-11-19.
  3. ↑ Gao, Xiang; Dong, Mingkai; Miao, Xie; Du, Wei; Yu, Chao; Chen, Haibo (2019). "EROFS: A Compression-friendly Readonly File System for Resource-scarce Devices" (PDF). 2019 USENIX Annual Technical Conference. USENIX Association. pp. 149–162.
  4. ↑ "Contributors". EROFS filesystem project. Retrieved 2026-11-19.
  5. ↑ "erofs-utils commit history". kernel.org. Retrieved 2026-11-19.
  6. 1 2 "Agent Infra,关键瓶颈是数据恢复—— TencentOS EROX 统一数据面实践". Zhihu (in Chinese). Retrieved 2026-11-19.
  7. 1 2 3 4 "Overview". EROFS filesystem project. Retrieved 2026-11-19.
  8. ↑ "Direct Access for files — The Linux Kernel documentation". docs.kernel.org. Retrieved 2026-11-19.
  9. 1 2 3 "Features and Comparison". EROFS filesystem project. Retrieved 2026-11-19.
  10. 1 2 "Technical Design". EROFS filesystem project. Retrieved 2026-11-19.
  11. ↑ "erofs: remove fscache backend entirely". Linux kernel source repository. 2026-06-22. Retrieved 2026-11-19.
  12. ↑ "Native sub-filesystem merging". EROFS filesystem project. Retrieved 2026-11-19.
  13. ↑ "The Linux Kernel threat model". The Linux Kernel documentation. Retrieved 2026-11-19.
  14. ↑ "Bootable system images". EROFS filesystem project. Retrieved 2026-11-19.
  15. ↑ "EROFS". Android Open Source Project. Retrieved 2026-11-19.
  16. ↑ "EROFS snapshotter". containerd documentation. Retrieved 2026-11-19.
  17. ↑ "Ray Sandboxes". Ray documentation. Retrieved 2026-11-19.
  18. ↑ Huang, Jialiang; Tang, Hongxuan; Chen, Jingchang; et al. (2026). "DeepSeek Elastic Compute (DSec): A Sandbox Infrastructure for Effective Agentic Training at Scale". arXiv:2609.22978 [cs.DC].
  19. ↑ "Switch to EROFS for Live Media". Fedora Project Wiki. Retrieved 2026-11-19.
[edit]