272 lines
7.5 KiB
Plaintext
272 lines
7.5 KiB
Plaintext
.\" Copyright (c) 2026
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd August 9, 2026
|
|
.Dt EROFS 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm erofs
|
|
.Nd Enhanced Read-Only File System
|
|
.Sh SYNOPSIS
|
|
To mount an
|
|
.Nm
|
|
volume:
|
|
.Bd -literal -offset indent
|
|
mount -t erofs /dev/da0 /mnt
|
|
.Ed
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
The
|
|
.Fx
|
|
implementation supports multiple compression algorithms, various data layouts,
|
|
extended attributes, and multi-device configurations.
|
|
.Pp
|
|
The currently qualified build target is
|
|
.Fx 15
|
|
on
|
|
.Sy amd64 .
|
|
The module Makefile rejects other architectures because they have not been
|
|
validated against this implementation's kernel ABI.
|
|
.Sh FEATURES
|
|
.Ss Inode Types
|
|
The
|
|
.Nm
|
|
driver supports both compact and extended inode formats:
|
|
.Bl -bullet -compact
|
|
.It
|
|
Compact inodes (32 bytes) for typical files
|
|
.It
|
|
Extended inodes (64 bytes) with extended metadata
|
|
.It
|
|
Special handling for single-link files
|
|
.It
|
|
Inline data (tailpacking) for small files
|
|
.El
|
|
.Ss Data Layouts
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Sy FLAT_PLAIN :
|
|
Uncompressed contiguous data
|
|
.It
|
|
.Sy FLAT_INLINE :
|
|
Uncompressed data with inline tail
|
|
.It
|
|
.Sy Chunk-based :
|
|
Fixed-size chunks for multi-device support
|
|
.It
|
|
.Sy Compressed :
|
|
LZ4, DEFLATE, zstd, or LZMA compressed data with pcluster mapping
|
|
.El
|
|
.Ss Compression Algorithms
|
|
.Bl -tag -width "MicroLZMA"
|
|
.It Sy LZ4
|
|
Fast decompression for general-purpose use, including ztailpacking
|
|
(compressed tail in inode metadata)
|
|
.It Sy DEFLATE
|
|
Standard compression with good compression ratio
|
|
.It Sy zstd
|
|
High compression ratio when the module is built with
|
|
.Va WITH_ZSTDIO=1 .
|
|
ZSTD support is disabled by default
|
|
.Pq Va WITH_ZSTDIO=0 ,
|
|
and an enabled module requires a kernel built with
|
|
.Cd "options ZSTDIO" .
|
|
.It Sy LZMA/MicroLZMA
|
|
Maximum compression ratio for space-constrained environments
|
|
.El
|
|
.Ss Extended Attributes
|
|
.Bl -bullet -compact
|
|
.It
|
|
Shared extended attributes with metabox container support
|
|
.It
|
|
Inline extended attributes
|
|
.It
|
|
Long-prefix extended attribute support
|
|
.It
|
|
Packed prefix table support
|
|
.It
|
|
POSIX ACL support (access and default ACLs)
|
|
.El
|
|
.Pp
|
|
User namespace attributes are exposed without prefix; system namespace
|
|
attributes retain their full qualified names (trusted.*, security.*).
|
|
.Pp
|
|
Linux POSIX access/default ACL xattrs are decoded into
|
|
.Fx
|
|
POSIX.1e ACLs when present.
|
|
ACL and xattr mutation remains read-only.
|
|
.Ss Advanced Features
|
|
.Bl -bullet -compact
|
|
.It
|
|
Superblock CRC32C verification
|
|
.It
|
|
48-bit block count and root nid support
|
|
.It
|
|
Device table for multi-device volumes
|
|
.It
|
|
Qualified fragment-backed compressed files and metabox carriers
|
|
.It
|
|
VFS hash integration and namecache support
|
|
.It
|
|
Directory entry optimization (dot_omitted handling)
|
|
.It
|
|
NFS export with stable superblock-seeded per-inode file-handle generations
|
|
.It
|
|
.Fx
|
|
local vnode pager support for read-only mappings
|
|
.El
|
|
.Sh MOUNT OPTIONS
|
|
The
|
|
.Nm
|
|
filesystem supports standard read-only mount options and the following
|
|
filesystem-specific option:
|
|
.Bl -tag -width "device.N=/dev/mdN"
|
|
.It Cm device.N= Ns Pa path
|
|
Map one-based on-disk external device slot
|
|
.Ar N
|
|
to the disk provider at
|
|
.Ar 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.
|
|
.El
|
|
.Pp
|
|
There is no filesystem-specific
|
|
.Pa /sbin/mount_erofs
|
|
utility in this repository.
|
|
Use the generic
|
|
.Xr mount 8
|
|
frontend with
|
|
.Fl t Cm erofs ;
|
|
it passes the filesystem-specific option names to
|
|
.Xr nmount 2 .
|
|
.Pp
|
|
If the image has a device table and no
|
|
.Cm 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
|
|
.Fl o Cm rw
|
|
request therefore still produces a read-only mount; it does not enable writes
|
|
and is not rejected solely because
|
|
.Cm rw
|
|
was requested.
|
|
Mutating vnode operations fail with
|
|
.Er EROFS .
|
|
.Sh EXAMPLES
|
|
Mount an EROFS image from a disk device:
|
|
.Bd -literal -offset indent
|
|
mount -t erofs -o ro /dev/da0s1 /mnt
|
|
.Ed
|
|
.Pp
|
|
Mount an EROFS image from a regular file using
|
|
.Xr mdconfig 8 :
|
|
.Bd -literal -offset indent
|
|
mdconfig -a -t vnode -f rootfs.img -u 0
|
|
mount -t erofs -o ro /dev/md0 /mnt
|
|
.Ed
|
|
.Pp
|
|
Mount a split image with two external blob slots.
|
|
The deliberately reversed
|
|
option order demonstrates that slot mapping is deterministic:
|
|
.Bd -literal -offset indent
|
|
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
|
|
.Ed
|
|
.Pp
|
|
Mount a flatdev image containing the primary image followed by all declared
|
|
unified device ranges:
|
|
.Bd -literal -offset indent
|
|
mdconfig -a -t vnode -f combined-flatdev.img -u 90
|
|
mount -t erofs -o ro /dev/md90 /mnt
|
|
.Ed
|
|
.Pp
|
|
Unmount an EROFS filesystem:
|
|
.Bd -literal -offset indent
|
|
umount /mnt
|
|
.Ed
|
|
.Sh DIAGNOSTICS
|
|
Error messages are logged via
|
|
.Xr printf 9
|
|
when filesystem inconsistencies are detected, such as:
|
|
.Bl -bullet -compact
|
|
.It
|
|
Invalid superblock magic number
|
|
.It
|
|
Superblock CRC32C checksum mismatch
|
|
.It
|
|
Unsupported compression algorithm
|
|
.It
|
|
Invalid inode format
|
|
.It
|
|
Invalid or unrepresentable inode timestamps
|
|
.It
|
|
Corrupted directory entries
|
|
.It
|
|
Compressed extent address arithmetic overflow
|
|
.It
|
|
Inline data crossing its inode metadata block or declared backing bounds
|
|
.It
|
|
Missing, short, or orphaned external providers
|
|
.It
|
|
Malformed or overlapping device-table ranges
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr nmount 2 ,
|
|
.Xr mdconfig 8 ,
|
|
.Xr mount 8 ,
|
|
.Xr umount 8 ,
|
|
.Xr printf 9
|
|
.Sh HISTORY
|
|
EROFS was originally developed for Linux by Huawei in 2019.
|
|
The
|
|
.Fx
|
|
implementation first appeared in 2026.
|
|
.Sh AUTHORS
|
|
.An Ruicheng Pan
|
|
.Sh BUGS
|
|
.Bl -bullet -compact
|
|
.It
|
|
The driver is read-only and does not claim support for every future EROFS
|
|
incompat feature or every dedupe encoding.
|
|
.It
|
|
There is no automated kernel regression harness; the repository records
|
|
.Fx 15
|
|
manual-test procedures and results.
|
|
.El
|