diff --git a/DC-snapper-system-rollback b/DC-snapper-system-rollback new file mode 100644 index 000000000..c04adbff4 --- /dev/null +++ b/DC-snapper-system-rollback @@ -0,0 +1,17 @@ +# This file originates from the project https://github.com/openSUSE/doc-kit +# This file can be edited downstream. + +MAIN="snapper-system-rollback.asm.xml" +# Point to the ID of the of your assembly +# ROOTID="article-example" +SRC_DIR="articles" +IMG_SRC_DIR="images" + +PROFOS="generic" +PROFCONDITION="suse-product" +#PROFCONDITION="community-project" + +STYLEASSEMBLY="/usr/share/xml/docbook/stylesheet/nwalsh5/current/assembly/assemble.xsl" + +STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" +FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns" diff --git a/articles/snapper-system-rollback.asm.xml b/articles/snapper-system-rollback.asm.xml new file mode 100644 index 000000000..0413f4cb3 --- /dev/null +++ b/articles/snapper-system-rollback.asm.xml @@ -0,0 +1,205 @@ + + + + + %entities; + + + + +]> + + + + + + + + + Limitations of &snapper;'s rollback feature + + + For more information + + + + + + Introduction + + + + + + Performing a rollback from a bootable snapshot + + + Accessing and identifying snapshot boot entries + + + + + + Snapshots after rollback + + + + + + Legal Notice + + + GNU Free Documentation License + + + + + + System rollback by booting from snapshots with &snapper; + + + 2024-01-10 + + + + Added sections: + + + + New section Important: Comparison of undoing changes and rollback + + New section For more information + + + + + + 2023-12-10 + + + Initial version. + + + + + + + + + + + + + + + &sles; + + Performing system rollback with &snapper; + How to do a system rollback by booting from snapshots with &snapper; + allows to recover a misconfigured system + How to roll back your system with &snapper; + + + + + https://bugzilla.suse.com/enter_bug.cgi + Smart Docs + Documentation + + maintainer@suse.com + + yes + + + + + WHAT? + + + This article describes how to use &snapper;'s rollback feature to perform a + rollback from a bootable snapshot. + + + + + WHY? + + + You want to learn how to perform a system rollback with &snapper; and + how to access and identify snapshot boot entires. + + + + + EFFORT + + + It takes up to 15 minutes to read about doing a rollback with &snapper;. + + + + + REQUIREMENTS + + + + + The root file system needs to be Btrfs. Booting from LVM volume snapshots + is not supported. + + + + + The root file system needs to be on a single device, a single partition + and a single subvolume. Directories that are excluded from snapshots such + as /srv may reside on separate partitions. + + + + + The system needs to be bootable via the installed boot loader. + + + + + + + + + + + + + + + + + + + + + + + diff --git a/concepts/snapper-system-rollback-intro.xml b/concepts/snapper-system-rollback-intro.xml new file mode 100644 index 000000000..03444dad5 --- /dev/null +++ b/concepts/snapper-system-rollback-intro.xml @@ -0,0 +1,75 @@ + + + + + %entities; +]> + + + + + + + System rollback with &snapper; + + + + + &snapper;'s rollback feature that allows rolling back your system by + booting from snapshots is a powerful tool for system recovery and maintenance. + + + + The main use case for a rollback is recovery from misconfigurations. If a + system is misconfigured due to a faulty update or manual changes, rolling + back to a previous snapshot can save the day. By booting into a previous + snapshot, you can restore the system to its previous state and identify + the cause of the issue. + The &grub; version included on &productname; can boot + from Btrfs snapshots. Together with &snapper;'s rollback feature, this allows + to recover a misconfigured system. Please note that only snapshots created + for the default &snapper; configuration (&rootuser;) are bootable. + Rollback can be useful when testing new configurations. Before making + significant changes to a live system, it is often safer to test them in a + controlled environment. By creating a snapshot, you can boot into a copy + of the system that reflects the current state. You can then make changes, + test them, and if something goes wrong, simply roll back to the snapshot + without affecting the live system. + If you make a change to the system that causes issues, instead of + trying to fix it immediately, you can simply roll back to a previous snapshot. + This can save time and prevent further complications. + + + Supported configuration + + As of &productname; &productnumber;, system rollbacks are only supported if + the default subvolume configuration of the root partition has not been + changed. + + + + + When booting a snapshot, the parts of the file system included in the + snapshot are mounted read-only. This means that you can view and read + the files, but you cannot modify them. All other file systems and parts + that are excluded from snapshots are mounted read-write and can be modified. + + + + Restoring to the identical state is not possible + While a system rollback using snapshots can restore a system to a + previous state, it does not guarantee a complete rollback to the exact + state as it was in when the snapshot was taken. Some limitations exist, + such as certain directories being excluded from snapshots. + + + + diff --git a/glues/snapper-system-rollback-limitations.xml b/glues/snapper-system-rollback-limitations.xml new file mode 100644 index 000000000..df424d1f2 --- /dev/null +++ b/glues/snapper-system-rollback-limitations.xml @@ -0,0 +1,27 @@ + + + + + %entities; +]> + + + Limitations of &snapper;'s rollback feature + + + + + + + Add web links to external sources or other SUSE articles. + + diff --git a/glues/snapper-system-rollback-more-info.xml b/glues/snapper-system-rollback-more-info.xml new file mode 100644 index 000000000..5339521d1 --- /dev/null +++ b/glues/snapper-system-rollback-more-info.xml @@ -0,0 +1,27 @@ + + + + + %entities; +]> + + + For more information + + + + + + + Add web links to external sources or other SUSE articles. + + diff --git a/images/snapper-main-yast.png b/images/snapper-main-yast.png new file mode 100644 index 000000000..5935acfaa Binary files /dev/null and b/images/snapper-main-yast.png differ diff --git a/images/snapper-yast-restore.png b/images/snapper-yast-restore.png new file mode 100644 index 000000000..9ba5364e2 Binary files /dev/null and b/images/snapper-yast-restore.png differ diff --git a/references/snapper-system-rollback-after-rollback.xml b/references/snapper-system-rollback-after-rollback.xml new file mode 100644 index 000000000..ceeab7b55 --- /dev/null +++ b/references/snapper-system-rollback-after-rollback.xml @@ -0,0 +1,81 @@ + + + + + %entities; + +]> + + + + + + + Snapshots after a rollback + + + + + When you perform a rollback, &snapper; reverts the changes + that were made after the snapshot was created, and the file system + returns to the state it was in when the snapshot was taken. + + + +
+ &snapper; snapshots following a rollback + + Before a rollback is performed, &snapper; creates a snapshot of the + running file system. The Description references + the ID of the snapshot that was restored in the rollback. + + Snapshots created by rollbacks receive the value number + for the Cleanup attribute. The rollback snapshots are + therefore automatically deleted when the set number of snapshots is reached. + + If the snapshot contains important data, extract the data from the snapshot + before it is removed. + +
+
+ Example of a rollback snapshot + + For example, after a fresh installation, the following snapshots are + available on the system: + + + &prompt.root;snapper --iso list + Type | # | | Cleanup | Description | Userdata + -------+---+ ... +---------+-----------------------+-------------- + single | 0 | | | current | + single | 1 | | | first root filesystem | + single | 2 | | number | after installation | important=yes + + + After running sudo snapper rollback, snapshot + 3 is created and contains the state of the system + before the rollback was executed. Its Description + references snapshot 1 as the one used for the rollback. + Snapshot 4 is the new default Btrfs subvolume and + thus the system after a reboot. + + + &prompt.root;snapper --iso list + Type | # | | Cleanup | Description | Userdata + -------+---+ ... +---------+-----------------------+-------------- + single | 0 | | | current | + single | 1 | | number | first root filesystem | + single | 2 | | number | after installation | important=yes + single | 3 | | number | rollback backup of #1 | important=yes + single | 4 | | | | + +
+ diff --git a/tasks/snapper-system-rollback-access-identify-boot-entries.xml b/tasks/snapper-system-rollback-access-identify-boot-entries.xml new file mode 100644 index 000000000..75f8dc1d0 --- /dev/null +++ b/tasks/snapper-system-rollback-access-identify-boot-entries.xml @@ -0,0 +1,98 @@ + + + + + %entities; +]> + + + + + + + Executing task X (with tool Y) + + + + + Introductory text + + + +
+ Introduction + + A paragraph of text. + +
+
+ Requirements + + + + An + + + + + Unordered + + + + + List + + + + + A paragraph of text. + +
+
+ Executing the task + + A paragraph of text. + + + + A short introduction to the procedure. + + + + A step. + + + + + A second step. + + + + + A third step. + + + +
+
+ Summary + + A paragraph of text, summing up the result of the task. + +
+
+ Troubleshooting + + Add some troubleshooting information, if applicable. + +
+ diff --git a/tasks/snapper-system-rollback-from-bootable-snapshot.xml b/tasks/snapper-system-rollback-from-bootable-snapshot.xml new file mode 100644 index 000000000..47d8eea6b --- /dev/null +++ b/tasks/snapper-system-rollback-from-bootable-snapshot.xml @@ -0,0 +1,104 @@ + + + + + %entities; +]> + + + + + + + Performing a rollback from a bootable snapshot + + + + + This section contains a procedure that describes rolling back + the system from a bootable snapshot. + + + + + + To perform a rollback from a bootable snapshot, follow these steps: + + + + + + Boot the system. In the boot menu, choose Bootable + snapshots and select the snapshot you want to boot. The list of + snapshots is listed by date—the most recent snapshot is listed + first (it is most likely one of the last pre snapshots). + + + + + Log in to the system. Carefully check whether everything works as + expected. Note that the selected snapshot is read-only, so you cannot + write to any directory that is part of this snapshot. The data you write + to other directories will not get lost, regardless + of what you do next. + + + + + Depending on whether you want to perform the rollback or not, choose your + next step: + + + + + If the system is in a state where you do not want to do a rollback, + reboot to boot into the current system state. You can then choose a different + snapshot, or start the rescue system. + + + + + To perform the rollback, run: + + &prompt.sudo;snapper rollback + + All you need to do now is reboot your system to complete the + snapshot restore process. On the boot screen, choose the default + boot entry to reboot into the reinstated system. &snapper; creates + a snapshot of the file system status before the rollback. The default + subvolume for &rootuser; will be replaced with a fresh read-write + snapshot. For details, see . + + + It is useful to add a description for the snapshot with the option. + For example: + +New file system root since rollback on DATE TIME + + + + + + Rolling back to a specific installation state + + If snapshots are not disabled during installation, an initial bootable + snapshot is created at the end of the initial system installation. You can + go back to that state at any time by booting this snapshot. The snapshot + can be identified by the description after installation. + + + A bootable snapshot is also created when starting a system upgrade to a + service pack or a new major release (provided snapshots are not disabled). + + + +