1.\" Copyright (c) 2004-2005 Pawel Jakub Dawidek <pjd@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd April 19, 2024 26.Dt GLABEL 8 27.Os 28.Sh NAME 29.Nm glabel 30.Nd "disk labelization control utility" 31.Sh SYNOPSIS 32.Nm 33.Cm create 34.Op Fl v 35.Ar name 36.Ar dev 37.Nm 38.Cm destroy 39.Op Fl fv 40.Ar name ... 41.Nm 42.Cm label 43.Op Fl v 44.Ar name 45.Ar dev 46.Nm 47.Cm stop 48.Op Fl fv 49.Ar name ... 50.Nm 51.Cm clear 52.Op Fl v 53.Ar dev ... 54.Nm 55.Cm dump 56.Ar dev ... 57.Nm 58.Cm refresh 59.Ar dev ... 60.Nm 61.Cm list 62.Nm 63.Cm status 64.Nm 65.Cm load 66.Nm 67.Cm unload 68.Sh DESCRIPTION 69The 70.Nm 71utility is used for GEOM provider labelization. 72A label can be set up on a GEOM provider in two ways: 73.Dq manual 74or 75.Dq automatic . 76When using the 77.Dq manual 78method, no metadata are stored on the devices, so a label has to be configured 79by hand every time it is needed. 80The 81.Dq automatic 82method uses on-disk metadata to store the label and detect it automatically in 83the future. 84.Pp 85This GEOM class also provides volume label detection for file systems. 86Those labels cannot be set with 87.Nm , 88but must be set with the appropriate file system utility, e.g.\& for UFS 89the file system label is set with 90.Xr tunefs 8 . 91Currently supported file systems are: 92.Pp 93.Bl -bullet -offset indent -compact 94.It 95UFS1 volume names (directory 96.Pa /dev/ufs/ ) . 97.It 98UFS2 volume names (directory 99.Pa /dev/ufs/ ) . 100.It 101UFS1 file system IDs (directory 102.Pa /dev/ufsid/ ) . 103.It 104UFS2 file system IDs (directory 105.Pa /dev/ufsid/ ) . 106.It 107MSDOSFS (FAT12, FAT16, FAT32) (directory 108.Pa /dev/msdosfs/ ) . 109.It 110CD ISO9660 (directory 111.Pa /dev/iso9660/ ) . 112.It 113EXT2FS (directory 114.Pa /dev/ext2fs/ ) . 115.It 116NTFS (directory 117.Pa /dev/ntfs/ ) . 118.El 119.Pp 120Support for partition metadata is implemented for: 121.Pp 122.Bl -bullet -offset indent -compact 123.It 124GPT labels (directory 125.Pa /dev/gpt/ ) . 126.It 127GPT UUIDs (directory 128.Pa /dev/gptid/ ) . 129.El 130.Pp 131Generic disk ID strings are exported as labels in the format 132.Pa /dev/diskid/GEOM_CLASS-ident 133e.g. 134.Pa /dev/diskid/DISK-6QG3Z026 . 135.Pp 136Generic labels created and managed solely by 137.Xr glabel 8 138are created in the 139.Pa /dev/label/ 140directory. 141Note that generic, automatic labels occupy some space on the device 142and thus should not be added to a device already containing a file system. 143In particular, 144.Nm 145reserves the last sector of the device to store the label information. 146If the device already contains a file system, 147.Nm 148will overwrite the last sector, possibly damaging the file system, and the 149file system may later overwrite the label sector. 150Instead, create a label before initializing the file system, and initialize 151that file system on the device created by 152.Nm 153under the 154.Pa /dev/label/ 155directory. 156Then the file system will correctly account for the space occupied by the 157generic label, 158since the 159.Nm 160device will be one sector smaller than the device from which it was created. 161.Pp 162Note that for all label types, nested GEOM classes will cause additional 163device nodes to be created, with context-specific data appended to their 164names. E.g. for every node like 165.Pa /dev/label/bigdisk 166there will be additional entries for any partitions which the device 167contains, like 168.Pa /dev/label/bigdiskp1 169and 170.Pa /dev/label/bigdiskp1a . 171.Pp 172The first argument to 173.Nm 174indicates an action to be performed: 175.Bl -tag -width ".Cm destroy" 176.It Cm create 177Create temporary label 178.Ar name 179for the given provider. 180This is the 181.Dq manual 182method. 183The kernel module 184.Pa geom_label.ko 185will be loaded if it is not loaded already. 186.It Cm label 187Set up a label 188.Ar name 189for the given provider. 190This is the 191.Dq automatic 192method, where metadata is stored in a provider's last sector. 193The kernel module 194.Pa geom_label.ko 195will be loaded if it is not loaded already. 196.It Cm stop 197Turn off the given label by its 198.Ar name . 199This command does not touch on-disk metadata! 200.It Cm destroy 201Same as 202.Cm stop . 203.It Cm clear 204Clear metadata on the given devices. 205.It Cm dump 206Dump metadata stored on the given devices. 207.It Cm refresh 208Refresh / rediscover metadata from the given devices. 209.It Cm list 210See 211.Xr geom 8 . 212.It Cm status 213See 214.Xr geom 8 . 215.It Cm load 216See 217.Xr geom 8 . 218.It Cm unload 219See 220.Xr geom 8 . 221.El 222.Pp 223Additional options: 224.Bl -tag -width indent 225.It Fl f 226Force the removal of the specified labels. 227.It Fl v 228Be more verbose. 229.El 230.Sh SYSCTL VARIABLES 231The following 232.Xr sysctl 8 233variables can be used to control the behavior of the 234.Nm LABEL 235GEOM class. 236The default value is shown next to each variable. 237.Bl -tag -width indent 238.It Va kern.geom.label.debug : No 0 239Debug level of the 240.Nm LABEL 241GEOM class. 242This can be set to a number between 0 and 2 inclusive. 243If set to 0 minimal debug information is printed, and if set to 2 the 244maximum amount of debug information is printed. 245.El 246.Bl -tag -width indent 247.It Va kern.geom.label.*.enable : No 1 248Most 249.Nm LABEL 250providers implement a 251.Xr sysctl 8 252flag and a tunable variable named in the above format. This flag 253controls if the label provider will be active, tasting devices 254and creating label nodes in the 255.Xr devfs 5 256tree. It is sometimes desirable to disable certain label types if 257they conflict with other classes in complex GEOM topologies. 258.El 259.Sh EXIT STATUS 260Exit status is 0 on success, and 1 if the command fails. 261.Sh EXAMPLES 262The following example shows how to set up a label for disk 263.Dq Li da2 , 264create a file system on it, and mount it: 265.Bd -literal -offset indent 266glabel label -v usr /dev/da2 267newfs /dev/label/usr 268mount /dev/label/usr /usr 269[...] 270umount /usr 271glabel stop usr 272glabel unload 273.Ed 274.Pp 275The next example shows how to set up a label for a UFS file system: 276.Bd -literal -offset indent 277tunefs -L data /dev/da4s1a 278mount /dev/ufs/data /mnt/data 279.Ed 280.Sh SEE ALSO 281.Xr geom 4 , 282.Xr loader.conf 5 , 283.Xr geom 8 , 284.Xr mount 8 , 285.Xr newfs 8 , 286.Xr sysctl 8 , 287.Xr tunefs 8 , 288.Xr umount 8 289.Sh HISTORY 290The 291.Nm 292utility appeared in 293.Fx 5.3 . 294.Sh AUTHORS 295.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org 296