Merge pull request #3171 from ericcurtin/docs-alternate-rollbacks

docs/atomic-rollbacks: Add a section on rollbacks
ostreedev · Feb 13, 2024 · eeccac7 · eeccac7
2 parents a3f9276 + bc5c071
commit eeccac7
Show file tree

Hide file tree

Showing 19 changed files with 194 additions and 18 deletions.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 19
+nav_order: 190
 ---
 
 # Contributing

diff --git a/docs/README-historical.md b/docs/README-historical.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 99
+nav_order: 990
 title: Historical OSTree README
 ---
 

diff --git a/docs/adapting-existing.md b/docs/adapting-existing.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 6
+nav_order: 70
 ---
 
 # Adapting existing mainstream distributions

diff --git a/docs/atomic-rollbacks.md b/docs/atomic-rollbacks.md
@@ -0,0 +1,176 @@
+---
+nav_order: 60
+---
+
+# Atomic Rollbacks
+{: .no_toc }
+
+1. TOC
+{:toc}
+
+## Automatic rollbacks
+
+See [greenboot](https://github.com/fedora-iot/greenboot/blob/main/README.md) for information on automatic rollbacks and how to integrate
+without your bootloader.
+
+## Manual rollbacks
+
+Ostree writes bootloader entries that are interpreted by the bootloader. To
+manually rollback, for bootloaders such as GRUB and syslinux that have an
+interactive UI, it is possible to select a previous boot entry. In the case of
+an Android bootloader, a slot switch may be triggererd using an AB switching
+tool. This may be useful for testing purposes.
+
+## Rollbacks
+
+```
+                        +------------------------------------------------+
++------------------+    |                                                |
+|                  |    |                                                |
+|                  |    |                                                |
+|                  |    |      (ostree:0) latest     (multi-user.target) |
+|                  |    |                                                |
+| Bootloader       |--->+ root                                           |
+|                  |    |                                                |
+|                  |    |      (ostree:1) latest - 1 (multi-user.target) |
+|                  |    |                                                |
+|                  |    |                                                |
++------------------+    |                                                |
+                        +------------------------------------------------+
+```
+
+Bootloaders have multiple boot entries to choose from after upgrade. On
+rollback, the bootloader will boot the "latest - 1" version, rather than the
+latest version of the OS.
+
+## Alternate rollback techniques
+
+Below is an alternate technique to traditional AB switching that can be used.
+On rollback, an alternative boot target is used, rather than booting as
+default.target.
+
+```
+                        +------------------------------------------------+
++------------------+    |                                                |
+|                  |    |                                                |
+|                  |    |                                                |
+|                  |    |      (ostree:0) latest     (multi-user.target) |
+|                  |    |                                                |
+| Bootloader       |--->+ root                                           |
+|                  |    |                                                |
+|                  |    |      (ostree:1) latest - 1 (rescue.target)     |
+|                  |    |                                                |
+|                  |    |                                                |
++------------------+    |                                                |
+                        +------------------------------------------------+
+```
+
+In this case, instead of rolling back to an older version, we also boot
+into an alternate systemd boot target. Here we will describe how you can put
+togther an alternate systemd boot target, using the built-in rescue.target as
+an example.
+
+Below is a rescue.service file, it essentially executes systemd-sulogin-shell
+rescue when this service is activated.
+
+rescue.service:
+
+```
+#  SPDX-License-Identifier: LGPL-2.1-or-later
+#
+#  This file is part of systemd.
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+
+[Unit]
+Description=Rescue Shell
+Documentation=man:sulogin(8)
+DefaultDependencies=no
+Conflicts=shutdown.target
+After=sysinit.target plymouth-start.service
+Before=shutdown.target
+
+[Service]
+Environment=HOME=/root
+WorkingDirectory=-/root
+ExecStartPre=-/usr/bin/plymouth --wait quit
+ExecStart=-/usr/lib/systemd/systemd-sulogin-shell rescue
+Type=idle
+StandardInput=tty-force
+StandardOutput=inherit
+StandardError=inherit
+KillMode=process
+IgnoreSIGPIPE=no
+SendSIGHUP=yes
+```
+
+Below is a rescue.target file, it is reached once rescue.service is complete.
+
+rescue.target:
+
+```
+#  SPDX-License-Identifier: LGPL-2.1-or-later
+#
+#  This file is part of systemd.
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+
+[Unit]
+Description=Rescue Mode
+Documentation=man:systemd.special(7)
+Requires=sysinit.target rescue.service
+After=sysinit.target rescue.service
+AllowIsolate=yes
+```
+
+This is a simple bash script, it checks whether `ostree admin status -D` is
+`not-default` and if it is, it notifies systemd to alternatively boot into
+rescue.target.
+
+In the happy path, when we have booted the latest version
+`ostree admin status -D` would output `default`.
+
+ostree-rollback-to-rescue:
+
+```
+#!/usr/bin/bash
+
+set -euo pipefail
+
+if [ "$(ostree admin status -D)" = "not-default" ]; then
+  exec systemctl --no-block isolate rescue.target
+fi
+```
+
+This is a systemd service file that runs ostree-rollback-to-rescue early in the
+boot sequence, it is essential that this service is run early to ensure we
+don't execute a full boot sequence, hence options `DefaultDependencies=no` and
+`Before=` are used.
+
+ostree-rollback-to-rescue.service
+
+```
+[Unit]
+Description=OSTree rollback to rescue
+DefaultDependencies=no
+OnFailure=emergency.target
+OnFailureJobMode=replace-irreversibly
+After=initrd-root-fs.target initrd-fs.target initrd.target boot.mount
+Before=cryptsetup.target integritysetup.target remote-fs.target slices.target swap.target veritysetup.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/sbin/ostree-rollback-to-rescue
+
+[Install]
+WantedBy=sysinit.target
+```
+
+###### Licensing for this document:
+`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`
diff --git a/docs/atomic-upgrades.md b/docs/atomic-upgrades.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 5
+nav_order: 50
 ---
 
 # Atomic Upgrades

diff --git a/docs/authenticated-repos.md b/docs/authenticated-repos.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 9
+nav_order: 100
 ---
 
 # Handling access to authenticated remote repositories

diff --git a/docs/bootloaders.md b/docs/bootloaders.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 11
+nav_order: 120
 ---
 
 # Bootloaders

diff --git a/docs/buildsystem-and-repos.md b/docs/buildsystem-and-repos.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 8
+nav_order: 90
 ---
 
 # Writing a buildsystem and managing repositories

diff --git a/docs/composefs.md b/docs/composefs.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 10
+nav_order: 110
 ---
 
 # Using composefs with OSTree

diff --git a/docs/contributing-tutorial.md b/docs/contributing-tutorial.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 20
+nav_order: 200
 ---
 
 # OSTree Contributing Tutorial

diff --git a/docs/deployment.md b/docs/deployment.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 4
+nav_order: 40
 ---
 
 # Deployments

diff --git a/docs/formats.md b/docs/formats.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 7
+nav_order: 80
 ---
 
 # OSTree data formats

diff --git a/docs/ima.md b/docs/ima.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 10
+nav_order: 110
 ---
 
 # Using Linux IMA with OSTree

diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 1
+nav_order: 10
 ---
 
 # libostree

diff --git a/docs/introduction.md b/docs/introduction.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 2
+nav_order: 20
 ---
 
 # OSTree Overview

diff --git a/docs/related-projects.md b/docs/related-projects.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 10
+nav_order: 110
 ---
 
 # Related Projects

diff --git a/docs/repo.md b/docs/repo.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 3
+nav_order: 30
 ---
 
 # Anatomy of an OSTree repository

diff --git a/docs/repository-management.md b/docs/repository-management.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 9
+nav_order: 100
 ---
 
 # Managing content in OSTree repositories

diff --git a/docs/var.md b/docs/var.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 6
+nav_order: 70
 ---
 
 # OSTree and /var handling