On 2025/12/2 11:08, ChengyuZhu6 wrote:
From: Chengyu Zhu <[email protected]>
Add manpage, command-line usage help, and README for
mount.erofs tool.
Signed-off-by: Chengyu Zhu <[email protected]>
---
README | 26 ++++++
man/Makefile.am | 2 +-
man/mount.erofs.1 | 202 ++++++++++++++++++++++++++++++++++++++++++++++
mount/main.c | 41 +++++++++-
4 files changed, 269 insertions(+), 2 deletions(-)
create mode 100644 man/mount.erofs.1
diff --git a/README b/README
index b885fa8..784bd50 100644
--- a/README
+++ b/README
@@ -4,6 +4,7 @@ erofs-utils
Userspace tools for EROFS filesystem, currently including:
mkfs.erofs filesystem formatter
+ mount.erofs mount helper for EROFS
erofsfuse FUSE daemon alternative
dump.erofs filesystem analyzer
fsck.erofs filesystem compatibility & consistency checker as well
@@ -206,6 +207,31 @@
git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git -b obsoleted
PLEASE NOTE: This version is highly _NOT recommended_ now.
+mount.erofs
+-----------
+
+mount.erofs is a mount helper for EROFS filesystem, which can be used
+to mount EROFS images with various backends including direct kernel
+mount, FUSE-based mount, and NBD for remote sources like OCI images.
+
+How to mount an EROFS image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To mount an EROFS image directly:
+ $ mount.erofs foo.erofs.img /mnt
$ mount.erofs foo.erofs mnt
+
+To mount with FUSE backend:
+ $ mount.erofs -t erofs.fuse foo.erofs.img /mnt
$ mount.erofs -t erofs.fuse foo.erofs mnt
+
+To mount from OCI image with NBD backend:
+ $ mount.erofs -t erofs.nbd -o oci.blob=sha256:... image:tag /mnt
$ mount.erofs -t erofs.nbd -o oci.blob=sha256:... <IMAGE>:<TAG> mnt
+
+To unmount:
To unmount an EROFS filesystem:
+ $ mount.erofs -u /mnt
$ mount.erofs -u mnt
+
+For more details, see mount.erofs(1) manpage.
+
+
erofsfuse
---------
diff --git a/man/Makefile.am b/man/Makefile.am
index 4628b85..2990e77 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,6 +1,6 @@
# SPDX-License-Identifier: GPL-2.0+
-dist_man_MANS = mkfs.erofs.1 dump.erofs.1 fsck.erofs.1
+dist_man_MANS = mkfs.erofs.1 dump.erofs.1 fsck.erofs.1 mount.erofs.1
EXTRA_DIST = erofsfuse.1
if ENABLE_FUSE
diff --git a/man/mount.erofs.1 b/man/mount.erofs.1
new file mode 100644
index 0000000..6eeb48c
--- /dev/null
+++ b/man/mount.erofs.1
@@ -0,0 +1,202 @@
+.\" Copyright (c) 2025 Chengyu Zhu <[email protected]>
+.\"
+.TH MOUNT.EROFS 1
+.SH NAME
+mount.erofs \- manage EROFS filesystem
+.SH SYNOPSIS
+\fBmount.erofs\fR [\fIOPTIONS\fR] \fISOURCE\fR \fIMOUNTPOINT\fR
+.br
+\fBmount.erofs\fR \fB\-u\fR \fITARGET\fR
+.br
+\fBmount.erofs\fR \fB\-\-reattach\fR \fITARGET\fR
+.SH DESCRIPTION
+EROFS is an enhanced lightweight read-only filesystem with modern designs
+for scenarios which need high-performance read-only requirements.
+.PP
+\fBmount.erofs\fR is used to mount an EROFS filesystem from \fISOURCE\fR
+(which can be an image file or block device) to a \fIMOUNTPOINT\fR. It
supports multiple backends including
+direct kernel mount, FUSE-based mount, and NBD (Network Block Device) for
+remote sources like OCI images.
+.SH OPTIONS
+.TP
+.B \-h, \-\-help
+Display help message and exit.
+.TP
+.B \-V, \-\-version
+Display version information and exit.
+.TP
+.BI "\-o " options
+Comma-separated list of mount options. See \fBMOUNT OPTIONS\fR below.
+.TP
+.BI "\-t " type[.subtype]
+Specify the filesystem type and optional subtype. The type should be
+\fBerofs\fR. Available subtypes are:
+.RS
+.TP
+.B fuse
+Use FUSE-based mount via \fBerofsfuse\fR.
+.TP
+.B local
+Force direct kernel mount (default if available).
+.TP
+.B nbd
+Use NBD backend for remote sources (e.g., OCI images).
+.RE
+.TP
+.B \-u
+Unmount the filesystem at the specified target.
+.TP
+.B \-\-reattach
+Reattach to an existing NBD device and restart the NBD service.
+.SH MOUNT OPTIONS
+Standard mount options:
+.TP
+.B ro
+Mount the filesystem read-only (default).
+.TP
+.B rw
+Mount the filesystem read-write (not supported for EROFS).
+.TP
+.B nosuid
+Do not honor set-user-ID and set-group-ID bits.
+.TP
+.B suid
+Honor set-user-ID and set-group-ID bits (default).
+.TP
+.B nodev
+Do not interpret character or block special devices.
+.TP
+.B dev
+Interpret character or block special devices (default).
+.TP
+.B noexec
+Do not allow direct execution of any binaries.
+.TP
+.B exec
+Allow execution of binaries (default).
+.TP
+.B noatime
+Do not update inode access times.
+.TP
+.B atime
+Update inode access times (default).
+.TP
+.B nodiratime
+Do not update directory inode access times.
+.TP
+.B diratime
+Update directory inode access times (default).
+.TP
+.B relatime
+Update inode access times relative to modify or change time.
+.TP
+.B norelatime
+Do not use relative atime updates.
+.SH OCI-SPECIFIC OPTIONS
+The following OCI-specific options are available:
+.TP
+.BI "oci.blob=" digest
+Specify the OCI blob digest to mount. The digest should be in the format
+\fBsha256:...\fR. Cannot be used together with \fBoci.layer\fR.
+.TP
+.BI "oci.layer=" index
+Specify the OCI layer index to mount (0-based). Cannot be used together
+with \fBoci.blob\fR.
+.TP
+.BI "oci.platform=" platform
+Specify the target platform (default: \fBlinux/amd64\fR).
+.TP
+.BI "oci.username=" username
+Username for OCI registry authentication.
+.TP
+.BI "oci.password=" password
+Password for OCI registry authentication.
+.TP
+.BI "oci.tarindex=" path
+Path to a tarball index file for hybrid tar+OCI mode.
+.TP
+.BI "oci.zinfo=" path
+Path to a gzip zinfo file for random access to gzip-compressed tar layers.
+.SH EXAMPLES
Maybe just drop this part "EXAMPLES" since I'm not sure it
should be in the manpage.
+.SH NOTES
+.IP \(bu 2
+EROFS filesystems are read-only by nature. The \fBrw\fR option will be ignored.
+.IP \(bu 2
+When mounting OCI images via NBD, the mount process creates a background
+daemon to serve the NBD device. The daemon will automatically clean up when
+the filesystem is unmounted.
+.IP \(bu 2
+The \fB\-\-reattach\fR option is useful for recovering NBD mounts after a
+system crash or when the NBD daemon was terminated unexpectedly.
+.IP \(bu 2
+Loop device mounting is automatically used when mounting a regular file
+without specifying a backend type.
Kernel direct mount is used when mounting a regular file without
specifying a backend type. If file-based mounts is unsupported,
loop devices will be set up automatically.
+.SH SEE ALSO
+.BR mkfs.erofs (1),
+.BR erofsfuse (1),
+.BR dump.erofs (1),
+.BR fsck.erofs (1),
+.BR mount (8),
+.BR umount (8)
+.SH AVAILABILITY
+\fBmount.erofs\fR is part of erofs-utils.
diff --git a/mount/main.c b/mount/main.c
index e25134c..4dfa1d1 100644
--- a/mount/main.c
+++ b/mount/main.c
@@ -81,6 +81,38 @@ static struct erofs_nbd_source {
};
} nbdsrc;
+static void usage(int argc, char **argv)
+{
+ printf("Usage: %s [OPTIONS] SOURCE [MOUNTPOINT]\n"
+ "Manage EROFS filesystem.\n"
+ "\n"
+ "General options:\n"
+ " -V, --version print the version number of mount.erofs
and exit\n"
+ " -h, --help display this help and exit\n"
+ " -o options comma-separated list of mount
options\n"
+ " -t type[.subtype] filesystem type (and optional
subtype)\n"
+ " subtypes: fuse, local, nbd\n"
+ " -u unmount the filesystem\n"
+ " --reattach reattach to an existing NBD device\n"
+#ifdef OCIEROFS_ENABLED
+ "\n"
+ "OCI-specific options (with -o):\n"
+ " oci.blob=<digest> specify OCI blob digest (sha256:...)\n"
+ " oci.layer=<index> specify OCI layer index (0-based)\n"
0-based sounds odd, maybe find a better representation.
Thanks,
Gao Xiang
