Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

System rollback by booting from snapshots (New) #284

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

System rollback by booting from snapshots (New) #284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions DC-snapper-system-rollback
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <structure> 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"
205 changes: 205 additions & 0 deletions articles/snapper-system-rollback.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
<!-- This file can be edited downstream. -->
<!DOCTYPE assembly
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
<!ENTITY snapper "entity-value">
<!ENTITY yast "entity-value">
<!ENTITY zypper "entity-value">
<!ENTITY prompt.sudo "entity-value">
]>
<!-- legacy doc: https://github.com/SUSE/doc-sle/blob/maintenance/SLE15SP5/xml/snapper.xml
https://docs.suse.com/sles/15-SP5/single-html/SLES-administration/#cha-snapper -->
<!-- refer to README.md for file and id naming conventions -->
<assembly version="5.2" xml:lang="en"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns="http://docbook.org/ns/docbook">
<!-- resources section references all topic chunks used in the final article
-->
<!-- R E S O U R C E S -->
<!-- Glue files -->
<resources>
<resource xml:id="_snapper-system-rollback-limitations" href="../glues/snapper-system-rollback-limitations.xml">
<description>Limitations of &snapper;'s rollback feature</description>
</resource>
<resource xml:id="_snapper-system-rollback-more-info" href="../glues/snapper-system-rollback-more-info.xml">
<description>For more information</description>
</resource>
</resources>
<!-- Concept files -->
<resources>
<resource xml:id="_snapper-system-rollback-intro" href="../concepts/snapper-system-rollback-intro.xml">
<description>Introduction</description>
</resource>
</resources>
<!-- Tasks -->
<resources>
<resource xml:id="_snapper-system-rollback-from-bootable-snapshot" href="../tasks/snapper-system-rollback-from-bootable-snapshot.xml">
<description>Performing a rollback from a bootable snapshot</description>
</resource>
<resource xml:id="_snapper-system-rollback-access-identify-boot-entries" href="../tasks/snapper-system-rollback-access-identify-boot-entries.xml">
<description>Accessing and identifying snapshot boot entries</description>
</resource>
</resources>
<!-- References -->
<resources>
<resource xml:id="_snapper-system-rollback-after-rollback" href="../references/snapper-system-rollback-after-rollback.xml">
<description>Snapshots after rollback</description>
</resource>
</resources>
<!-- Legal -->
<resources>
<resource href="../common/legal.xml" xml:id="_legal">
<description>Legal Notice</description>
</resource>
<resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
<description>GNU Free Documentation License</description>
</resource>
</resources>
<!-- S T R U C T U R E -->
<structure renderas="article" xml:id="snapper-system-rollback" xml:lang="en">
<merge>
<title>System rollback by booting from snapshots with &snapper;</title>
<!-- Create changelog to enable versioning; add most recent entries at the top. -->
<revhistory xml:id="rh-snapper-system-rollback">
<revision><date>2024-01-10</date>
<revdescription>
<itemizedlist>
<!-- Group by type of change (added/removed/changed)-->
<listitem><para>Added sections:</para>
<itemizedlist>
<!-- Reference, but don't link to tracker items-->
<!-- Follow https://en.opensuse.org/openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations for tracker item references-->
<listitem><para>New section <quote>Important: Comparison of undoing changes and rollback</quote></para></listitem>
<!-- Name sections, but don't insert links -->
<listitem><para>New section <quote>For more information</quote></para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision><date>2023-12-10</date>
<revdescription>
<para>
Initial version.
</para>
</revdescription>
</revision>
</revhistory>
<!-- TODO: provide a listing of possible and validatable meta entry values. Maybe in our geekodoc repo? -->
<!-- add author's e-mail -->
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<!-- ISO date of last update as YYYY-MM-DD -->
<meta name="updated" content="2024-01-10" its:translate="no"/>
<!-- this does not work yet. Use the dm tags listed below for now
<meta name="bugtracker" its:translate="no">
<phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
<phrase role="component">Non-product-specific documentation</phrase>
<phrase role="product">Smart Docs</phrase>
<phrase role="assignee">[email protected]</phrase>
</meta>
-->
<!-- not supported, yet. Use dm: tag for now
<meta name="translation" its:translate="no">
<phrase role="trans">yes</phrase>
<phrase role="language">de-de,cs-cz</phrase>
</meta>
-->
<!-- enter the platform identifier or a list of
identifiers, separated by ; -->
<meta name="architecture" content="x86_64;zseries;power;aarch64" its:translate="no"/>
<meta name="productname" its:translate="no">
<!-- enter product name and version --><productname version="15-SP5">&sles;</productname>
</meta>
<meta name="title" its:translate="yes">Performing system rollback with &snapper;</meta>
<meta name="description" its:translate="yes">How to do a system rollback by booting from snapshots with &snapper;
allows to recover a misconfigured system</meta>
<meta name="social-descr" its:translate="yes">How to roll back your system with &snapper;</meta>
<!-- suitable category, comma-separated list of categories -->
<meta name="category" content="Systems Management" its:translate="no"/>
<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker>
<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
<dm:component>Smart Docs</dm:component>
<dm:product>Documentation</dm:product>
<!-- provide your BUGZILLA e-mail address, otherwise this does not work correctly-->
<dm:assignee>[email protected]</dm:assignee>
</dm:bugtracker>
<dm:translation>yes</dm:translation>
</dm:docmanager>
<abstract>
<variablelist>
<varlistentry>
<term>WHAT?</term>
<listitem>
<para>
This article describes how to use &snapper;'s rollback feature to perform a
rollback from a bootable snapshot.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WHY?</term>
<listitem>
<para>
You want to learn how to perform a system rollback with &snapper; and
how to access and identify snapshot boot entires.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EFFORT</term>
<listitem>
<para>
It takes up to 15 minutes to read about doing a rollback with &snapper;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REQUIREMENTS</term>
<listitem>
<itemizedlist>
<listitem>
<para>
The root file system needs to be Btrfs. Booting from LVM volume snapshots
is not supported.
</para>
</listitem>
<listitem>
<para>
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 <filename>/srv</filename> <!--(see <xref linkend="snapper-dir-excludes"/>
for a full list)--> may reside on separate partitions.
</para>
</listitem>
<listitem>
<para>
The system needs to be bootable via the installed boot loader.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</abstract>
</merge>
<!-- pull in all the topic files you need -->
<!-- pick the appropriate type of include to match your needs -->
<!-- pull in a topic as is -->
<module resourceref="_snapper-system-rollback-intro" renderas="section"/>
<module resourceref="_snapper-system-rollback-from-bootable-snapshot" renderas="section"/>
<module resourceref="_snapper-system-rollback-after-rollback" renderas="section"/>
<module resourceref="_snapper-system-rollback-access-identify-boot-entries" renderas="section"/>
<module resourceref="_snapper-system-rollback-limitations" renderas="section"/>
<module resourceref="_snapper-system-rollback-more-info" renderas="section"/>
<module resourceref="_legal"/>
<module resourceref="_gfdl">
<output renderas="appendix"/>
</module>
</structure>
</assembly>
75 changes: 75 additions & 0 deletions concepts/snapper-system-rollback-intro.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
<!-- This file can be edited downstream. -->
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="snapper-system-rollback-intro"
role="concept" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>System rollback with &snapper;</title><!-- can be changed via merge in the assembly -->
<!--add author's email address-->
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<abstract><!-- can be changed via merge in the assembly -->
<para>
&snapper;'s rollback feature that allows rolling back your system by
booting from snapshots is a powerful tool for system recovery and maintenance.
</para>
</abstract>
</info>
<para>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.</para>
<para>The &grub; version included on &productname; can boot
from <literal>Btrfs</literal> 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.</para>
<para>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.</para>
<para>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.</para>

