lib/geom/label/glabel.8

   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 .\" $FreeBSD$
  26 .\"
  27 .Dd March 12, 2017
  28 .Dt GLABEL 8
  29 .Os
  30 .Sh NAME
  31 .Nm glabel
  32 .Nd "disk labelization control utility"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm create
  36 .Op Fl v
  37 .Ar name
  38 .Ar dev
  39 .Nm
  40 .Cm destroy
  41 .Op Fl fv
  42 .Ar name ...
  43 .Nm
  44 .Cm label
  45 .Op Fl v
  46 .Ar name
  47 .Ar dev
  48 .Nm
  49 .Cm stop
  50 .Op Fl fv
  51 .Ar name ...
  52 .Nm
  53 .Cm clear
  54 .Op Fl v
  55 .Ar dev ...
  56 .Nm
  57 .Cm dump
  58 .Ar dev ...
  59 .Nm
  60 .Cm refresh
  61 .Ar dev ...
  62 .Nm
  63 .Cm list
  64 .Nm
  65 .Cm status
  66 .Nm
  67 .Cm load
  68 .Nm
  69 .Cm unload
  70 .Sh DESCRIPTION
  71 The
  72 .Nm
  73 utility is used for GEOM provider labelization.
  74 A label can be set up on a GEOM provider in two ways:
  75 .Dq manual
  76 or
  77 .Dq automatic .
  78 When using the
  79 .Dq manual
  80 method, no metadata are stored on the devices, so a label has to be configured
  81 by hand every time it is needed.
  82 The
  83 .Dq automatic
  84 method uses on-disk metadata to store the label and detect it automatically in
  85 the future.
  86 .Pp
  87 This GEOM class also provides volume label detection for file systems.
  88 Those labels cannot be set with
  89 .Nm ,
  90 but must be set with the appropriate file system utility, e.g.\& for UFS
  91 the file system label is set with
  92 .Xr tunefs 8 .
  93 Currently supported file systems are:
  94 .Pp
  95 .Bl -bullet -offset indent -compact
  96 .It
  97 UFS1 volume names (directory
  98 .Pa /dev/ufs/ ) .
  99 .It
 100 UFS2 volume names (directory
 101 .Pa /dev/ufs/ ) .
 102 .It
 103 UFS1 file system IDs (directory
 104 .Pa /dev/ufsid/ ) .
 105 .It
 106 UFS2 file system IDs (directory
 107 .Pa /dev/ufsid/ ) .
 108 .It
 109 MSDOSFS (FAT12, FAT16, FAT32) (directory
 110 .Pa /dev/msdosfs/ ) .
 111 .It
 112 CD ISO9660 (directory
 113 .Pa /dev/iso9660/ ) .
 114 .It
 115 EXT2FS (directory
 116 .Pa /dev/ext2fs/ ) .
 117 .It
 118 REISERFS (directory
 119 .Pa /dev/reiserfs/ ) .
 120 .It
 121 NTFS (directory
 122 .Pa /dev/ntfs/ ) .
 123 .El
 124 .Pp
 125 Support for partition metadata is implemented for:
 126 .Pp
 127 .Bl -bullet -offset indent -compact
 128 .It
 129 GPT labels (directory
 130 .Pa /dev/gpt/ ) .
 131 .It
 132 GPT UUIDs (directory
 133 .Pa /dev/gptid/ ) .
 134 .El
 135 .Pp
 136 Generic disk ID strings are exported as labels in the format
 137 .Pa /dev/diskid/GEOM_CLASS-ident
 138 e.g.
 139 .Pa /dev/diskid/DISK-6QG3Z026  .
 140 .Pp
 141 Generic labels created and managed solely by
 142 .Xr glabel 8
 143 are created in the
 144 .Pa /dev/label/
 145 directory.
 146 .Pp
 147 Note that for all label types, nested GEOM classes will cause additional
 148 device nodes to be created, with context-specific data appended to their
 149 names. E.g. for every node like
 150 .Pa /dev/label/bigdisk
 151 there will be additional entries for any partitions which the device
 152 contains, like
 153 .Pa /dev/label/bigdiskp1
 154 and
 155 .Pa /dev/label/bigdiskp1a .
 156 .Pp
 157 The first argument to
 158 .Nm
 159 indicates an action to be performed:
 160 .Bl -tag -width ".Cm destroy"
 161 .It Cm create
 162 Create temporary label
 163 .Ar name
 164 for the given provider.
 165 This is the
 166 .Dq manual
 167 method.
 168 The kernel module
 169 .Pa geom_label.ko
 170 will be loaded if it is not loaded already.
 171 .It Cm label
 172 Set up a label
 173 .Ar name
 174 for the given provider.
 175 This is the
 176 .Dq automatic
 177 method, where metadata is stored in a provider's last sector.
 178 The kernel module
 179 .Pa geom_label.ko
 180 will be loaded if it is not loaded already.
 181 .It Cm stop
 182 Turn off the given label by its
 183 .Ar name .
 184 This command does not touch on-disk metadata!
 185 .It Cm destroy
 186 Same as
 187 .Cm stop .
 188 .It Cm clear
 189 Clear metadata on the given devices.
 190 .It Cm dump
 191 Dump metadata stored on the given devices.
 192 .It Cm refresh
 193 Refresh / rediscover metadata from the given devices.
 194 .It Cm list
 195 See
 196 .Xr geom 8 .
 197 .It Cm status
 198 See
 199 .Xr geom 8 .
 200 .It Cm load
 201 See
 202 .Xr geom 8 .
 203 .It Cm unload
 204 See
 205 .Xr geom 8 .
 206 .El
 207 .Pp
 208 Additional options:
 209 .Bl -tag -width indent
 210 .It Fl f
 211 Force the removal of the specified labels.
 212 .It Fl v
 213 Be more verbose.
 214 .El
 215 .Sh SYSCTL VARIABLES
 216 The following
 217 .Xr sysctl 8
 218 variables can be used to control the behavior of the
 219 .Nm LABEL
 220 GEOM class.
 221 The default value is shown next to each variable.
 222 .Bl -tag -width indent
 223 .It Va kern.geom.label.debug : No 0
 224 Debug level of the
 225 .Nm LABEL
 226 GEOM class.
 227 This can be set to a number between 0 and 2 inclusive.
 228 If set to 0 minimal debug information is printed, and if set to 2 the
 229 maximum amount of debug information is printed.
 230 .El
 231 .Bl -tag -width indent
 232 .It Va kern.geom.label.*.enable : No 1
 233 Most
 234 .Nm LABEL
 235 providers implement a
 236 .Xr sysctl 8
 237 flag and a tunable variable named in the above format. This flag
 238 controls if the label provider will be active, tasting devices
 239 and creating label nodes in the
 240 .Xr devfs 5
 241 tree. It is sometimes desirable to disable certain label types if
 242 they conflict with other classes in complex GEOM topologies.
 243 .El
 244 .Sh EXIT STATUS
 245 Exit status is 0 on success, and 1 if the command fails.
 246 .Sh EXAMPLES
 247 The following example shows how to set up a label for disk
 248 .Dq Li da2 ,
 249 create a file system on it, and mount it:
 250 .Bd -literal -offset indent
 251 glabel label -v usr /dev/da2
 252 newfs /dev/label/usr
 253 mount /dev/label/usr /usr
 254 [...]
 255 umount /usr
 256 glabel stop usr
 257 glabel unload
 258 .Ed
 259 .Pp
 260 The next example shows how to set up a label for a UFS file system:
 261 .Bd -literal -offset indent
 262 tunefs -L data /dev/da4s1a
 263 mount /dev/ufs/data /mnt/data
 264 .Ed
 265 .Sh SEE ALSO
 266 .Xr geom 4 ,
 267 .Xr loader.conf 5 ,
 268 .Xr geom 8 ,
 269 .Xr mount 8 ,
 270 .Xr newfs 8 ,
 271 .Xr sysctl 8 ,
 272 .Xr tunefs 8 ,
 273 .Xr umount 8
 274 .Sh HISTORY
 275 The
 276 .Nm
 277 utility appeared in
 278 .Fx 5.3 .
 279 .Sh AUTHORS
 280 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org