mirror of
https://github.com/ostreedev/ostree.git
synced 2025-03-16 10:50:43 +03:00
479 lines
24 KiB
HTML
479 lines
24 KiB
HTML
|
||
|
||
<!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.5" />
|
||
<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/atomic-rollbacks/" class="nav-list-link">Atomic Rollbacks</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/var/" class="nav-list-link">OSTree and /var handling</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/authenticated-repos/" class="nav-list-link">Handling access to authenticated remote 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/copying-deltas/" class="nav-list-link">Static deltas for offline updates</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/related-projects/" class="nav-list-link">Related Projects</a></li><li class="nav-list-item"><a href="/ostree/composefs/" class="nav-list-link">Using composefs with OSTree</a></li><li class="nav-list-item"><a href="/ostree/bootloaders/" class="nav-list-link">Bootloaders</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></li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
|
||
<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
|
||
<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>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<hr>
|
||
<footer>
|
||
|
||
|
||
<p class="text-small text-grey-dk-100 mb-0">Copyright © <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>
|
||
|