From b56da3409d8f1eb6551c9901cbe8bafbe4382d5b Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Mon, 19 Jun 2023 17:29:08 -0400 Subject: [PATCH] docs/composefs: Updates - fix URL - Document requirements - Document kernel argument - Adjust for recent changes --- docs/composefs.md | 49 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/docs/composefs.md b/docs/composefs.md index 800103fa..8f63c6e2 100644 --- a/docs/composefs.md +++ b/docs/composefs.md @@ -10,7 +10,7 @@ nav_order: 10 ## composefs -The [composefs](github.com/containers/composefs) project is a new +The [composefs](https://github.com/containers/composefs) project is a new hybrid Linux stacking filesystem that provides many benefits when used for bootable host systems, such as a strong story for integrity. @@ -22,12 +22,53 @@ At the current time, integration of composefs and ostree is experimental. When building a disk image *or* to transition an existing system, run: ``` -ostree config --repo=/ostree/repo set ex-integrity.composefs yes +ostree config --repo=/ostree/repo set ex-integrity.composefs true ``` This will ensure that any future deployments (e.g. created by `ostree admin upgrade`) have a `.ostree.cfs` file in the deployment directory which is a mountable -composefs metadata file, with a "backing store" directory also shared with the current `/ostree/repo/objects`. +composefs metadata file, with a "backing store" directory that is +shared with the current `/ostree/repo/objects`. + +### Kernel argument ot-composefs + +The `ostree-prepare-root` binary will look for a kernel argument called `ot-composefs`. + +The default value is `maybe` (this will likely become a build and initramfs-configurable option) +in the future too. + +The possible values are: + +- `off`: Never use composefs +- `maybe`: Use composefs if supported and there is a composefs image in the deployment directory +- `on`: Require composefs +- `digest=`: Require the mounted composefs image to have a particular digest +- `signed`: This option will be documented in the future; don't use it right now + +### Injecting composefs digests + +When generating an OSTree commit, there is a CLI switch `--generate-composefs-metadata` +and a corresponding C API `ostree_repo_commit_add_composefs_metadata`. This will +inject the composefs digest as metadata into the ostree commit under a metadata +key `ostree.composefs.v0`. Because an OSTree commit can be signed, this allows +covering the composefs fsverity digest with a signature. + +At the current time, ostree does not directly support verifying the signature on +the commit object before mounting, but that is in progress. + +## Requirements + +The current default composefs integration in ostree does not have any requirements +from the underlying kernel and filesystem other than having the following +kernel options set: + +- `CONFIG_OVERLAY_FS` +- `CONFIG_BLK_DEV_LOOP` +- `CONFIG_EROFS_FS` + +At the current time, there are no additional userspace runtime requirements. + +## Status **IMPORTANT** The integration with composefs is experimental and subject to change. Please try it and report issues but do not deploy to production systems yet. @@ -39,7 +80,7 @@ provides much stronger and more efficient integrity: - composefs validates an entire filesystem tree, not just individual files - composefs makes files actually read-only, whereas IMA does not by default -- composefs uses fs-verity which does on-demand verification +- composefs uses fs-verity which does on-demand verification (IMA by default does a full readahead of every file accessed, though IMA can also use fs-verity as a backend) ## Further references