Merge pull request #196 from alexlarsson/more-docs

Add more docs

libcomposefs/lcfs-mount.c

@@ -216,11 +216,6 @@ static int lcfs_validate_mount_options(struct lcfs_mount_state_s *state)
 		return -EINVAL;
 	}
 
-	if ((options->flags & LCFS_MOUNT_FLAGS_REQUIRE_VERITY) &&
-	    (options->flags & LCFS_MOUNT_FLAGS_DISABLE_VERITY)) {
-		return -EINVAL; /* Can't have both */
-	}
-
 	if (options->n_objdirs == 0)
 		return -EINVAL;
 
@@ -435,14 +430,12 @@ static int lcfs_mount_erofs_ovl(struct lcfs_mount_state_s *state,
 	const char *lowerdir_target = NULL;
 	int loopfd;
 	bool require_verity;
-	bool disable_verity;
 	bool readonly;
 	int mount_flags;
 
 	image_flags = lcfs_u32_from_file(header->flags);
 
 	require_verity = (options->flags & LCFS_MOUNT_FLAGS_REQUIRE_VERITY) != 0;
-	disable_verity = (options->flags & LCFS_MOUNT_FLAGS_DISABLE_VERITY) != 0;
 	readonly = (options->flags & LCFS_MOUNT_FLAGS_READONLY) != 0;
 
 	loopfd = setup_loopback(state->fd, state->image_path, loopname);
@@ -509,8 +502,7 @@ static int lcfs_mount_erofs_ovl(struct lcfs_mount_state_s *state,
 		       lowerdir_target, upperdir ? ",upperdir=" : "",
 		       upperdir ? upperdir : "", workdir ? ",workdir=" : "",
 		       workdir ? workdir : "",
-		       require_verity ? ",verity=require" :
-					(disable_verity ? ",verity=off" : ""));
+		       require_verity ? ",verity=require" : "");
 	if (res < 0) {
 		res = -ENOMEM;
 		goto fail;

libcomposefs/lcfs-mount.h

@@ -36,7 +36,6 @@ enum lcfs_mount_flags_t {
 	LCFS_MOUNT_FLAGS_REQUIRE_VERITY = (1 << 0),
 	LCFS_MOUNT_FLAGS_READONLY = (1 << 1),
 	LCFS_MOUNT_FLAGS_IDMAP = (1 << 3),
-	LCFS_MOUNT_FLAGS_DISABLE_VERITY = (1 << 4),
 
 	LCFS_MOUNT_FLAGS_MASK = (1 << 5) - 1,
 };

man/mkcomposefs.md

@@ -9,11 +9,13 @@ mkcomposefs - create a composefs filesystem image
 
 # DESCRIPTION
 
-The composefs project uses EROFS to store metadata, and a distinct
-underlying backing store for regular files.
+The composefs project uses EROFS image file to store metadata, and one
+or more separate directories containing content-addressed backing data
+for regular files.
 
 **mkcomposefs** constructs the mountable "composefs image" using the
-source directory as input.
+source directory as input. It can also create the backing store
+directory.
 
 # OPTIONS
 
@@ -23,14 +25,37 @@ will be a mountable composefs image.
 
 **mkcomposefs** accepts the following options:
 
+
 **\-\-digest-store**=*PATH*
-:   This path will become a composefs "object store".  Non-empty regular files
-    in the *SOURCEDIR* will be copied (reflinked if possible) into this target
-    directory, named after their fsverity digest.
+:   This path will become a composefs "object store". Non-empty
+    regular files in the *SOURCEDIR* will be copied (reflinked if
+    possible) into this target directory, named after their fsverity
+    digest. If possible, the added files will have fs-verity enabled.
+
+    This directory should be passed to the basedir option when you
+    mount the image.
 
 **\-\-print-digest**
 :   Print the fsverity digest of the composefs metadata file.
 
+**\-\-print-digest-only**
+:   Print the fsverity digest of the composefs metadata file, but
+    don't write the image. If this is passed, the *IMAGE* argument should
+    be left out.
+
+**\-\-use-epoch**
+:   Use a zero time (unix epoch) as the modification time for all files.
+
+**\-\-skip-devices**
+:   Don't add device nodes to the image.
+
+**\-\-skip-xattrs**
+:   Don't add xattrs to files in the image.
+
+**\-\-user-xattrs**
+:   Only add xattrs with the "user." prefix to files in the image.
+
+
 # SEE ALSO
 
 - [composefs upstream](https://github.com/containers/composefs)

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
 

tests/integration.sh

@@ -16,7 +16,7 @@ run_test() {
     local dumpdir_args="$2"
     mkcomposefs --print-digest --digest-store=${cfsroot}/objects ${testsrc} ${cfsroot}/roots/test.cfs | tee digest.txt
     prev_digest=$(cat digest.txt)
-    new_digest=$(mkcomposefs --by-digest --print-digest-only ${testsrc})
+    new_digest=$(mkcomposefs --print-digest-only ${testsrc})
     test "$prev_digest" = "$new_digest"
 
     if which fsck.erofs &>/dev/null; then
@@ -36,7 +36,7 @@ run_test() {
         exit 1
     fi
 
-    new_digest=$(mkcomposefs --by-digest --print-digest-only mnt)
+    new_digest=$(mkcomposefs --print-digest-only mnt)
     test "$prev_digest" = "$new_digest"
 
     umount mnt