From bc5c0717fc5af040a98d73f1fbd25e4800cdbaef Mon Sep 17 00:00:00 2001 From: Eric Curtin 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 --- 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