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
This commit is contained in:
Chris Moerz
2024-05-21 15:10:11 -03:00
committed by Joseph Mingrone
parent a332ba32d4
commit c80c104cbd
+19 -6
View File
@@ -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.