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