From: Chengyu Zhu <[email protected]> Add manpage, command-line usage help, and README for mount.erofs tool.
Signed-off-by: Chengyu Zhu <[email protected]> Link: https://lore.kernel.org/r/[email protected] [ Gao Xiang: change the section number of the manpage to 8. ] Signed-off-by: Gao Xiang <[email protected]> --- 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 <[email protected]> +.\" +.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
