docs/atomic-rollbacks: Add a section on rollbacks

Describing how different types of rollbacks work.

Signed-off-by: Eric Curtin <[email protected]>

docs/adapting-existing.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 6
+nav_order: 7
 ---
 
 # Adapting existing mainstream distributions

docs/atomic-rollbacks.md

@@ -0,0 +1,175 @@
+---
+nav_order: 6
+---
+
+# Atomic Rollback
+{: .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 will have multiple boot entries to choose from when performing a
+rollback, the bootloader will alternatively boot the "latest - 1" version.
+
+## 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)`

docs/authenticated-repos.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 9
+nav_order: 10
 ---
 
 # Handling access to authenticated remote repositories

docs/bootloaders.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 11
+nav_order: 12
 ---
 
 # Bootloaders

docs/buildsystem-and-repos.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 8
+nav_order: 9
 ---
 
 # Writing a buildsystem and managing repositories

docs/composefs.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 10
+nav_order: 11
 ---
 
 # Using composefs with OSTree

docs/formats.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 7
+nav_order: 8
 ---
 
 # OSTree data formats

docs/ima.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 10
+nav_order: 11
 ---
 
 # Using Linux IMA with OSTree

docs/related-projects.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 10
+nav_order: 11
 ---
 
 # Related Projects

docs/repository-management.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 9
+nav_order: 10
 ---
 
 # Managing content in OSTree repositories

docs/var.md

@@ -1,5 +1,5 @@
 ---
-nav_order: 6
+nav_order: 7
 ---
 
 # OSTree and /var handling