Update snapper documentation to include snapper-sync

Author: jameslai-dev

doc/snapper.xml.in

@@ -192,6 +192,71 @@
       snapshotted. For that, use subvolumes or mount points.</para>
     </refsect2>
 
+    <refsect2 id='snapshot-number-sync'>
+      <title>Highest Snapshot Number Synchronization with 'snbk' (Btrfs Only)</title>
+
+      <para>This section is only relevant when the filesystem is Btrfs and the Snapper
+      backup tool (snbk) is used.
+      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, Snapper 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.
+      This requires a properly configured 'snbk'. If 'snbk' is not installed, the script
+      does nothing.
+      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'>