Mount EROFS Images with Predictable Read-Only Options

You will finish with a repeatable way to mount an EROFS image, inspect its effective options, and avoid treating read-only as permission to alter the source. The examples follow the installed Linux man-pages 6.7 description of EROFS. Allow about ten minutes for a known image and an empty mount point.

You need a Linux kernel with CONFIG_EROFS_FS, the image path, and a mount point. Mounting needs elevated privileges unless your system has deliberately delegated that operation. The filesystem itself is create-once and read-only: use another filesystem, such as an overlay upper layer, if an application needs to write.

1. Check the local contract

Read the installed manual before copying an option from a different kernel or distribution. This is an ordinary, read-only command:

$ man 5 erofs
$ dpkg-query -W -f='${Package} ${Version}\n' manpages
manpages 6.7-2

The local page is dated 31 October 2023 and describes two inode formats, compressed-file cache strategies, DAX, extra devices, extended attributes and POSIX ACLs. The kernel documentation is useful for newer details, but the local page is the authority for what this machine's installed reference records.

Checkpoint: confirm that the kernel exposes EROFS before planning a mount:

$ grep CONFIG_EROFS_FS /boot/config-$(uname -r)
CONFIG_EROFS_FS=m

Your result may be y, m, or absent. An absent setting means the running kernel cannot mount EROFS. A module setting means the module must be available and loadable; do not assume that installing a user-space utility changes the kernel.

2. Prepare a mount point without touching the image

Choose a directory that does not contain files you need. Creating a directory under /mnt changes system state and normally needs sudo:

$ sudo install -d -m 0755 /mnt/erofs-image
$ sudo test -z "$(find /mnt/erofs-image -mindepth 1 -maxdepth 1 -print -quit)"
$ printf 'mount point is empty\n'
mount point is empty

Do not mount over a non-empty directory just to make the command succeed. Its old contents become hidden until unmounting, which is an easy source of confusion. If you created this directory only for the test, remove it after unmounting with sudo rmdir /mnt/erofs-image. That removes the directory, not the image.

3. Mount with the default behaviour first

Replace /path/to/image.erofs with an image you trust and keep the mount point as a separate argument. This changes kernel mount state, so it needs elevated privileges:

$ sudo mount -t erofs /path/to/image.erofs /mnt/erofs-image

The default options in the installed page are user_xattr, acl, cache_strategy=readaround, and DAX unset, which is equivalent to dax=never. Those defaults do not make the filesystem writable and do not enable direct access.

Checkpoint: verify that the mount is the one you requested:

$ findmnt -t erofs -T /mnt/erofs-image
TARGET             SOURCE                     FSTYPE OPTIONS
/mnt/erofs-image   /path/to/image.erofs       erofs  ro,relatime
$ findmnt -no FSTYPE,OPTIONS -T /mnt/erofs-image
erofs ro,relatime

The exact source spelling and option list vary. The useful checks are the erofs type and the ro flag. Read a file to test access without changing the image:

$ stat /mnt/erofs-image/KNOWN_FILE
$ head -c 32 /mnt/erofs-image/KNOWN_FILE > /dev/null

Replace KNOWN_FILE with a path that exists in your image. A missing path says nothing about the mount itself.

4. Choose compressed-file caching deliberately

cache_strategy controls cache allocation while compressed files are read. The installed page defines three values:

• disabled never allocates this cache.
• readahead caches when reading from the start of a file, regardless of the position.
• readaround is the default.

Use an explicit value when reproducibility matters. For example, this remount keeps the image read-only while selecting the documented conservative setting:

$ sudo mount -o remount,cache_strategy=disabled /mnt/erofs-image
$ findmnt -no FSTYPE,OPTIONS -T /mnt/erofs-image
erofs ro,relatime,cache_strategy=disabled

Remounting changes live mount behaviour. If the option is rejected, keep the original mount and consult the local page and kernel support rather than repeatedly adding options. To return to the documented default, unmount and mount again without cache_strategy:

$ sudo umount /mnt/erofs-image
$ sudo mount -t erofs /path/to/image.erofs /mnt/erofs-image

5. Treat DAX as a hardware-dependent choice

DAX bypasses the page cache for uncompressed, non-inlined files when the source device supports it. The accepted forms are dax, dax=always, and dax=never. The default is equivalent to dax=never. Do not add dax as a performance guess: the source device and the files must support the requested path.

If you have verified those prerequisites and deliberately want DAX, specify it at mount time:

$ sudo umount /mnt/erofs-image
$ sudo mount -t erofs -o dax=always /path/to/image.erofs /mnt/erofs-image
$ findmnt -no FSTYPE,OPTIONS -T /mnt/erofs-image
erofs ro,relatime,dax=always

If the mount fails, remove the DAX option and test the ordinary page-cache path. Do not infer that a successful mount means every file uses DAX; compressed and inlined files are excluded by the documented conditions.

6. Handle multi-device images in the recorded order

An EROFS image can refer to extra devices. The mount option is device=blobdev, repeated for each extra device. The order must match the order used by --blobdev when the image was created:

$ sudo mount -t erofs \
    -o device=/dev/EXTRA_DEVICE_1,device=/dev/EXTRA_DEVICE_2 \
    /path/to/image.erofs /mnt/erofs-image

This is a security-sensitive boundary. Confirm each device path with lsblk and the image's build record before using sudo. A wrong block device can expose unrelated data or make the mount fail. Never substitute guessed devices, and do not repartition, format or write to them as part of this test.

7. Unmount and recover cleanly

When finished, leave the image unmounted unless a service needs it:

$ sudo umount /mnt/erofs-image
$ findmnt -T /mnt/erofs-image || printf 'not mounted\n'
not mounted
$ sudo rmdir /mnt/erofs-image

If unmounting reports that the target is busy, close shells and files whose current directory is below the mount, stop readers, then retry. Do not use a forced or lazy unmount merely to hide an active workload. Check fuser -vm /mnt/erofs-image to identify holders before deciding how to stop them.