git: c80c104cbd52 - main - glabel.8: Describe cases related to permissions / existing mounts

The branch main has been updated by jrm:

URL: https://cgit.FreeBSD.org/src/commit/?id=c80c104cbd52db994c0f2757bd1c6d014744022c

commit c80c104cbd52db994c0f2757bd1c6d014744022c
Author:     Chris Moerz <freebsd@ny-central.org>
AuthorDate: 2024-05-21 18:10:11 +0000
Commit:     Joseph Mingrone <jrm@FreeBSD.org>
CommitDate: 2024-05-21 18:49:17 +0000

    glabel.8: Describe cases related to permissions / existing mounts
    
    Specially, note some requirements for label changes:
    
    - glabel requires write permission on device
    - filesystems first need to be unmounted for new labels to persist
      across reboots
    - if the affected device node holds the filesystem root, single-user
      mode with r/o mount will be required.
    
    Also, while here, apply some formatting tweaks.
    
    PR:             276724
    Reported by:    Alex Matei <matei35@yahoo.com>
    Reviewed by:    gbe, jrm, Alexander Ziaee <concussious@runbox.com>
    Differential Revision:  https://reviews.freebsd.org/D44394
---
 lib/geom/label/glabel.8 | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/lib/geom/label/glabel.8 b/lib/geom/label/glabel.8
index d6f253342905..da958b52befd 100644
--- a/lib/geom/label/glabel.8
+++ b/lib/geom/label/glabel.8
@@ -137,7 +137,7 @@ e.g.
 .Pa /dev/diskid/DISK-6QG3Z026  .
 .Pp
 Generic labels created and managed solely by
-.Xr glabel 8
+.Nm
 are created in the
 .Pa /dev/label/
 directory.
@@ -164,7 +164,8 @@ device will be one sector smaller than the device from which it was created.
 .Pp
 Note that for all label types, nested GEOM classes will cause additional
 device nodes to be created, with context-specific data appended to their
-names. E.g. for every node like
+names.
+E.g. for every node like
 .Pa /dev/label/bigdisk
 there will be additional entries for any partitions which the device
 contains, like
@@ -172,6 +173,17 @@ contains, like
 and
 .Pa /dev/label/bigdiskp1a .
 .Pp
+.Nm
+requires write access to a device to create, modify, and destroy
+"automatic" labels.
+It will fail to persist changes if they are applied while a file
+system on the device is currently mounted.
+To ensure that modifications are stored across a reboot, the file system
+needs to be unmounted first.
+If the device holds the system's root file system, entering into
+single user mode and mounting in read-only mode is required to persist
+the change.
+.Pp
 The first argument to
 .Nm
 indicates an action to be performed:
@@ -252,12 +264,13 @@ Most
 .Nm LABEL
 providers implement a
 .Xr sysctl 8
-flag and a tunable variable named in the above format. This flag
-controls if the label provider will be active, tasting devices
+flag and a tunable variable named in the above format.
+This flag controls if the label provider will be active, tasting devices
 and creating label nodes in the
 .Xr devfs 4
-tree. It is sometimes desirable to disable certain label types if
-they conflict with other classes in complex GEOM topologies.
+tree.
+It is sometimes desirable to disable certain label types if they
+conflict with other classes in complex GEOM topologies.
 .El
 .Sh EXIT STATUS
 Exit status is 0 on success, and 1 if the command fails.