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

Jump to bottom

Using Snapper to undo changes #232

Open
wants to merge 25 commits into
base: main
Choose a base branch
from
Open

Using Snapper to undo changes #232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
4950c23
Create assembly for Undoing changes with Snapper
dariavladykina Nov 6, 2023
3e8f06e
Update main file
dariavladykina Nov 6, 2023
63b9a6d
Add concept introduction
dariavladykina Nov 6, 2023
9e26497
Add task and glue topics
dariavladykina Nov 6, 2023
9bcd848
Fix validation
dariavladykina Nov 6, 2023
3904870
Fix validation errors
dariavladykina Nov 10, 2023
5b0ec2e
Remove task, create content for concept and task
dariavladykina Nov 22, 2023
57f363e
Create content for concept topic
dariavladykina Nov 22, 2023
eca0ef1
Fix validation
dariavladykina Nov 22, 2023
6129f66
Create content for glue topic
dariavladykina Nov 23, 2023
cea5020
Create content for task topics
dariavladykina Nov 24, 2023
846621c
Create content for task and glue topics
dariavladykina Nov 27, 2023
1a79291
Added images to the task
dariavladykina Dec 1, 2023
8aba67f
Add missing IMG_SRC_DIR variable to DC file
tomschr Dec 1, 2023
5f084ed
Update glues/snapper-undo-changes-compare-undo-and-rollback.xml
dariavladykina Jan 4, 2024
a8f2323
Update concepts/snapper-undo-changes-intro.xml
dariavladykina Jan 4, 2024
f0226c6
Update glues/snapper-undo-changes-compare-undo-and-rollback.xml
dariavladykina Jan 4, 2024
6aab3ad
Update glues/snapper-undo-changes-compare-undo-and-rollback.xml
dariavladykina Jan 4, 2024
8e80e98
Update tasks/snapper-undo-changes-yast-zypper.xml
dariavladykina Jan 4, 2024
4e9eb4a
Update content, optimize images and screens, accommodate review comments
dariavladykina Jan 4, 2024
bf40eac
Update articles/snapper-undo-changes.asm.xml
dariavladykina Jan 4, 2024
00dfa20
Update articles/snapper-undo-changes.asm.xml
dariavladykina Jan 4, 2024
571cbce
Update assembly with new template
dariavladykina Mar 27, 2024
f45b111
Update meta task spelling
dariavladykina Mar 28, 2024
96b8588
Add rootid to DC file
dariavladykina Mar 28, 2024
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-undo-changes
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-undo-changes.asm.xml"
ROOTID="snapper-undo-changes"
SRC_DIR="articles"
IMG_SRC_DIR="images"

