[PATCH v1] erofs-utils: mount: add manpage and usage information

[PATCH v1] erofs-utils: mount: add manpage and usage information

[ChengyuZhu6]

From: Chengyu Zhu <hudsonzhu@tencent.com>

Add manpage, command-line usage help, and README for
mount.erofs tool.

Signed-off-by: Chengyu Zhu <hudsonzhu@tencent.com>
---
 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
+
+To mount with FUSE backend:
+ $ mount.erofs -t erofs.fuse foo.erofs.img /mnt
+
+To mount from OCI image with NBD backend:
+ $ mount.erofs -t erofs.nbd -o oci.blob=sha256:... image:tag /mnt
+
+To unmount:
+ $ 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 <hudsonzhu@tencent.com>
+.\"
+.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
+Mount a local EROFS image:
+.PP
+.nf
+.RS
+mount.erofs image.erofs /mnt
+.RE
+.fi
+.PP
+Mount using FUSE backend:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.fuse image.erofs /mnt
+.RE
+.fi
+.PP
+Mount an OCI blob via NBD:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.nbd \\
+    \-o oci.blob=sha256:abc123...,oci.username=user,oci.password=pass \\
+    docker.io/library/image:tag /mnt
+.RE
+.fi
+.PP
+Mount an OCI layer by index:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.nbd \-o oci.layer=0 \\
+    docker.io/library/image:tag /mnt
+.RE
+.fi
+.PP
+Mount with tarball index and gzip support:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.nbd \\
+    \-o oci.blob=sha256:abc...,oci.tarindex=/path/to/index,oci.zinfo=/path/to/zinfo \\
+    docker.io/library/image:tag /mnt
+.RE
+.fi
+.PP
+Unmount a filesystem:
+.PP
+.nf
+.RS
+mount.erofs \-u /mnt
+.RE
+.fi
+.PP
+Reattach to an NBD device:
+.PP
+.nf
+.RS
+mount.erofs \-\-reattach /dev/nbd0
+.RE
+.fi
+.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.
+.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..3c5e657 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"
+	       "   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"
+#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)
 {
@@ -253,6 +285,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},
 	};
@@ -261,9 +294,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, "hVNfno: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.47.1

Re: [PATCH v1] erofs-utils: mount: add manpage and usage information

[zhaoyifan (H)]

