mounts: track mount state and provenance explicitly

doc/user_guide.rst

@@ -232,13 +232,12 @@ that is what ``snapset mount`` reports for a default mount.
 Any contents the directory has are shadowed while the snapshot set is
 mounted, and reappear when it is unmounted.
 
-``snapm`` locates snapshot set mounts by matching the set's member
-devices against the system mount table, so a set mounted at a custom
-mount root is found automatically: ``snapset umount`` does not need to
-be told where the set was mounted. The ``--mount-root`` option is
-accepted by ``snapset umount`` as well, but is only required to select
-between mounts when the same snapshot set is mounted at more than one
-path:
+``snapm`` records each mount it makes in ``/run/snapm/mount-state``, so
+a set mounted at a custom mount root is found again automatically:
+``snapset umount`` does not need to be told where the set was mounted.
+The ``--mount-root`` option is accepted by ``snapset umount`` as well,
+but is only required to select between mounts when the same snapshot
+set is mounted at more than one path:
 
 .. code-block:: bash
 
@@ -255,6 +254,66 @@ path:
 Each path reported by an ambiguous ``umount`` selects that mount when
 passed back as ``--mount-root``.
 
+Mounts snapm did not make
+-------------------------
+
+Only a mount that ``snapm`` made has a record in
+``/run/snapm/mount-state``, and only a mount with a record is one that
+``snapm`` will unmount or remove the mount point of. A snapshot mounted
+by hand is therefore left alone, even though its device belongs to a
+snapshot set that ``snapm`` knows about:
+
+.. code-block:: bash
+
+   # Mount a snapshot set's root snapshot directly
+   sudo mount /dev/fedora/root-snapset_backup_1234567890_- /mnt/inspect
+
+   # snapm does not claim it: there is nothing of its own to unmount
+   sudo snapm snapset umount backup
+
+Because the records live in ``/run`` they last exactly as long as the
+mounts they describe, and both go away at reboot. A snapshot set that
+was already mounted when ``snapm`` was upgraded to a version that
+writes these records has no record either, and has to be unmounted with
+``umount -R`` by hand.
+
+Finding snapm mounts
+--------------------
+
+Every mount ``snapm`` makes carries the mount option
+``x-snapm.managed=<uuid>``, naming the snapshot set that is mounted.
+The option is in the ``x-`` namespace, so the kernel never sees it:
+``mount`` keeps it in ``/run/mount/utab``, and ``findmnt`` reports it
+alongside the kernel's own options in ``--mtab`` mode. This lists every
+mount ``snapm`` made, wherever in the file system it appears:
+
+.. code-block:: bash
+
+   # findmnt -m -o TARGET,OPTIONS -O x-snapm.managed
+   TARGET      OPTIONS
+   /mnt        rw,relatime,seclabel,nouuid,x-snapm.managed=f48e...
+   /mnt/opt    rw,relatime,seclabel,x-snapm.managed=f48e...
+   /mnt/proc   rw,nosuid,nodev,noexec,relatime,x-snapm.managed=f48e...
+
+Add the snapshot set UUID to the filter to list the mounts of one set:
+
+.. code-block:: bash
+
+   sudo findmnt -m -o TARGET -O x-snapm.managed=$(
+       sudo snapm snapset show --json backup | jq -r '.[0].UUID')
+
+The option is more than a label for the administrator's benefit.
+``snapm`` decides what it owns from the records in
+``/run/snapm/mount-state``, and a record names the mount it describes by
+this option as well as by the device mounted there. A device number
+names a file system rather than one mount of it: a record outlives a
+mount taken down outside ``snapm`` until the next command that writes
+reaps it, and without the option a mount made by hand of the same
+snapshot device at the same path in that window would answer to the
+record left behind. The option is recorded by ``mount`` with the mount
+and removed by ``umount`` with it, so it marks that mount and no later
+one.
+
 Keep the mount point and the directory containing it owned by root and
 inaccessible to other users while the snapshot set is mounted, and open
 up access as the final step. A directory another user can write to lets
