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 labels are created in the directory
 134 .Pa /dev/label/ .
 135 .Pp
 136 The first argument to
 137 .Nm
 138 indicates an action to be performed:
 139 .Bl -tag -width ".Cm destroy"
 140 .It Cm create
 141 Create temporary label
 142 .Ar name
 143 for the given provider.
 144 This is the
 145 .Dq manual
 146 method.
 147 The kernel module
 148 .Pa geom_label.ko
 149 will be loaded if it is not loaded already.
 150 .It Cm label
 151 Set up a label
 152 .Ar name
 153 for the given provider.
 154 This is the
 155 .Dq automatic
 156 method, where metadata is stored in a provider's last sector.
 157 The kernel module
 158 .Pa geom_label.ko
 159 will be loaded if it is not loaded already.
 160 .It Cm stop
 161 Turn off the given label by its
 162 .Ar name .
 163 This command does not touch on-disk metadata!
 164 .It Cm destroy
 165 Same as
 166 .Cm stop .
 167 .It Cm clear
 168 Clear metadata on the given devices.
 169 .It Cm dump
 170 Dump metadata stored on the given devices.
 171 .It Cm list
 172 See
 173 .Xr geom 8 .
 174 .It Cm status
 175 See
 176 .Xr geom 8 .
 177 .It Cm load
 178 See
 179 .Xr geom 8 .
 180 .It Cm unload
 181 See
 182 .Xr geom 8 .
 183 .El
 184 .Pp
 185 Additional options:
 186 .Bl -tag -width indent
 187 .It Fl f
 188 Force the removal of the specified labels.
 189 .It Fl v
 190 Be more verbose.
 191 .El
 192 .Sh SYSCTL VARIABLES
 193 The following
 194 .Xr sysctl 8
 195 variables can be used to control the behavior of the
 196 .Nm LABEL
 197 GEOM class.
 198 The default value is shown next to each variable.
 199 .Bl -tag -width indent
 200 .It Va kern.geom.label.debug : No 0
 201 Debug level of the
 202 .Nm LABEL
 203 GEOM class.
 204 This can be set to a number between 0 and 2 inclusive.
 205 If set to 0 minimal debug information is printed, and if set to 2 the
 206 maximum amount of debug information is printed.
 207 .El
 208 .Sh EXIT STATUS
 209 Exit status is 0 on success, and 1 if the command fails.
 210 .Sh EXAMPLES
 211 The following example shows how to set up a label for disk
 212 .Dq Li da2 ,
 213 create a file system on it, and mount it:
 214 .Bd -literal -offset indent
 215 glabel label -v usr /dev/da2
 216 newfs /dev/label/usr
 217 mount /dev/label/usr /usr
 218 [...]
 219 umount /usr
 220 glabel stop usr
 221 glabel unload
 222 .Ed
 223 .Pp
 224 The next example shows how to set up a label for a UFS file system:
 225 .Bd -literal -offset indent
 226 tunefs -L data /dev/da4s1a
 227 mount /dev/ufs/data /mnt/data
 228 .Ed
 229 .Sh SEE ALSO
 230 .Xr geom 4 ,
 231 .Xr loader.conf 5 ,
 232 .Xr geom 8 ,
 233 .Xr mount 8 ,
 234 .Xr newfs 8 ,
 235 .Xr sysctl 8 ,
 236 .Xr tunefs 8 ,
 237 .Xr umount 8
 238 .Sh HISTORY
 239 The
 240 .Nm
 241 utility appeared in
 242 .Fx 5.3 .
 243 .Sh AUTHORS
 244 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org