From 96d12b3f68216c006465930a7cc9f4faba3d13a0 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Sat, 27 Feb 2016 11:28:33 -0500 Subject: [PATCH] docs: Add a blurb on the summary file We expect people to use it now, so let's actually describe what it is. --- docs/manual/repo.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/manual/repo.md b/docs/manual/repo.md index 3b7a737f..f636d574 100644 --- a/docs/manual/repo.md +++ b/docs/manual/repo.md @@ -88,3 +88,30 @@ the parent of a given commit. For example, `exampleos/buildmaster/x86_64-runtime^` refers to the previous build, and `exampleos/buildmaster/x86_64-runtime^^` refers to the one before that. + +## The summary file + +A later addition to OSTree is the concept of a "summary" file, created +via the `ostree summary -u` command. This was introduced for a few +reasons. A primary use case is to be a target a +(Metalink)[https://en.wikipedia.org/wiki/Metalink], which requires a +single file with a known checksum as a target. + +The summary file primarily contains two mappings: + + - A mapping of the refs and their checksums, equivalent to fetching + the ref file individually + - A list of all static deltas, along with their metadata checksums + +This currently means that it grows linearly with both items. On the +other hand, using the summary file, a client can enumerate branches. + +Further, the summary file is fetched over e.g. pinned TLS, this +creates a strong end-to-end verification of the commit or static delta. + +The summary file can also be GPG signed (detached), and currently this +is the only way provide GPG signatures (transitively) on deltas. + +If a repository administrator creates a summary file, they must +thereafter run `ostree summary -u` to update it whenever a commit is +made or a static delta is generated.