1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
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 © <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>
|
