summaryrefslogtreecommitdiff
path: root/repo/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'repo/index.html')
-rw-r--r--repo/index.html488
1 files changed, 488 insertions, 0 deletions
diff --git a/repo/index.html b/repo/index.html
new file mode 100644
index 00000000..ee3773f7
--- /dev/null
+++ b/repo/index.html
@@ -0,0 +1,488 @@
+
+
+<!DOCTYPE html>
+
+<html lang="en-US">
+<head>
+ <meta charset="UTF-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+
+ <link rel="stylesheet" href="/ostree/assets/css/just-the-docs-default.css">
+
+
+
+
+ <script src="/ostree/assets/js/vendor/lunr.min.js"></script>
+
+
+
+
+ <script src="/ostree/assets/js/just-the-docs.js"></script>
+
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+
+
+
+
+ <!-- Begin Jekyll SEO tag v2.8.0 -->
+<title>Anatomy of an OSTree repository | ostreedev/ostree</title>
+<meta name="generator" content="Jekyll v3.9.3" />
+<meta property="og:title" content="Anatomy of an OSTree repository" />
+<meta property="og:locale" content="en_US" />
+<meta name="description" content="ostree documentation" />
+<meta property="og:description" content="ostree documentation" />
+<link rel="canonical" href="https://ostreedev.github.io/ostree/repo/" />
+<meta property="og:url" content="https://ostreedev.github.io/ostree/repo/" />
+<meta property="og:site_name" content="ostreedev/ostree" />
+<meta property="og:type" content="website" />
+<meta name="twitter:card" content="summary" />
+<meta property="twitter:title" content="Anatomy of an OSTree repository" />
+<script type="application/ld+json">
+{"@context":"https://schema.org","@type":"WebPage","description":"ostree documentation","headline":"Anatomy of an OSTree repository","url":"https://ostreedev.github.io/ostree/repo/"}</script>
+<!-- End Jekyll SEO tag -->
+
+
+
+
+</head>
+
+<body>
+ <a class="skip-to-main" href="#main-content">Skip to main content</a>
+ <svg xmlns="http://www.w3.org/2000/svg" class="d-none">
+ <symbol id="svg-link" viewBox="0 0 24 24">
+ <title>Link</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link">
+ <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+ </svg>
+</symbol>
+
+ <symbol id="svg-menu" viewBox="0 0 24 24">
+ <title>Menu</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu">
+ <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
+ </svg>
+</symbol>
+
+ <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+ <title>Expand</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right">
+ <polyline points="9 18 15 12 9 6"></polyline>
+ </svg>
+</symbol>
+
+ <!-- Feather. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE -->
+<symbol id="svg-external-link" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-external-link">
+ <title id="svg-external-link-title">(external link)</title>
+ <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line>
+</symbol>
+
+
+ <symbol id="svg-doc" viewBox="0 0 24 24">
+ <title>Document</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file">
+ <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
+ </svg>
+</symbol>
+
+ <symbol id="svg-search" viewBox="0 0 24 24">
+ <title>Search</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search">
+ <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+ </svg>
+</symbol>
+
+
+
+ <!-- Bootstrap Icons. MIT License: https://github.com/twbs/icons/blob/main/LICENSE.md -->
+<symbol id="svg-copy" viewBox="0 0 16 16">
+ <title>Copy</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard" viewBox="0 0 16 16">
+ <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/>
+ <path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/>
+ </svg>
+</symbol>
+<symbol id="svg-copied" viewBox="0 0 16 16">
+ <title>Copied</title>
+ <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-clipboard-check-fill" viewBox="0 0 16 16">
+ <path d="M6.5 0A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3Zm3 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3Z"/>
+ <path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1A2.5 2.5 0 0 1 9.5 5h-3A2.5 2.5 0 0 1 4 2.5v-1Zm6.854 7.354-3 3a.5.5 0 0 1-.708 0l-1.5-1.5a.5.5 0 0 1 .708-.708L7.5 10.793l2.646-2.647a.5.5 0 0 1 .708.708Z"/>
+ </svg>
+</symbol>
+
+
+</svg>
+
+ <div class="side-bar">
+ <div class="site-header">
+ <a href="/ostree/" class="site-title lh-tight">
+ ostreedev/ostree
+
+</a>
+ <a href="#" id="menu-button" class="site-button">
+ <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
+ </a>
+ </div>
+ <nav aria-label="Main" id="site-nav" class="site-nav">
+
+
+ <ul class="nav-list"><li class="nav-list-item"><a href="/ostree/" class="nav-list-link">libostree</a></li><li class="nav-list-item"><a href="/ostree/introduction/" class="nav-list-link">OSTree Overview</a></li><li class="nav-list-item active"><a href="/ostree/repo/" class="nav-list-link active">Anatomy of an OSTree repository</a></li><li class="nav-list-item"><a href="/ostree/deployment/" class="nav-list-link">Deployments</a></li><li class="nav-list-item"><a href="/ostree/atomic-upgrades/" class="nav-list-link">Atomic Upgrades</a></li><li class="nav-list-item"><a href="/ostree/adapting-existing/" class="nav-list-link">Adapting existing mainstream distributions</a></li><li class="nav-list-item"><a href="/ostree/formats/" class="nav-list-link">OSTree data formats</a></li><li class="nav-list-item"><a href="/ostree/buildsystem-and-repos/" class="nav-list-link">Writing a buildsystem and managing repositories</a></li><li class="nav-list-item"><a href="/ostree/repository-management/" class="nav-list-link">Managing content in OSTree repositories</a></li><li class="nav-list-item"><a href="/ostree/related-projects/" class="nav-list-link">Related Projects</a></li><li class="nav-list-item"><a href="/ostree/ima/" class="nav-list-link">Using Linux IMA with OSTree</a></li><li class="nav-list-item"><a href="/ostree/CONTRIBUTING/" class="nav-list-link">Contributing</a></li><li class="nav-list-item"><a href="/ostree/contributing-tutorial/" class="nav-list-link">OSTree Contributing Tutorial</a></li><li class="nav-list-item"><a href="/ostree/README-historical/" class="nav-list-link">Historical OSTree README</a></li></ul>
+
+ </nav>
+
+
+
+ <footer class="site-footer">
+ This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
+ </footer>
+
+</div>
+
+ <div class="main" id="top">
+ <div id="main-header" class="main-header">
+
+
+
+<div class="search">
+ <div class="search-input-wrap">
+ <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search ostreedev/ostree" aria-label="Search ostreedev/ostree" autocomplete="off">
+ <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
+ </div>
+ <div id="search-results" class="search-results"></div>
+</div>
+
+
+
+
+ <nav aria-label="Auxiliary" class="aux-nav">
+ <ul class="aux-nav-list">
+
+ <li class="aux-nav-list-item">
+ <a href="https://github.com/ostreedev/ostree" class="site-button"
+
+ >
+ OSTree on GitHub
+ </a>
+ </li>
+
+ </ul>
+</nav>
+
+
+</div>
+
+ <div id="main-content-wrap" class="main-content-wrap">
+
+
+
+
+ <div id="main-content" class="main-content" role="main">
+
+ <h1 class="no_toc" id="anatomy-of-an-ostree-repository">
+
+
+ <a href="#anatomy-of-an-ostree-repository" class="anchor-heading" aria-labelledby="anatomy-of-an-ostree-repository"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Anatomy of an OSTree repository
+
+
+</h1>
+
+
+<ol id="markdown-toc">
+ <li><a href="#core-object-types-and-data-model" id="markdown-toc-core-object-types-and-data-model">Core object types and data model</a> <ol>
+ <li><a href="#commit-objects" id="markdown-toc-commit-objects">Commit objects</a></li>
+ <li><a href="#dirtree-objects" id="markdown-toc-dirtree-objects">Dirtree objects</a></li>
+ <li><a href="#dirmeta-objects" id="markdown-toc-dirmeta-objects">Dirmeta objects</a></li>
+ <li><a href="#content-objects" id="markdown-toc-content-objects">Content objects</a></li>
+ <li><a href="#xattrs-objects" id="markdown-toc-xattrs-objects">Xattrs objects</a></li>
+ </ol>
+ </li>
+ <li><a href="#repository-types-and-locations" id="markdown-toc-repository-types-and-locations">Repository types and locations</a> <ol>
+ <li><a href="#refs" id="markdown-toc-refs">Refs</a></li>
+ <li><a href="#the-summary-file" id="markdown-toc-the-summary-file">The summary file</a> <ol>
+ <li><a href="#licensing-for-this-document" id="markdown-toc-licensing-for-this-document">Licensing for this document:</a></li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+</ol>
+<h2 id="core-object-types-and-data-model">
+
+
+ <a href="#core-object-types-and-data-model" class="anchor-heading" aria-labelledby="core-object-types-and-data-model"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Core object types and data model
+
+
+</h2>
+
+
+<p>OSTree is deeply inspired by git; the core layer is a userspace
+content-addressed versioning filesystem. It is worth taking some time
+to familiarize yourself with
+<a href="http://git-scm.com/book/en/Git-Internals">Git Internals</a>, as this
+section will assume some knowledge of how git works.</p>
+
+<p>Its object types are similar to git; it has commit objects and content
+objects. Git has “tree” objects, whereas OSTree splits them into
+“dirtree” and “dirmeta” objects. But unlike git, OSTree’s checksums
+are SHA256. And most crucially, its content objects include uid, gid,
+and extended attributes (but still no timestamps).</p>
+<h3 id="commit-objects">
+
+
+ <a href="#commit-objects" class="anchor-heading" aria-labelledby="commit-objects"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Commit objects
+
+
+</h3>
+
+
+<p>A commit object contains metadata such as a timestamp, a log
+message, and most importantly, a reference to a
+dirtree/dirmeta pair of checksums which describe the root
+directory of the filesystem.
+Also like git, each commit in OSTree can have a parent. It is
+designed to store a history of your binary builds, just like git
+stores a history of source control. However, OSTree also makes
+it easy to delete data, under the assumption that you can
+regenerate it from source code.</p>
+<h3 id="dirtree-objects">
+
+
+ <a href="#dirtree-objects" class="anchor-heading" aria-labelledby="dirtree-objects"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Dirtree objects
+
+
+</h3>
+
+
+<p>A dirtree contains a sorted array of (filename, checksum)
+pairs for content objects, and a second sorted array of
+(filename, dirtree checksum, dirmeta checksum), which are
+subdirectories. This type of object is stored as files
+ending with <code class="language-plaintext highlighter-rouge">.dirtree</code> in the objects directory.</p>
+<h3 id="dirmeta-objects">
+
+
+ <a href="#dirmeta-objects" class="anchor-heading" aria-labelledby="dirmeta-objects"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Dirmeta objects
+
+
+</h3>
+
+
+<p>In git, tree objects contain the metadata such as permissions
+for their children. But OSTree splits this into a separate
+object to avoid duplicating extended attribute listings.
+These type of objects are stored as files ending with <code class="language-plaintext highlighter-rouge">.dirmeta</code>
+in the objects directory.</p>
+<h3 id="content-objects">
+
+
+ <a href="#content-objects" class="anchor-heading" aria-labelledby="content-objects"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Content objects
+
+
+</h3>
+
+
+<p>Unlike the first three object types which are metadata, designed to be
+<code class="language-plaintext highlighter-rouge">mmap()</code>ed, the content object has a separate internal header and
+payload sections. The header contains uid, gid, mode, and symbolic
+link target (for symlinks), as well as extended attributes. After the
+header, for regular files, the content follows. These parts together
+form the SHA256 hash for content objects. The content type objects in
+this format exist only in <code class="language-plaintext highlighter-rouge">archive</code> OSTree repositories. Today the
+content part is gzip’ed and the objects are stored as files ending
+with <code class="language-plaintext highlighter-rouge">.filez</code> in the objects directory. Because the SHA256 hash is
+formed over the uncompressed content, these files do not match the
+hash they are named as.</p>
+
+<p>The OSTree data format intentionally does not contain timestamps. The reasoning
+is that data files may be downloaded at different times, and by different build
+systems, and so will have different timestamps but identical physical content.
+These files may be large, so most users would like them to be shared, both in
+the repository and between the repository and deployments.</p>
+
+<p>This could cause problems with programs that check if files are out-of-date by
+comparing timestamps. For Git, the logical choice is to not mess with
+timestamps, because unnecessary rebuilding is better than a broken tree.
+However, OSTree has to hardlink files to check them out, and commits are assumed
+to be internally consistent with no build steps needed. For this reason, OSTree
+acts as though all timestamps are set to time_t 0, so that comparisons will be
+considered up-to-date. Note that for a few releases, OSTree used 1 to fix
+warnings such as GNU Tar emitting “implausibly old time stamp” with 0; however,
+until we have a mechanism to transition cleanly to 1, for compatibilty OSTree
+is reverted to use zero again.</p>
+<h3 id="xattrs-objects">
+
+
+ <a href="#xattrs-objects" class="anchor-heading" aria-labelledby="xattrs-objects"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Xattrs objects
+
+
+</h3>
+
+
+<p>In some repository modes (e.g. <code class="language-plaintext highlighter-rouge">bare-split-xattrs</code>), xattrs are stored on the
+side of the content objects they refer to. This is done via two dedicated
+object types, <code class="language-plaintext highlighter-rouge">file-xattrs</code> and <code class="language-plaintext highlighter-rouge">file-xattrs-link</code>.</p>
+
+<p><code class="language-plaintext highlighter-rouge">file-xattrs</code> store xattrs data, encoded as GVariant. Each object is keyed by
+the checksum of the xattrs content, allowing for multiple references.</p>
+
+<p><code class="language-plaintext highlighter-rouge">file-xattrs-link</code> are hardlinks which are associated to file objects.
+Each object is keyed by the same checksum of the corresponding file
+object. The target of the hardlink is an existing <code class="language-plaintext highlighter-rouge">file-xattrs</code> object.
+In case of reaching the limit of too many links, this object could be
+a plain file too.</p>
+<h1 id="repository-types-and-locations">
+
+
+ <a href="#repository-types-and-locations" class="anchor-heading" aria-labelledby="repository-types-and-locations"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Repository types and locations
+
+
+</h1>
+
+
+<p>Also unlike git, an OSTree repository can be in one of five separate
+modes: <code class="language-plaintext highlighter-rouge">bare</code>, <code class="language-plaintext highlighter-rouge">bare-split-xattrs, </code><code class="language-plaintext highlighter-rouge">bare-user</code>, <code class="language-plaintext highlighter-rouge">bare-user-only</code>, and
+<code class="language-plaintext highlighter-rouge">archive</code>.</p>
+
+<p>A <code class="language-plaintext highlighter-rouge">bare</code> repository is one where content files are just stored as regular
+files; it’s designed to be the source of a “hardlink farm”, where each
+operating system checkout is merely links into it. If you want to store files
+owned by e.g. root in this mode, you must run OSTree as root.</p>
+
+<p>The <code class="language-plaintext highlighter-rouge">bare-split-xattrs</code> mode is similar to the above one, but it does store
+xattrs as separate objects. This is meant to avoid conflicts with
+kernel-enforced constraints (e.g. on SELinux labels) and with other softwares
+that may perform ephemeral changes to xattrs (e.g. container runtimes).</p>
+
+<p>The <code class="language-plaintext highlighter-rouge">bare-user</code> mode is a later addition that is like <code class="language-plaintext highlighter-rouge">bare</code> in that
+files are unpacked, but it can (and should generally) be created as
+non-root. In this mode, extended metadata such as owner uid, gid, and
+extended attributes are stored in extended attributes under the name
+<code class="language-plaintext highlighter-rouge">user.ostreemeta</code> but not actually applied.
+The <code class="language-plaintext highlighter-rouge">bare-user</code> mode is useful for build systems that run as non-root
+but want to generate root-owned content, as well as non-root container
+systems.</p>
+
+<p>The <code class="language-plaintext highlighter-rouge">bare-user-only</code> mode is a variant to the <code class="language-plaintext highlighter-rouge">bare-user</code> mode. Unlike
+<code class="language-plaintext highlighter-rouge">bare-user</code>, neither ownership nor extended attributes are stored. These repos
+are meant to to be checked out in user mode (with the <code class="language-plaintext highlighter-rouge">-U</code> flag), where this
+information is not applied anyway. Hence this mode may lose metadata.
+The main advantage of <code class="language-plaintext highlighter-rouge">bare-user-only</code> is that repos can be stored on
+filesystems which do not support extended attributes, such as tmpfs.</p>
+
+<p>In contrast, the <code class="language-plaintext highlighter-rouge">archive</code> mode is designed for serving via plain
+HTTP. Like tar files, it can be read/written by non-root users.</p>
+
+<p>On an OSTree-deployed system, the “system repository” is <code class="language-plaintext highlighter-rouge">/ostree/repo</code>. It can
+be read by any uid, but only written by root. The <code class="language-plaintext highlighter-rouge">ostree</code> command will by
+default operate on the system repository; you may provide the <code class="language-plaintext highlighter-rouge">--repo</code> argument
+to override this, or set the <code class="language-plaintext highlighter-rouge">$OSTREE_REPO</code> environment variable.</p>
+<h2 id="refs">
+
+
+ <a href="#refs" class="anchor-heading" aria-labelledby="refs"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Refs
+
+
+</h2>
+
+
+<p>Like git, OSTree uses the terminology “references” (abbreviated
+“refs”) which are text files that name (refer to) particular
+commits. See the
+<a href="https://git-scm.com/book/en/v2/Git-Internals-Git-References">Git Documentation</a>
+for information on how git uses them. Unlike git though, it doesn’t
+usually make sense to have a “main” branch. There is a convention
+for references in OSTree that looks like this:
+<code class="language-plaintext highlighter-rouge">exampleos/buildmain/x86_64-runtime</code> and
+<code class="language-plaintext highlighter-rouge">exampleos/buildmain/x86_64-devel-debug</code>. These two refs point to
+two different generated filesystem trees. In this example, the
+“runtime” tree contains just enough to run a basic system, and
+“devel-debug” contains all of the developer tools and debuginfo.</p>
+
+<p>The <code class="language-plaintext highlighter-rouge">ostree</code> supports a simple syntax using the caret <code class="language-plaintext highlighter-rouge">^</code> to refer to
+the parent of a given commit. For example,
+<code class="language-plaintext highlighter-rouge">exampleos/buildmain/x86_64-runtime^</code> refers to the previous build,
+and <code class="language-plaintext highlighter-rouge">exampleos/buildmain/x86_64-runtime^^</code> refers to the one before
+that.</p>
+<h2 id="the-summary-file">
+
+
+ <a href="#the-summary-file" class="anchor-heading" aria-labelledby="the-summary-file"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> The summary file
+
+
+</h2>
+
+
+<p>A later addition to OSTree is the concept of a “summary” file, created
+via the <code class="language-plaintext highlighter-rouge">ostree summary -u</code> command. This was introduced for a few
+reasons. A primary use case is to be compatible with
+<a href="https://en.wikipedia.org/wiki/Metalink">Metalink</a>, which requires a
+single file with a known checksum as a target.</p>
+
+<p>The summary file primarily contains two mappings:</p>
+
+<ul>
+ <li>A mapping of the refs and their checksums, equivalent to fetching
+the ref file individually</li>
+ <li>A list of all static deltas, along with their metadata checksums</li>
+</ul>
+
+<p>This currently means that it grows linearly with both items. On the
+other hand, using the summary file, a client can enumerate branches.</p>
+
+<p>Further, fetching the summary file over e.g. pinned TLS creates a strong
+end-to-end verification of the commit or static delta.</p>
+
+<p>The summary file can also be GPG signed (detached). This is currently
+the only way to provide GPG signatures (transitively) on deltas.</p>
+
+<p>If a repository administrator creates a summary file, they must
+thereafter run <code class="language-plaintext highlighter-rouge">ostree summary -u</code> to update it whenever a ref is
+updated or a static delta is generated.</p>
+<h6 id="licensing-for-this-document">
+
+
+ <a href="#licensing-for-this-document" class="anchor-heading" aria-labelledby="licensing-for-this-document"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Licensing for this document:
+
+
+</h6>
+
+<p><code class="language-plaintext highlighter-rouge">SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)</code></p>
+
+
+
+
+
+
+
+ <hr>
+ <footer>
+
+
+ <p class="text-small text-grey-dk-100 mb-0">Copyright &copy; <a href="https://www.redhat.com">Red Hat, Inc.</a> and <a href="https://github.com/ostreedev">others</a>.</p>
+
+
+ <div class="d-flex mt-2">
+
+
+ <p class="text-small text-grey-dk-000 mb-0">
+ <a href="https://github.com/ostreedev/ostree/tree/main/docs/repo.md" id="edit-this-page">Edit this page on GitHub</a>
+ </p>
+
+ </div>
+
+ </footer>
+
+
+
+ </div>
+ </div>
+
+
+
+<div class="search-overlay"></div>
+
+
+ </div>
+
+
+</body>
+</html>
+