EROFS(5)

NAME
erofs - Enhanced Read-Only File System

SYNOPSIS
To mount an
erofs volume:

    mount -t erofs /dev/da0 /mnt

DESCRIPTION
The erofs driver provides read-only support for the Enhanced Read-Only File System (EROFS), a modern compressed read-only filesystem designed for space efficiency and performance. EROFS is widely used in Linux distributions and mobile systems for root filesystems, firmware images, and container layers.

The FreeBSD implementation supports multiple compression algorithms, various data layouts, extended attributes, and multi-device configurations.

The currently qualified build target is FreeBSD 15 on amd64. The module Makefile rejects other architectures because they have not been validated against this implementation's kernel ABI.

FEATURES

  Inode Types
The erofs driver supports both compact and extended inode formats:
•   Compact inodes (32 bytes) for typical files
•   Extended inodes (64 bytes) with extended metadata
•   Special handling for single-link files
•   Inline data (tailpacking) for small files

  Data Layouts
•   FLAT_PLAIN: Uncompressed contiguous data
•   FLAT_INLINE: Uncompressed data with inline tail
•   Chunk-based: Fixed-size chunks for multi-device support
•   Compressed: LZ4, DEFLATE, zstd, or LZMA compressed data with pcluster mapping

  Compression Algorithms

LZ4 Fast decompression for general-purpose use, including ztailpacking (compressed tail in inode metadata)

DEFLATE
    Standard compression with good compression ratio

zstd
    High compression ratio when the module is built with WITH_ZSTDIO=1. ZSTD support is disabled by default (WITH_ZSTDIO=0), and an enabled module requires a kernel built with options ZSTDIO.

LZMA/MicroLZMA
    Maximum compression ratio for space-constrained environments

  Extended Attributes
•   Shared extended attributes with metabox container support
•   Inline extended attributes
•   Long-prefix extended attribute support
•   Packed prefix table support
•   POSIX ACL support (access and default ACLs)

User namespace attributes are exposed without prefix; system namespace attributes retain their full qualified names (trusted.*, security.*).

Linux POSIX access/default ACL xattrs are decoded into FreeBSD POSIX.1e ACLs when present. ACL and xattr mutation remains read-only.

  Advanced Features
•   Superblock CRC32C verification
•   48-bit block count and root nid support
•   Device table for multi-device volumes
•   Qualified fragment-backed compressed files and metabox carriers
•   VFS hash integration and namecache support
•   Directory entry optimization (dot_omitted handling)
•   NFS export with stable superblock-seeded per-inode file-handle generations
•   FreeBSD local vnode pager support for read-only mappings

MOUNT OPTIONS
The erofs filesystem supports standard read-only mount options and the following filesystem-specific option:

device.N=path
    Map one-based on-disk external device slot N to the disk provider at path. The slot number is part of the option name, so option order has no effect. Every declared external slot must be supplied exactly once when external blob providers are used. Reusing the primary provider or one external provider for multiple slots is rejected.

There is no filesystem-specific /sbin/mount_erofs utility in this repository. Use the generic mount(8) frontend with -t erofs; it passes the filesystem-specific option names to nmount(2).

If the image has a device table and no device.N options are supplied, the primary provider is treated as a flatdev image. It must contain every declared device range at its on-disk unified block address. The driver forces every successful mount read-only. An explicit -o rw request therefore still produces a read-only mount; it does not enable writes and is not rejected solely because rw was requested. Mutating vnode operations fail with EROFS.

EXAMPLES
Mount an EROFS image from a disk device:

    mount -t erofs -o ro /dev/da0s1 /mnt

Mount an EROFS image from a regular file using mdconfig(8):

    mdconfig -a -t vnode -f rootfs.img -u 0
    mount -t erofs -o ro /dev/md0 /mnt

Mount a split image with two external blob slots. The deliberately reversed option order demonstrates that slot mapping is deterministic:

    mdconfig -a -t vnode -f primary.img -u 90
    mdconfig -a -t vnode -f blob1.img -u 91
    mdconfig -a -t vnode -f blob2.img -u 92
    mount -t erofs -o ro -o device.2=/dev/md92     -o device.1=/dev/md91 /dev/md90 /mnt

Mount a flatdev image containing the primary image followed by all declared unified device ranges:

    mdconfig -a -t vnode -f combined-flatdev.img -u 90
    mount -t erofs -o ro /dev/md90 /mnt

Unmount an EROFS filesystem:

    umount /mnt

DIAGNOSTICS
Error messages are logged via printf(9) when filesystem inconsistencies are detected, such as:
•   Invalid superblock magic number
•   Superblock CRC32C checksum mismatch
•   Unsupported compression algorithm
•   Invalid inode format
•   Invalid or unrepresentable inode timestamps
•   Corrupted directory entries
•   Compressed extent address arithmetic overflow
•   Inline data crossing its inode metadata block or declared backing bounds
•   Missing, short, or orphaned external providers
•   Malformed or overlapping device-table ranges

SEE ALSO
nmount(2), mdconfig(8), mount(8), umount(8), printf(9)

HISTORY
EROFS was originally developed for Linux by Huawei in 2019. The FreeBSD implementation first appeared in 2026.

AUTHORS
Ruicheng Pan

BUGS
•   The driver is read-only and does not claim support for every future EROFS incompat feature or every dedupe encoding.
•   There is no automated kernel regression harness; the repository records FreeBSD 15 manual-test procedures and results.