@@ -869,9 +928,11 @@ Rename an existing snapset.
 
    snapm snapset rename <old_name> <new_name>
 
-A mounted snapshot set cannot be renamed because the mount table records
-its member device names at mount time. Unmount the set with
-``snapm snapset umount`` before renaming it.
+A mounted snapshot set cannot be renamed: its mount point path embeds
+the set name by default, and the record of the mount in
+``/run/snapm/mount-state`` identifies the set by its name and UUID, both
+of which a rename changes. Unmount the set with ``snapm snapset umount``
+before renaming it.
 
 snapset revert
 --------------

man/man8/snapm.8

@@ -1372,15 +1372,29 @@ omit \fB--mount-root\fP to mount beneath it. \fBsnapm\fP does not create the
 directory, and does not remove it when the snapshot set is unmounted.
 Its permissions are the administrator's to set, and any contents it has are
 shadowed while the snapshot set is mounted.
+.sp
+Every mount in the tree carries the \fBx-snapm.managed=\fP\fIuuid\fP mount
+option, naming the snapshot set that is mounted, so that the mounts
+\fBsnapm\fP made can be listed wherever they are:
+.sp
+.EX
+# findmnt -m -o TARGET,OPTIONS -O x-snapm.managed
+.EE
+.sp
+The option is in the "x-" namespace, so it is kept in
+\fI/run/mount/utab\fP by \fBmount\fP(8) rather than by the kernel, and
+\fBfindmnt\fP(8) only reports it in \fB--mtab\fP mode.
 .
 .TP
 .B snapm
 .CMD_SNAPSET_UMOUNT
 .br
 Unmount the specified snapshot set members. Snapshot set mounts are located
-by matching the set's member devices against the system mount table, so a
-snapshot set mounted with \fB--mount-root\fP is unmounted without needing to
-name that location again.
+from the records \fBsnapm\fP writes in \fI/run/snapm/mount-state\fP as it
+mounts a snapshot set, so a snapshot set mounted with \fB--mount-root\fP is
+unmounted without needing to name that location again. A snapshot mounted by
+hand has no such record and is never unmounted by \fBsnapm\fP, even when its
+device belongs to a snapshot set.
 .sp
 The \fB--mount-root\fP option selects which mount to unmount, and is only
 required when the snapshot set is mounted at more than one path. An
@@ -2373,6 +2387,17 @@ Snapshot set mounts are created in:
 .PP
 The snapshot set root volume is mounted to a directory named for the snapshot
 set.
+.PP
+A record of each mount \fBsnapm\fP makes is written to:
+.PP
+.I /run/snapm/mount-state
+.br
+.PP
+Each record is named for the path it describes, escaped as
+\fBsystemd-escape --path\fP escapes it, and holds the unescaped mount path,
+the name and UUID of the snapshot set mounted there, the device mounted at
+that path, and whether \fBsnapm\fP created the mount point and should remove
+it again.
 .
 .SH BUGS
 Please report bugs via the GitHub issue tracker:

snapm.spec

@@ -110,6 +110,7 @@ mkdir -p ${RPM_BUILD_ROOT}/%{_tmpfilesdir}
 
 %{__install} -d -m 0700 ${RPM_BUILD_ROOT}/%{_rundir}/%{name}
 %{__install} -d -m 0700 ${RPM_BUILD_ROOT}/%{_rundir}/%{name}/mounts
+%{__install} -d -m 0700 ${RPM_BUILD_ROOT}/%{_rundir}/%{name}/mount-state
 %{__install} -d -m 0700 ${RPM_BUILD_ROOT}/%{_rundir}/%{name}/lock
 
 %check
@@ -132,6 +133,7 @@ mkdir -p ${RPM_BUILD_ROOT}/%{_tmpfilesdir}
 %attr(644, -, -) %{_tmpfilesdir}/%{name}.conf
 %dir %{_rundir}/%{name}/
 %dir %{_rundir}/%{name}/mounts
+%dir %{_rundir}/%{name}/mount-state
 %dir %{_rundir}/%{name}/lock
 
 %files -n python3-snapm