diff options
Diffstat (limited to 'deployment/index.html')
| -rw-r--r-- | deployment/index.html | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/deployment/index.html b/deployment/index.html new file mode 100644 index 00000000..51e77350 --- /dev/null +++ b/deployment/index.html @@ -0,0 +1,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> + |