From: Cheng-Ling Lai <jameslai.tech@gmail.com>
Date: Thu, 23 Apr 2026 08:26:15 +0000 (+0800)
Subject: Update snbk documentation for snapper-sync
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6a9ab4ea6be1376bbc4c3c56b688a00db9745bb1;p=thirdparty%2Fsnapper.git

Update snbk documentation for snapper-sync
---

diff --git a/doc/snbk.xml.in b/doc/snbk.xml.in
index 93c63288..bb384f0f 100644
--- a/doc/snbk.xml.in
+++ b/doc/snbk.xml.in
@@ -2,13 +2,13 @@
 <refentry id='snbk8' xmlns:xlink="http://www.w3.org/1999/xlink">
 
   <refentryinfo>
-    <date>2026-01-16</date>
+    <date>2026-04-23</date>
   </refentryinfo>
 
   <refmeta>
     <refentrytitle>snbk</refentrytitle>
     <manvolnum>8</manvolnum>
-    <refmiscinfo class='date'>2026-01-16</refmiscinfo>
+    <refmiscinfo class='date'>2026-04-23</refmiscinfo>
     <refmiscinfo class='version'>@VERSION@</refmiscinfo>
     <refmiscinfo class='manual'>Filesystem Snapshot Management</refmiscinfo>
   </refmeta>
@@ -140,6 +140,67 @@
       </para>
     </refsect2>
 
+    <refsect2 id='snapshot-number-sync'>
+      <title>Highest Snapshot Number Synchronization</title>
+
+      <para>To avoid reusing snapshot numbers, 'snapperd' keeps the highest snapshot
+      folder (whether it is an empty snapshot or not) in <filename>.snapshots</filename>
+      directory, ensuring snapshot numbers remain unique at all times.
+      However, when performing a restore using various methods, the state of the highest
+      snapshot number may vary:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Synchronized: The latest backed-up snapshot is restored to
+	  <filename>.snapshots</filename> using `snbk restore` or manual Btrfs
+	  send-receive.
+	  In this case, the highest snapshot number is synchronized.
+	  'snapperd' creates snapshots with numbers greater than the restored snapshot,
+	  preventing snapshot number collisions.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Legacy: A restore is made with a previous but not the latest backed-up
+	  snapshot.
+	  In this case, the state of the highest snapshot number is not valid.
+	  'snapperd' would create snapshots with numbers lower than the latest backed-up
+	  snapshot.
+	  This could invalidate the backed-up snapshots created later than the restored
+	  snapshot, and these invalid backed-up snapshots might be removed during the
+	  automatic Snapper backup process.
+	</para>
+	</listitem>
+	<listitem>
+	  <para>Legacy: When using a virtualization platform and the system is restored
+	  from a virtual machine backup.
+	  In this case, depending on the timing of the VM backup creation, the state of
+	  the highest snapshot number might not be synchronized.
+	  Snapshot number collisions might occur when 'snapperd' creates snapshots after
+	  the VM boots up.
+	  </para>
+	</listitem>
+
+      </itemizedlist>
+
+      <para>To avoid snapshot number collisions, The Snapper Backup package provides a
+      'snapper-sync' script, which can be triggered by `snapper-sync.service`, to
+      synchronize the highest snapshot number across the source and backup target devices.
+      Please consider enabling `snapper-sync.service` if any scenario related to 'Legacy'
+      might occur in your environment.
+
+      If any custom systemd timer or service is configured, please consider adding
+      the following directives:
+
+	<programlisting>
+[Unit]
+After=snapper-sync.service
+	</programlisting>
+
+      This ensures systemd schedules the custom unit to run after the highest snapshot
+      number synchronization.</para>
+
+    </refsect2>
+
   </refsect1>
 
   <refsect1 id='global_options'>