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 + +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 <[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 +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