<important>
<title>Supported configuration</title>
<para>
As of &productname; &productnumber;, system rollbacks are only supported if
the default subvolume configuration of the root partition has not been
changed.
</para>
</important>

<para>
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.
</para>

<important>
<title>Restoring to the identical state is not possible</title>
<para>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. <!--For more information, see Limitations.-->
</para>
</important>

</topic>
27 changes: 27 additions & 0 deletions glues/snapper-system-rollback-limitations.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
<!-- This file can be edited downstream. -->
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<topic xml:id="snapper-system-rollback-limitations"
role="glue" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>Limitations of &snapper;'s rollback feature</title><!-- can be changed via merge in the
assembly -->
<!--add author's e-mail address-->
<meta name="maintainer" content="" its:translate="no"/>
<!-- add an abstract/para here, if you need one -->
<!-- can be changed via merge in the assembly -->
</info>
<para>
Add web links to external sources or other SUSE articles.
</para>
</topic>
27 changes: 27 additions & 0 deletions glues/snapper-system-rollback-more-info.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
<!-- This file can be edited downstream. -->
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<topic xml:id="snapper-system-rollback-more-info"
role="glue" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>For more information</title><!-- can be changed via merge in the
assembly -->
<!--add author's e-mail address-->
<meta name="maintainer" content="" its:translate="no"/>
<!-- add an abstract/para here, if you need one -->
<!-- can be changed via merge in the assembly -->
</info>
<para>
Add web links to external sources or other SUSE articles.
</para>
</topic>
Binary file added images/snapper-main-yast.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/snapper-yast-restore.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading