diff --git a/docs/adapting-existing.md b/docs/adapting-existing.md index 12df966f2b..137f6f9669 100644 --- a/docs/adapting-existing.md +++ b/docs/adapting-existing.md @@ -1,5 +1,5 @@ --- -nav_order: 6 +nav_order: 7 --- # Adapting existing mainstream distributions diff --git a/docs/atomic-rollbacks.md b/docs/atomic-rollbacks.md new file mode 100644 index 0000000000..6c5758ead4 --- /dev/null +++ b/docs/atomic-rollbacks.md @@ -0,0 +1,176 @@ +--- +nav_order: 6 +--- + +# 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 + +To manually rollback you can select an older entry via GRUB bootloader or in +the case of an Android bootloader, trigger a slot switch 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 + +An alternate technique to rolling back can be used. We can rollback into a +different runtime by using systemd targets. + +``` + +------------------------------------------------+ ++------------------+ | | +| | | | +| | | | +| | | (ostree:0) latest (multi-user.target) | +| | | | +| Bootloader |--->+ root | +| | | | +| | | (ostree:1) latest - 1 (rescue.target) | +| | | | +| | | | ++------------------+ | | + +------------------------------------------------+ +``` + +In this case instead of only rollback back to the last version, we also boot +into an alternate systemd target. Here we will describe how you can put +togther an alternate systemd target, using the built-in rescue.target as an +example. + +Below is a rescue.service file, it essentially executes: + +/usr/lib/systemd/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 not rolled back `ostree admin status -D` would +output `default`. + +ostree-rollback-to-rescue: + +``` +#!/usr/bin/bash + +set -ex + +if [ "$(ostree admin status -D)" = "not-default" ]; then + exec systemctl --no-block isolate rescue.target +fi +``` + +This is a systemd service file that checks early in the boot sequence if we +have rolled back (it executes ostree-rollback-to-rescue), 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/authenticated-repos.md b/docs/authenticated-repos.md index 7c872dc31e..20b555da1b 100644 --- a/docs/authenticated-repos.md +++ b/docs/authenticated-repos.md @@ -1,5 +1,5 @@ --- -nav_order: 9 +nav_order: 10 --- # Handling access to authenticated remote repositories diff --git a/docs/bootloaders.md b/docs/bootloaders.md index cb33d6f8ba..c8dd8d9f2d 100644 --- a/docs/bootloaders.md +++ b/docs/bootloaders.md @@ -1,5 +1,5 @@ --- -nav_order: 11 +nav_order: 12 --- # Bootloaders diff --git a/docs/buildsystem-and-repos.md b/docs/buildsystem-and-repos.md index e265ee7a03..6380fece02 100644 --- a/docs/buildsystem-and-repos.md +++ b/docs/buildsystem-and-repos.md @@ -1,5 +1,5 @@ --- -nav_order: 8 +nav_order: 9 --- # Writing a buildsystem and managing repositories diff --git a/docs/composefs.md b/docs/composefs.md index b95c61f6b4..471d289534 100644 --- a/docs/composefs.md +++ b/docs/composefs.md @@ -1,5 +1,5 @@ --- -nav_order: 10 +nav_order: 11 --- # Using composefs with OSTree diff --git a/docs/formats.md b/docs/formats.md index c372327999..6aaa16eebf 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -1,5 +1,5 @@ --- -nav_order: 7 +nav_order: 8 --- # OSTree data formats diff --git a/docs/ima.md b/docs/ima.md index 53fd10d893..7180c0dd35 100644 --- a/docs/ima.md +++ b/docs/ima.md @@ -1,5 +1,5 @@ --- -nav_order: 10 +nav_order: 11 --- # Using Linux IMA with OSTree diff --git a/docs/related-projects.md b/docs/related-projects.md index a2ba547de6..c85537cfa2 100644 --- a/docs/related-projects.md +++ b/docs/related-projects.md @@ -1,5 +1,5 @@ --- -nav_order: 10 +nav_order: 11 --- # Related Projects diff --git a/docs/repository-management.md b/docs/repository-management.md index 2db6383a86..77223a8cc9 100644 --- a/docs/repository-management.md +++ b/docs/repository-management.md @@ -1,5 +1,5 @@ --- -nav_order: 9 +nav_order: 10 --- # Managing content in OSTree repositories diff --git a/docs/var.md b/docs/var.md index 625359892d..f37c73579f 100644 --- a/docs/var.md +++ b/docs/var.md @@ -1,5 +1,5 @@ --- -nav_order: 6 +nav_order: 7 --- # OSTree and /var handling