PROFOS="generic"
#PROFCONDITION="suse-product"
#PROFCONDITION="suse-product;beta"
#PROFCONDITION="community-project"

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
XSLTPARAM="--param generate.json-ld=1 "
169 changes: 169 additions & 0 deletions articles/snapper-undo-changes.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- file: templates/articles/assembly.xml -->
<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
type="application/relax-ng-compact-syntax"?>
<!DOCTYPE assembly
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- 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
-->
<!-- 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 -->
<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:xi="http://www.w3.org/2001/XInclude"
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-undo-changes-more-info" href="../glues/snapper-undo-changes-more-info.xml">
<description>For more information</description>
</resource>
<resource xml:id="_snapper-undo-changes-compare-undo-and-rollback" href="../glues/snapper-undo-changes-compare-undo-and-rollback.xml">
<description>Comparing rollback and undoing changes</description>
</resource>
</resources>
<!-- Concept files -->
<resources>
<resource xml:id="_snapper-undo-changes-intro" href="../concepts/snapper-undo-changes-intro.xml">
<description>Introduction</description>
</resource>
<resource xml:id="_snapper-undo-changes-yast-zypper" href="../tasks/snapper-undo-changes-yast-zypper.xml">
<description>Undoing &yast; and &zypper; changes</description>
</resource>
<resource xml:id="_snapper-undo-changes-restore-files" href="../tasks/snapper-undo-changes-restore-files.xml">
<description>Restoring files with &snapper;</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-undo-changes" xml:lang="en">
<merge>
<title>Using &snapper; to undo changes</title>
<revhistory xml:id="rh-snapper-undo-changes">
<revision><date>2024-01-04</date>
<revdescription>
<para>
This topic merges and updates the content about using Snapper to
undo changes and restore files from the Snapper chapter 10.2 in
the &productname; Admin Guide.
</para>
</revdescription>
</revision>
</revhistory>
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<meta name="updated" content="2023-11-11" its:translate="no"/>
<meta name="architecture">
<phrase>&x86-64;</phrase>
<phrase>&power;</phrase>
<phrase>&zseries;</phrase>
<phrase>&aarch64;</phrase>
</meta>
<meta name="productname" its:translate="no">
<productname version="1">&alp;</productname>
</meta>
<meta name="title" its:translate="yes">Using &snapper; to undo changes</meta>
<meta name="description" its:translate="yes">How to use &snapper; to undo &yast; and &zypper; changes
and restore files; comparison between undoing changes and rollback</meta>
<meta name="social-descr" its:translate="yes">Undo &yast; and &zypper; changes with &snapper;</meta>
<meta name="task">
<phrase>Backup &amp; Recovery</phrase>
<phrase>Administration</phrase>
</meta>
<meta name="series">Products &amp; Solutions</meta>
<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>
<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; in its default configuration
to undo changes performed with &yast; and &zypper; and to restore files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WHY?</term>
<listitem>
<para>
You aim to learn about &snapper;'s most commonly used functionality: undoing changes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EFFORT</term>
<listitem>
<para>
It takes up to 15 minutes to read about reverting changes and restoring files
with &snapper;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REQUIREMENTS</term>
<listitem>
<itemizedlist>
<listitem>
<para>
&rootuser; or &sudo; privileges
</para>
</listitem>
<listitem>
<para>
Snapper needs to be installed. It is available on &productname; by default.
</para>
</listitem>
<listitem>
<para>
The root partition (<filename>/</filename>) size of at least 16&nbsp;GB.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>This article is the second installment of the series of articles
about &snapper;. In the first article, we covered the core principles
of &snapper;&mdash;see
<link xlink:href="https://documentation.suse.com/smart/systems-management/html/snapper-basic-concepts/index.html">The Basic Concepts of Snapper</link>.
Subsequent articles will cover &snapper;'s other use cases such as rolling
back the system, manually creating and managing snapshots, and automatic
snapshot cleanup.</para><!--Add a link to "For more information"
(to be created) with links to other articles from this series and reading order.-->
</note>
</abstract>
</merge>
<module resourceref="_snapper-undo-changes-intro" renderas="section"/>
<module resourceref="_snapper-undo-changes-yast-zypper" renderas="section"/>
<module resourceref="_snapper-undo-changes-restore-files" renderas="section"/>
<module resourceref="_snapper-undo-changes-compare-undo-and-rollback" renderas="section"/>
<module resourceref="_snapper-undo-changes-more-info" renderas="section"/>
<module resourceref="_legal" renderas="section"/>
<module resourceref="_gfdl" renderas="appendix"/>
</structure>
</assembly>
96 changes: 96 additions & 0 deletions concepts/snapper-undo-changes-intro.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
<!ENTITY snapper "entity-value">
<!ENTITY productname "entity-value">
<!ENTITY yast "entity-value">
<!ENTITY zypper "entity-value">
]>
<!-- refers to legacy doc: https://documentation.suse.com/sles/15-SP5/single-html/SLES-administration/#cha-snapper -->
<!-- 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-undo-changes-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>Default configuration</title>
dariavladykina marked this conversation as resolved.
Show resolved Hide resolved
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<abstract>
<para>
&snapper; on &productname; is preconfigured to serve as a tool that lets you
undo changes made by <command>zypper</command> and &yast;. It does this
by creating a pair of snapshots before and after each run of <command>zypper</command>
and &yast;.</para>
</abstract>
</info>
<para>
Taking snapshot pairs upon installing packages with &yast; or &zypper; is
handled by <systemitem class="resource">snapper-zypp-plugin</systemitem>. An XML
configuration file, <filename>/etc/snapper/zypp-plugin.conf</filename>, defines
when to make snapshots. By default, the file looks like the following:
</para>
<screen linenumbering="numbered">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;snapper-zypp-plugin-conf&gt;
&lt;solvables&gt;
&lt;solvable match="w"<co xml:id="zypp-conf-match"/> important="true"<co xml:id="zypp-conf-important"/>&gt;kernel-*<co xml:id="zypp-conf-kernel"/>&lt;/solvable&gt;
&lt;solvable match="w" important="true"&gt;dracut&lt;/solvable&gt;
&lt;solvable match="w" important="true"&gt;glibc&lt;/solvable&gt;
&lt;solvable match="w" important="true"&gt;systemd*&lt;/solvable&gt;
&lt;solvable match="w" important="true"&gt;udev&lt;/solvable&gt;
&lt;solvable match="w"&gt;*&lt;/solvable&gt;<co xml:id="zypp-conf-packages"/>
&lt;/solvables&gt;
&lt;/snapper-zypp-plugin-conf&gt;</screen>
<calloutlist>
<callout arearefs="zypp-conf-match">
<para>
The match attribute defines whether the pattern is a Unix shell-style
wild card (<literal>w</literal>) or a Python regular expression
(<literal>re</literal>). For more information about regular expressions in Python,
refer to <link xlink:href="https://docs.python.org/3/library/re.html">Regular expression operations</link>.
</para>
</callout>
<callout arearefs="zypp-conf-important">
<para>
If the pattern matches and the corresponding package is marked as
important (for example, kernel packages), the snapshot will also be
marked as important.
</para>
</callout>
<callout arearefs="zypp-conf-kernel">
<para>
Pattern to match a package name. Based on the setting of the
<literal>match</literal> attribute, special characters are
interpreted as shell wild cards or regular expressions. This pattern
matches all package names, starting with <literal>kernel-</literal>.
</para>
</callout>
<callout arearefs="zypp-conf-packages">
<para>
This line unconditionally matches all packages.
</para>
</callout>
</calloutlist>
<para>
With this configuration snapshot, pairs are made whenever a package is
installed (see <xref linkend="zypp-conf-packages"/>). When the kernel, dracut, glibc, systemd, or udev packages
marked as important are installed, the snapshot pair will also be marked
as important. All rules are evaluated.
</para>
<para>By default, automatic snapshots as described above are configured for the
root partition and its subvolumes. To make snapshots available for other
partitions such as <filename>/home</filename>, for example, you can create
custom configurations.
</para>
<para>&snapper; also lets you restore system files that have been accidentally
deleted or modified. Timeline snapshots for the root partition need to be
enabled for this purpose.</para>

