diff options
author | Colin Walters <walters@verbum.org> | 2016-02-27 11:28:33 -0500 |
---|---|---|
committer | Colin Walters <walters@verbum.org> | 2016-02-27 11:28:54 -0500 |
commit | 96d12b3f68216c006465930a7cc9f4faba3d13a0 (patch) | |
tree | 3efede265c67efac1736d20b6d4b74912675cec0 /docs | |
parent | 3d7098bc5e451d9c76813168b2c5eef5647b16de (diff) | |
download | ostree-96d12b3f68216c006465930a7cc9f4faba3d13a0.tar.gz |
docs: Add a blurb on the summary file
We expect people to use it now, so let's actually describe what it is.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/manual/repo.md | 27 |
1 files changed, 27 insertions, 0 deletions
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. |