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
|
<!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>Deployments | ostreedev/ostree</title>
<meta name="generator" content="Jekyll v3.9.3" />
<meta property="og:title" content="Deployments" />
<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/deployment/" />
<meta property="og:url" content="https://ostreedev.github.io/ostree/deployment/" />
<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="Deployments" />
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"WebPage","description":"ostree documentation","headline":"Deployments","url":"https://ostreedev.github.io/ostree/deployment/"}</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"><a href="/ostree/repo/" class="nav-list-link">Anatomy of an OSTree repository</a></li><li class="nav-list-item active"><a href="/ostree/deployment/" class="nav-list-link active">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="deployments">
<a href="#deployments" class="anchor-heading" aria-labelledby="deployments"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Deployments
</h1>
<ol id="markdown-toc">
<li><a href="#overview" id="markdown-toc-overview">Overview</a> <ol>
<li><a href="#stateroot-aka-osname-group-of-deployments-that-share-var" id="markdown-toc-stateroot-aka-osname-group-of-deployments-that-share-var">“stateroot” (AKA “osname”): Group of deployments that share /var</a></li>
<li><a href="#contents-of-a-deployment" id="markdown-toc-contents-of-a-deployment">Contents of a deployment</a></li>
<li><a href="#staged-deployments" id="markdown-toc-staged-deployments">Staged deployments</a></li>
<li><a href="#the-system-boot" id="markdown-toc-the-system-boot">The system /boot</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="overview">
<a href="#overview" class="anchor-heading" aria-labelledby="overview"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Overview
</h2>
<p>Built on top of the OSTree versioning filesystem core is a layer
that knows how to deploy, parallel install, and manage Unix-like
operating systems (accessible via <code class="language-plaintext highlighter-rouge">ostree admin</code>). The core content of these operating systems
are treated as read-only, but they transparently share storage.</p>
<p>A deployment is physically located at a path of the form
<code class="language-plaintext highlighter-rouge">/ostree/deploy/$stateroot/deploy/$checksum</code>.
OSTree is designed to boot directly into exactly one deployment
at a time; each deployment is intended to be a target for
<code class="language-plaintext highlighter-rouge">chroot()</code> or equivalent.</p>
<h3 id="stateroot-aka-osname-group-of-deployments-that-share-var">
<a href="#stateroot-aka-osname-group-of-deployments-that-share-var" class="anchor-heading" aria-labelledby="stateroot-aka-osname-group-of-deployments-that-share-var"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> “stateroot” (AKA “osname”): Group of deployments that share /var
</h3>
<p>Each deployment is grouped in exactly one “stateroot” (also known as an “osname”);
the former term is preferred.</p>
<p>From above, you can see that a stateroot is physically represented in the
<code class="language-plaintext highlighter-rouge">/ostree/deploy/$stateroot</code> directory. For example, OSTree can allow parallel
installing Debian in <code class="language-plaintext highlighter-rouge">/ostree/deploy/debian</code> and Red Hat Enterprise Linux in
<code class="language-plaintext highlighter-rouge">/ostree/deploy/rhel</code> (subject to operating system support, present released
versions of these operating systems may not support this).</p>
<p>Each stateroot has exactly one copy of the traditional Unix <code class="language-plaintext highlighter-rouge">/var</code>,
stored physically in <code class="language-plaintext highlighter-rouge">/ostree/deploy/$stateroot/var</code>. OSTree provides
support tools for <code class="language-plaintext highlighter-rouge">systemd</code> to create a Linux bind mount that ensures
the booted deployment sees the shared copy of <code class="language-plaintext highlighter-rouge">/var</code>.</p>
<p>OSTree does not touch the contents of <code class="language-plaintext highlighter-rouge">/var</code>. Operating system
components such as daemon services are required to create any
directories they require there at runtime
(e.g. <code class="language-plaintext highlighter-rouge">/var/cache/$daemonname</code>), and to manage upgrading data formats
inside those directories.</p>
<h3 id="contents-of-a-deployment">
<a href="#contents-of-a-deployment" class="anchor-heading" aria-labelledby="contents-of-a-deployment"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Contents of a deployment
</h3>
<p>A deployment begins with a specific commit (represented as a
SHA256 hash) in the OSTree repository in <code class="language-plaintext highlighter-rouge">/ostree/repo</code>. This commit refers
to a filesystem tree that represents the underlying basis of a
deployment. For short, we will call this the “tree”, to
distinguish it from the concept of a deployment.</p>
<p>First, the tree must include a kernel (and optionally an initramfs). The
current standard locations for these are <code class="language-plaintext highlighter-rouge">/usr/lib/modules/$kver/vmlinuz</code> and
<code class="language-plaintext highlighter-rouge">/usr/lib/modules/$kver/initramfs.img</code>. The “boot checksum” will be computed
automatically. This follows the current Fedora kernel layout, and is
the current recommended path. However, older versions of libostree don’t
support this; you may need to also put kernels in the previous (legacy)
paths, which are <code class="language-plaintext highlighter-rouge">vmlinuz(-.*)?-$checksum</code> in either <code class="language-plaintext highlighter-rouge">/boot</code> or <code class="language-plaintext highlighter-rouge">/usr/lib/ostree-boot</code>.
The checksum should be a SHA256 hash of the kernel contents; it must be
pre-computed before storing the kernel in the repository. Optionally,
the directory can also contain an initramfs, stored as
<code class="language-plaintext highlighter-rouge">initramfs(-.*)?-$checksum</code> and/or a device tree, stored as
<code class="language-plaintext highlighter-rouge">devicetree(-.*)?-$checksum</code>. If an initramfs or devicetree exist,
the checksum must include all of the kernel, initramfs and devicetree contents.
OSTree will use this to determine which kernels are shared. The rationale for
this is to avoid computing checksums on the client by default.</p>
<p>The deployment should not have a traditional UNIX <code class="language-plaintext highlighter-rouge">/etc</code>; instead, it
should include <code class="language-plaintext highlighter-rouge">/usr/etc</code>. This is the “default configuration”. When
OSTree creates a deployment, it performs a 3-way merge using the
<em>old</em> default configuration, the active system’s <code class="language-plaintext highlighter-rouge">/etc</code>, and the new
default configuration. In the final filesystem tree for a deployment
then, <code class="language-plaintext highlighter-rouge">/etc</code> is a regular writable directory.</p>
<p>Besides the exceptions of <code class="language-plaintext highlighter-rouge">/var</code> and <code class="language-plaintext highlighter-rouge">/etc</code> then, the rest of the
contents of the tree are checked out as hard links into the
repository. It’s strongly recommended that operating systems ship all
of their content in <code class="language-plaintext highlighter-rouge">/usr</code>, but this is not a hard requirement.</p>
<p>Finally, a deployment may have a <code class="language-plaintext highlighter-rouge">.origin</code> file, stored next to its
directory. This file tells <code class="language-plaintext highlighter-rouge">ostree admin upgrade</code> how to upgrade it.
At the moment, OSTree only supports upgrading a single refspec.
However, in the future OSTree may support a syntax for composing
layers of trees, for example.</p>
<h3 id="staged-deployments">
<a href="#staged-deployments" class="anchor-heading" aria-labelledby="staged-deployments"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Staged deployments
</h3>
<p>As mentioned above, when OSTree creates a new deployment, a 3-way merge is done
to update its <code class="language-plaintext highlighter-rouge">/etc</code>. Depending on the nature of the system, this can cause an
issue: if a user or program modifies the booted <code class="language-plaintext highlighter-rouge">/etc</code> <em>after</em> the pending
deployment is created but <em>before</em> rebooting, those modifications will be lost.
OSTree does not do a second <code class="language-plaintext highlighter-rouge">/etc</code> merge on reboot.</p>
<p>To counter this, OSTree supports staged deployments. In this flow, deployments
are created using e.g. <code class="language-plaintext highlighter-rouge">ostree admin upgrade --stage</code> on the CLI. The new
deployment is still created when the command is invoked, but the 3-way <code class="language-plaintext highlighter-rouge">/etc</code>
merge is delayed until the system is rebooted or shut down. Additionally,
updating the bootloader is also delayed. This is done by the
<code class="language-plaintext highlighter-rouge">ostree-finalize-staged.service</code> systemd unit.</p>
<p>The main disadvantage of this approach is that rebooting can take longer and the
failure mode can be confusing (the machine will reboot into the same
deployment). In systems where the workload is well-understood and not subject to
the <code class="language-plaintext highlighter-rouge">/etc</code> issue above, it may be better to not stage deployments.</p>
<h3 id="the-system-boot">
<a href="#the-system-boot" class="anchor-heading" aria-labelledby="the-system-boot"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> The system /boot
</h3>
<p>While OSTree parallel installs deployments cleanly inside the
<code class="language-plaintext highlighter-rouge">/ostree</code> directory, ultimately it has to control the system’s <code class="language-plaintext highlighter-rouge">/boot</code>
directory. The way this works is via the
<a href="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader Specification</a>,
which is a standard for bootloader-independent drop-in configuration
files.</p>
<p>When a tree is deployed, it will have a configuration file generated
of the form
<code class="language-plaintext highlighter-rouge">/boot/loader/entries/ostree-$stateroot-$checksum.$serial.conf</code>. This
configuration file will include a special <code class="language-plaintext highlighter-rouge">ostree=</code> kernel argument
that allows the initramfs to find (and <code class="language-plaintext highlighter-rouge">chroot()</code> into) the specified
deployment.</p>
<p>At present, not all bootloaders implement the BootLoaderSpec, so
OSTree contains code for some of these to regenerate native config
files (such as <code class="language-plaintext highlighter-rouge">/boot/syslinux/syslinux.conf</code>) based on the entries.</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/deployment.md" id="edit-this-page">Edit this page on GitHub</a>
</p>
</div>
</footer>
</div>
</div>
<div class="search-overlay"></div>
</div>
</body>
</html>
|