</topic>
63 changes: 63 additions & 0 deletions glues/snapper-undo-changes-compare-undo-and-rollback.xml
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice topic! The only issue that I have is with the links to non-existing sections or yet-to-be-written articles. Even if they are resolved one day, the disrupt the flow and might make readers jump from this article and never come back.

Only add those links when the reader absolutely needs this reference to proceed with what you're describing. Otherwise put'em right to the end of the article under "For more info".

Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
<!ENTITY snapper "entity-value">
]>
<topic xml:id="snapper-undo-changes-compare-undo-and-rollback"
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>Undoing changes compared to rollback with &snapper;</title><!-- can be changed via merge in the assembly -->
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<abstract>
<para>When working with snapshots to restore data, it is important to know that
there are two fundamentally different scenarios &snapper; can handle:
undoing changes and rollback. The key difference between them is the level
of granularity and the scope of the operation.</para>
</abstract>
<!-- can be changed via merge in the assembly -->
</info>

<section xml:id="sec-snapper-undo">
<title>Undoing changes with &snapper;</title>
<para>To undo changes made between two snapshots, the <command>undochange</command>
command is used. This command allows you to reverse the effects of a specific
action within a transaction without impacting subsequent changes. For example,
if you have a configuration file that was modified in a certain snapshot and
you want to revert that change, use the <command>undochange</command>
command to do so.</para>
<para>
When undoing changes, two snapshots are
being compared and the changes between these two snapshots are made
undone. Using this method, you can explicitly select the files
that need to be restored.
</para>
</section>

<section xml:id="sec-snapper-rollback">
<title>Rollback with &snapper;</title>
<para>In comparison with undoing changes, a rollback is a more comprehensive
operation that reverts the entire file system to a previous snapshot, including
configurations and system files. This is useful when you want to revert
multiple transactions and return the system to a previous state, erasing
all changes made after a specific transaction.</para>
<para>
When doing rollbacks, <!-- as described in <xref linkend="sec-snapper-snapshot-boot"/> -->
the system is reset to the state at which the snapshot was taken.
</para>
<para>
When undoing changes, it is also possible to compare a snapshot against the
current system. When restoring <emphasis>all</emphasis> files from such a
comparison, this will have the same result as doing a rollback. <!--However,
using the method described in <xref linkend="sec-snapper-snapshot-boot"/>
for rollbacks should be preferred, since it is faster and allows you to
review the system before doing the rollback.-->
</para>
</section>
</topic>
50 changes: 50 additions & 0 deletions glues/snapper-undo-changes-more-info.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
<!ENTITY snapper "entity-value">
]>
<topic xml:id="snapper-undo-changes-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 email address -->
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<!-- add an abstract/para here, if you need one -->
<!-- can be changed via merge in the assembly -->
</info>
<itemizedlist>
<listitem>
<para>
For more detailed information on how to do system rollback by
booting from snapshots, see
<!--<link xlink:href="https://documentation.suse.com/smart/...">System rollback by booting from snapshots</link>.-->
</para>
</listitem>
<listitem>
<para>
For more information on creating additional &snapper; configurations, see
<!--<link xlink:href="https://documentation.suse.com/smart/...">Creating and modifying Snapper configurations</link>.-->
</para>
</listitem>
<listitem>
<para>
For more information about backup snapshots, see
<!--<link xlink:href="https://documentation.suse.com/smart/..."/>Snapshot types based on triggering events.-->
</para>
</listitem>
<listitem>
<para>
For more information about creating custom configurations, see <!--TODO: Add link to custom configurations:
Create content on this question.-->
</para>
</listitem>
</itemizedlist>

</topic>
Binary file added images/snapper-yast-changes.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-diff.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-list.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
Loading