sbin/geom/class/label/glabel.8

   1 .\" Copyright (c) 2004-2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   2 .\" Copyright (c) 2008-2009 Ivan Voras <ivoras@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd June 13, 2009
  29 .Dt GLABEL 8
  30 .Os
  31 .Sh NAME
  32 .Nm glabel
  33 .Nd "disk labelization control utility"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Cm create
  37 .Op Fl v
  38 .Ar name
  39 .Ar dev
  40 .Nm
  41 .Cm destroy
  42 .Op Fl fv
  43 .Ar name ...
  44 .Nm
  45 .Cm label
  46 .Op Fl v
  47 .Ar name
  48 .Ar dev
  49 .Nm
  50 .Cm stop
  51 .Op Fl fv
  52 .Ar name ...
  53 .Nm
  54 .Cm clear
  55 .Op Fl v
  56 .Ar dev ...
  57 .Nm
  58 .Cm dump
  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
  69 The
  70 .Nm
  71 utility is used for GEOM provider labelization.
  72 A label can be set up on a GEOM provider in two ways:
  73 .Dq manual
  74 or
  75 .Dq automatic .
  76 When using the
  77 .Dq manual
  78 method, no metadata are stored on the devices, so a label has to be configured
  79 by hand every time it is needed.
  80 The
  81 .Dq automatic
  82 method uses on-disk metadata to store the label and detect it automatically in
  83 the future.
  84 .Pp
  85 This class also provides volume label detection for file systems.
  86 Those labels cannot be set with
  87 .Nm ,
  88 but must be set with the appropriate file system utility, e.g.\& for UFS
  89 the file system label is set with
  90 .Xr tunefs 8 .
  91 Currently supported file systems are:
  92 .Pp
  93 .Bl -bullet -offset indent -compact
  94 .It
  95 UFS1 volume names (directory
  96 .Pa /dev/ufs/ ) .
  97 .It
  98 UFS2 volume names (directory
  99 .Pa /dev/ufs/ ) .
 100 .It
 101 UFS1 file system IDs (directory
 102 .Pa /dev/ufsid/ ) .
 103 .It
 104 UFS2 file system IDs (directory
 105 .Pa /dev/ufsid/ ) .
 106 .It
 107 MSDOSFS (FAT12, FAT16, FAT32) (directory
 108 .Pa /dev/msdosfs/ ) .
 109 .It
 110 CD ISO9660 (directory
 111 .Pa /dev/iso9660/ ) .
 112 .It
 113 EXT2FS (directory
 114 .Pa /dev/ext2fs/ ) .
 115 .It
 116 REISERFS (directory
 117 .Pa /dev/reiserfs/ ) .
 118 .It
 119 NTFS (directory
 120 .Pa /dev/ntfs/ ) .
 121 .El
 122 .Pp
 123 Support for partition metadata is implemented for:
 124 .Pp
 125 .Bl -bullet -offset indent -compact
 126 .It
 127 GPT labels (directory
 128 .Pa /dev/gpt/ ) .
 129 .It
 130 GPT UUIDs (directory
 131 .Pa /dev/gptid/ ) .
 132 .El
 133 .Pp
 134 Generic labels are created in the directory
 135 .Pa /dev/label/ .
 136 .Pp
 137 The first argument to
 138 .Nm
 139 indicates an action to be performed:
 140 .Bl -tag -width ".Cm destroy"
 141 .It Cm create
 142 Create temporary label
 143 .Ar name
 144 for the given provider.
 145 This is the
 146 .Dq manual
 147 method.
 148 The kernel module
 149 .Pa geom_label.ko
 150 will be loaded if it is not loaded already.
 151 .It Cm label
 152 Set up a label
 153 .Ar name
 154 for the given provider.
 155 This is the
 156 .Dq automatic
 157 method, where metadata is stored in a provider's last sector.
 158 The kernel module
 159 .Pa geom_label.ko
 160 will be loaded if it is not loaded already.
 161 .It Cm stop
 162 Turn off the given label by its
 163 .Ar name .
 164 This command does not touch on-disk metadata!
 165 .It Cm destroy
 166 Same as
 167 .Cm stop .
 168 .It Cm clear
 169 Clear metadata on the given devices.
 170 .It Cm dump
 171 Dump metadata stored on the given devices.
 172 .It Cm list
 173 See
 174 .Xr geom 8 .
 175 .It Cm status
 176 See
 177 .Xr geom 8 .
 178 .It Cm load
 179 See
 180 .Xr geom 8 .
 181 .It Cm unload
 182 See
 183 .Xr geom 8 .
 184 .El
 185 .Pp
 186 Additional options:
 187 .Bl -tag -width indent
 188 .It Fl f
 189 Force the removal of the specified labels.
 190 .It Fl v
 191 Be more verbose.
 192 .El
 193 .Sh SYSCTL VARIABLES
 194 The following
 195 .Xr sysctl 8
 196 variables can be used to control the behavior of the
 197 .Nm LABEL
 198 GEOM class.
 199 The default value is shown next to each variable.
 200 .Bl -tag -width indent
 201 .It Va kern.geom.label.debug : No 0
 202 Debug level of the
 203 .Nm LABEL
 204 GEOM class.
 205 This can be set to a number between 0 and 2 inclusive.
 206 If set to 0 minimal debug information is printed, and if set to 2 the
 207 maximum amount of debug information is printed.
 208 .El
 209 .Sh EXIT STATUS
 210 Exit status is 0 on success, and 1 if the command fails.
 211 .Sh EXAMPLES
 212 The following example shows how to set up a label for disk
 213 .Dq Li da2 ,
 214 create a file system on it, and mount it:
 215 .Bd -literal -offset indent
 216 glabel label -v usr /dev/da2
 217 newfs /dev/label/usr
 218 mount /dev/label/usr /usr
 219 [...]
 220 umount /usr
 221 glabel stop usr
 222 glabel unload
 223 .Ed
 224 .Pp
 225 The next example shows how to set up a label for a UFS file system:
 226 .Bd -literal -offset indent
 227 tunefs -L data /dev/da4s1a
 228 mount /dev/ufs/data /mnt/data
 229 .Ed
 230 .Sh SEE ALSO
 231 .Xr geom 4 ,
 232 .Xr loader.conf 5 ,
 233 .Xr geom 8 ,
 234 .Xr mount 8 ,
 235 .Xr newfs 8 ,
 236 .Xr sysctl 8 ,
 237 .Xr tunefs 8 ,
 238 .Xr umount 8
 239 .Sh HISTORY
 240 The
 241 .Nm
 242 utility appeared in
 243 .Fx 5.3 .
 244 .Sh AUTHORS
 245 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org