From ce58c0d17642f1211fd2e65e9a5698daccc6e199 Mon Sep 17 00:00:00 2001 From: Alexander Larsson Date: Fri, 22 Sep 2023 12:00:25 +0200 Subject: [PATCH] Update manpage and usage for mount.composefs Signed-off-by: Alexander Larsson --- man/mount.composefs.md | 50 +++++++++++++++++++++++++++++++++++------- tools/mountcomposefs.c | 16 ++++++++++++-- 2 files changed, 56 insertions(+), 10 deletions(-) diff --git a/man/mount.composefs.md b/man/mount.composefs.md index 24c0df74..c5c83ca7 100644 --- a/man/mount.composefs.md +++ b/man/mount.composefs.md @@ -5,27 +5,61 @@ mount.composefs - mount a composefs filesystem image # SYNOPSIS -**mount.composefs** *IMAGE* *TARGETDIR* +**mount.composefs** [-o OPTIONS] *IMAGE* *TARGETDIR* # DESCRIPTION -The composefs project uses EROFS to store metadata, and a distinct -underlying backing store for regular files. At runtime, composefs -uses `overlayfs` on top of a loopback mount. +The composefs project uses EROFS image file to store metadata, and one +or more separate directories containing content-addressed backing data +for regular files. -**mount.composefs** +**mount.composefs** mounts such an EROFS file in combination with a given +set of basedir at the specified location. It can be called directly, or +as a mount helper by running `mount -t composefst ...`. # OPTIONS The provided *IMAGE* argument must be a valid composefs (EROFS) metadata image. The *TARGETDIR* will be used as a mount target. -**mount.composefs** accepts the following options: +**mount.composefs** accepts the following colon-separated mount +options when passed via the `-o OPTIONS` argument. -**\-\-basedir**=*PATH* +**basedir**=*PATH* : This path will be used to resolve non-empty file references stored in the composefs metadata image. A primary use case is to have - this be the same path provided to `mkcomposefs --digest-store`. + this be the same path provided to `mkcomposefs --digest-store=PATH`. + + Multiple paths can be specified, separated by `:`. + +**digest**=*DIGEST* +: The image file is validated to have the specified fs-verity digest + before being used. This allows a chain of trust the ensures only + the expected data is ever visible in the mount. + + This option also implies **verity**. + +**verity** +: If this is specified, all files in the *IMAGE* must specify an fs-verity + digest, and all the files in the base dirs must have a matching fs-verity + digest. + + Note: This needs support for the overlayfs "verity" option in the + kernel, which was added in 6.6rc1. + +**ro** +: Mounts the filesystem read-only. This is mainly useful when using + **upperdir** as unlayered composefs images are naturally readonly. + +**rw** +: Overrides a previous **ro** option + +**upperdir** +: Specify an upper dir in the overlayfs mount that composefs uses. This allows + a writable layer on top of the composefs image. See overlayfs docs for details. + +**workdir** +: Specifies an overlayfs workdir to go with **upperdir**. # SEE ALSO diff --git a/tools/mountcomposefs.c b/tools/mountcomposefs.c index 784feed1..931fbc71 100644 --- a/tools/mountcomposefs.c +++ b/tools/mountcomposefs.c @@ -51,11 +51,23 @@ static void printexit(const char *format, ...) static void usage(const char *argv0) { + const char *bin = basename(argv0); fprintf(stderr, "usage: %s [-t type] [-o opt[,opts..]] IMAGE MOUNTPOINT\n" "Example:\n" - " %s -o basedir=/composefs/objects exampleimage.cfs /mnt/exampleimage\n", - argv0, argv0); + " %s -o basedir=/composefs/objects exampleimage.cfs /mnt/exampleimage\n" + "or, as a mount helper:\n" + " mount -t composefs -o basedir=/composefs/objects exampleimage.cfs /mnt/exampleimage\n" + "\n" + "Supported options:\n" + " basedir=PATH[:PATH] Specify location of basedir(s)\n" + " digest=DIGEST Specify required image digest\n" + " verity Require all files to have specified and valid fs-verity digests\n" + " ro Read only\n" + " rw Read/write\n" + " upperdir Overlayfs upperdir\n" + " workdir Overlayfs workdir\n", + bin, bin); } static void unescape_option(char *s)