[-- Attachment #1: Type: text/plain, Size: 827 bytes --]


On 2025/11/30 11:35, ChengyuZhu6 wrote:
> +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"

Hi Chengyu,

Seems wrong indent here.


Thanks,
Yifan Zhao


> +#ifdef OCIEROFS_ENABLED
>

[-- Attachment #2: Type: text/html, Size: 1476 bytes --]

Re: [PATCH v1] erofs-utils: mount: add manpage and usage information

[hudsonZhu]

[-- Attachment #1: Type: text/plain, Size: 1036 bytes --]

Thanks, I’ll fix it.

Thanks,
Chengyu

> 2025年12月1日 21:54，zhaoyifan (H) <zhaoyifan28@huawei.com> 写道：
> 
> 
> 
> On 2025/11/30 11:35, ChengyuZhu6 wrote:
> 
>> +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"
> Hi Chengyu,
> 
> Seems wrong indent here.
> 
> 
> 
> Thanks,
> Yifan Zhao
> 
> 
> 
>> +#ifdef OCIEROFS_ENABLED
>> 


[-- Attachment #2: Type: text/html, Size: 1924 bytes --]

[PATCH v2] mount.erofs: add manpage and usage information

[ChengyuZhu6]

From: Chengyu Zhu <hudsonzhu@tencent.com>

Add manpage, command-line usage help, and README for
mount.erofs tool.

Signed-off-by: Chengyu Zhu <hudsonzhu@tencent.com>
---
 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
+
+To mount with FUSE backend:
+ $ mount.erofs -t erofs.fuse foo.erofs.img /mnt
+
+To mount from OCI image with NBD backend:
+ $ mount.erofs -t erofs.nbd -o oci.blob=sha256:... image:tag /mnt
+
+To unmount:
+ $ 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 <hudsonzhu@tencent.com>
+.\"
+.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
+Mount a local EROFS image:
+.PP
+.nf
+.RS
+mount.erofs image.erofs /mnt
+.RE
+.fi
+.PP
+Mount using FUSE backend:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.fuse image.erofs /mnt
+.RE
+.fi
+.PP
+Mount an OCI blob via NBD:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.nbd \\
+    \-o oci.blob=sha256:abc123...,oci.username=user,oci.password=pass \\
+    docker.io/library/image:tag /mnt
+.RE
+.fi
+.PP
+Mount an OCI layer by index:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.nbd \-o oci.layer=0 \\
+    docker.io/library/image:tag /mnt
+.RE
+.fi
+.PP
+Mount with tarball index and gzip support:
+.PP
+.nf
+.RS
+mount.erofs \-t erofs.nbd \\
+    \-o oci.blob=sha256:abc...,oci.tarindex=/path/to/index,oci.zinfo=/path/to/zinfo \\
+    docker.io/library/image:tag /mnt
+.RE
+.fi
+.PP
+Unmount a filesystem:
+.PP
+.nf
+.RS
+mount.erofs \-u /mnt
+.RE
+.fi
+.PP
+Reattach to an NBD device:
+.PP
+.nf
+.RS
+mount.erofs \-\-reattach /dev/nbd0
+.RE
+.fi
+.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.
+.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"
+		"   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"
+#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)
 {
@@ -253,6 +285,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},
 	};
@@ -261,9 +294,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, "hVNfno: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.51.0

Re: [PATCH v2] mount.erofs: add manpage and usage information

[Gao Xiang]

On 2025/12/2 11:08, ChengyuZhu6 wrote:
> From: Chengyu Zhu <hudsonzhu@tencent.com>
> 
> Add manpage, command-line usage help, and README for
> mount.erofs tool.
> 
> Signed-off-by: Chengyu Zhu <hudsonzhu@tencent.com>
> ---
>   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 <hudsonzhu@tencent.com>
> +.\"
> +.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

[PATCH v3] mount.erofs: add manpage and usage information

[ChengyuZhu6]

From: Chengyu Zhu <hudsonzhu@tencent.com>

Add manpage, command-line usage help, and README for
mount.erofs tool.

Signed-off-by: Chengyu Zhu <hudsonzhu@tencent.com>
---
 README            |  26 +++++++++
 man/Makefile.am   |   2 +-
 man/mount.erofs.1 | 142 ++++++++++++++++++++++++++++++++++++++++++++++
 mount/main.c      |  41 ++++++++++++-
 4 files changed, 209 insertions(+), 2 deletions(-)
 create mode 100644 man/mount.erofs.1

diff --git a/README b/README
index b885fa8..77ccef7 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(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..146c01e
--- /dev/null
+++ b/man/mount.erofs.1
@@ -0,0 +1,142 @@
+.\" Copyright (c) 2025 Chengyu Zhu <hudsonzhu@tencent.com>
+.\"
+.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 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 e25134c..b0eba79 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\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"
+#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)
 {
@@ -253,6 +285,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},
 	};
@@ -261,9 +294,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, "hVNfno: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.51.0

[PATCH v4] erofs-utils: mount: add manpage and usage information

[Yifan Zhao]

From: Chengyu Zhu <hudsonzhu@tencent.com>

Add manpage, command-line usage help, and README for
mount.erofs tool.

Signed-off-by: Chengyu Zhu <hudsonzhu@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@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@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

Re: [PATCH v4] erofs-utils: mount: add manpage and usage information

[Gao Xiang]

Hi Yifan,

On 2025/12/22 15:16, Yifan Zhao wrote:
> From: Chengyu Zhu <hudsonzhu@tencent.com>
> 
> Add manpage, command-line usage help, and README for
> mount.erofs tool.
> 
> Signed-off-by: Chengyu Zhu <hudsonzhu@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@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

Can you just posting an incremental patch for this? since I
have two new patches relying on this too.

Thanks,
Gao Xiang

[PATCH v5] erofs-utils: mount: add manpage and usage information

[Yifan Zhao]

From: Chengyu Zhu <hudsonzhu@tencent.com>

Add manpage, command-line usage help, and README for
mount.erofs tool.

Signed-off-by: Chengyu Zhu <hudsonzhu@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@linux.alibaba.com>
---
Sorry, there is also an indent error need to be fixed.

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..1463dee 100644
  --- a/mount/main.c
  +++ b/mount/main.c
  @@ -94,7 +94,7 @@ static void usage(int argc, char **argv)
   		" -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"
  +		" --reattach		reattach to an existing NBD device\n"
   #ifdef OCIEROFS_ENABLED
   		"\n"
   		"OCI-specific options (with -o):\n"
  @@ -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@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..1463dee 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

Re: [PATCH v4] erofs-utils: mount: add manpage and usage information

[zhaoyifan (H)]

OK, I will just submit a new patch.


Thanks,

Yifan Zhao


On 2025/12/22 15:36, Gao Xiang wrote:
> Hi Yifan,
>
> On 2025/12/22 15:16, Yifan Zhao wrote:
>> From: Chengyu Zhu <hudsonzhu@tencent.com>
>>
>> Add manpage, command-line usage help, and README for
>> mount.erofs tool.
>>
>> Signed-off-by: Chengyu Zhu <hudsonzhu@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@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
>
> Can you just posting an incremental patch for this? since I
> have two new patches relying on this too.
>
> Thanks,
> Gao Xiang