From bc5c0717fc5af040a98d73f1fbd25e4800cdbaef Mon Sep 17 00:00:00 2001
From: Eric Curtin <ecurtin@redhat.com>
Date: Tue, 13 Feb 2024 10:39:20 +0000
Subject: [PATCH] docs/atomic-rollbacks: Add a section on rollbacks
Describing how different types of rollbacks work.
Signed-off-by: Eric Curtin <ecurtin@redhat.com>
---
docs/CONTRIBUTING.md | 2 +-
docs/README-historical.md | 2 +-
docs/adapting-existing.md | 2 +-
docs/atomic-rollbacks.md | 176 ++++++++++++++++++++++++++++++++++
docs/atomic-upgrades.md | 2 +-
docs/authenticated-repos.md | 2 +-
docs/bootloaders.md | 2 +-
docs/buildsystem-and-repos.md | 2 +-
docs/composefs.md | 2 +-
docs/contributing-tutorial.md | 2 +-
docs/deployment.md | 2 +-
docs/formats.md | 2 +-
docs/ima.md | 2 +-
docs/index.md | 2 +-
docs/introduction.md | 2 +-
docs/related-projects.md | 2 +-
docs/repo.md | 2 +-
docs/repository-management.md | 2 +-
docs/var.md | 2 +-
19 files changed, 194 insertions(+), 18 deletions(-)
create mode 100644 docs/atomic-rollbacks.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index f7d7a5caa1..8ee1fdcc79 100644
--- 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
index eebf5b2fe3..eba0960f15 100644
--- 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
index 12df966f2b..422ba498cc 100644
--- 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
new file mode 100644
index 0000000000..61405663e4
--- /dev/null
+++ 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
index 92ae2c49f1..414bdccd7b 100644
--- 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
index 7c872dc31e..65d360acc1 100644
--- 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
index cb33d6f8ba..b93b18c6ca 100644
--- 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
index e265ee7a03..5c57813111 100644
--- 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
index b95c61f6b4..528141a375 100644
--- 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
index d3db4cf70f..3341ad9009 100644
--- 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
index 98a1bdb876..7df292d5a7 100644
--- 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
index c372327999..74be428fd0 100644
--- 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
index 53fd10d893..bebb3817ff 100644
--- 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
index 1de55f2f42..23dfe57ed6 100644
--- 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
index a6fa22528b..df64b5850a 100644
--- 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
index a2ba547de6..7eb464ccc2 100644
--- 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
index 580281cacb..31e6d809d0 100644
--- 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
index 2db6383a86..9760bf690a 100644
--- 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
index 625359892d..90c119805f 100644
--- a/docs/var.md
+++ b/docs/var.md
@@ -1,5 +1,5 @@
---
-nav_order: 6
+nav_order: 70
---
# OSTree and /var handling