[PATCH v4] erofs-utils: mount: add manpage and usage information
Yifan Zhao
zhaoyifan28 at huawei.com
Mon Dec 22 18:16:35 AEDT 2025
From: Chengyu Zhu <hudsonzhu at tencent.com>
Add manpage, command-line usage help, and README for
mount.erofs tool.
Signed-off-by: Chengyu Zhu <hudsonzhu at tencent.com>
Link: https://lore.kernel.org/r/20251202110315.14656-1-hudson@cyzhu.com
[ Gao Xiang: change the section number of the manpage to 8. ]
Signed-off-by: Gao Xiang <hsiangkao at linux.alibaba.com>
---
Hi Xiang,
Note that you have merged this patch. Could you consider merging this
patch instead for the experimental branch? The only difference is that
it also covers the newly added `oci.insecure` documents, see below.
Thanks,
Yifan Zhao
Interdiff against experimental:
diff --git a/man/mount.erofs.8 b/man/mount.erofs.8
index 6b3a32b..856e07f 100644
--- a/man/mount.erofs.8
+++ b/man/mount.erofs.8
@@ -117,6 +117,9 @@ 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.
+.TP
+.BI "oci.insecure"
+Use HTTP instead of HTTPS to access the image registry.
.SH NOTES
.IP \(bu 2
EROFS filesystems are read-only by nature. The \fBrw\fR option will be ignored.
diff --git a/mount/main.c b/mount/main.c
index ed6bcdc..6652cf5 100644
--- a/mount/main.c
+++ b/mount/main.c
@@ -105,6 +105,7 @@ static void usage(int argc, char **argv)
" oci.password=<pass> password for authentication (optional)\n"
" oci.tarindex=<path> path to tarball index file (optional)\n"
" oci.zinfo=<path> path to gzip zinfo file (optional)\n"
+ " oci.insecure use HTTP instead of HTTPS (optional)\n"
#endif
, argv[0]);
}
README | 26 +++++++++
man/Makefile.am | 2 +-
man/mount.erofs.8 | 145 ++++++++++++++++++++++++++++++++++++++++++++++
mount/main.c | 42 +++++++++++++-
4 files changed, 213 insertions(+), 2 deletions(-)
create mode 100644 man/mount.erofs.8
diff --git a/README b/README
index b885fa8..1ca376f 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 /mnt
+
+To mount with FUSE backend:
+ $ 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
+
+To unmount an EROFS filesystem:
+ $ mount.erofs -u mnt
+
+For more details, see mount.erofs(8) manpage.
+
+
erofsfuse
---------
diff --git a/man/Makefile.am b/man/Makefile.am
index 4628b85..b76b457 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.8
EXTRA_DIST = erofsfuse.1
if ENABLE_FUSE
diff --git a/man/mount.erofs.8 b/man/mount.erofs.8
new file mode 100644
index 0000000..856e07f
--- /dev/null
+++ b/man/mount.erofs.8
@@ -0,0 +1,145 @@
+.\" Copyright (c) 2025 Chengyu Zhu <hudsonzhu at tencent.com>
+.\"
+.TH MOUNT.EROFS 8
+.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.
+.TP
+.BI "oci.insecure"
+Use HTTP instead of HTTPS to access the image registry.
+.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
+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 893daf9..6652cf5 100644
--- a/mount/main.c
+++ b/mount/main.c
@@ -82,6 +82,39 @@ 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\n"
+ " oci.platform=<name> specify platform (default: linux/amd64)\n"
+ " oci.username=<user> username for authentication (optional)\n"
+ " oci.password=<pass> password for authentication (optional)\n"
+ " oci.tarindex=<path> path to tarball index file (optional)\n"
+ " oci.zinfo=<path> path to gzip zinfo file (optional)\n"
+ " oci.insecure use HTTP instead of HTTPS (optional)\n"
+#endif
+ , argv[0]);
+}
+
+static void version(void)
+{
+ printf("mount.erofs (erofs-utils) %s\n", cfg.c_version);
+}
+
#ifdef OCIEROFS_ENABLED
static int erofsmount_parse_oci_option(const char *option)
{
@@ -237,6 +270,7 @@ static int erofsmount_parse_options(int argc, char **argv)
{
static const struct option long_options[] = {
{"help", no_argument, 0, 'h'},
+ {"version", no_argument, 0, 'V'},
{"reattach", no_argument, 0, 512},
{0, 0, 0, 0},
};
@@ -245,9 +279,15 @@ static int erofsmount_parse_options(int argc, char **argv)
nbdsrc.ocicfg.layer_index = -1;
- while ((opt = getopt_long(argc, argv, "Nfno:st:uv",
+ while ((opt = getopt_long(argc, argv, "VNfhno:st:uv",
long_options, NULL)) != -1) {
switch (opt) {
+ case 'h':
+ usage(argc, argv);
+ exit(0);
+ case 'V':
+ version();
+ exit(0);
case 'o':
mountcfg.full_options = optarg;
mountcfg.flags =
--
2.43.0
More information about the Linux-erofs
mailing list