sbin/geom/class/virstor/gvirstor.8

   1 .\" Copyright (c) 2006-2011 Ivan Voras <ivoras@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 January 24, 2011
  28 .Dt GVIRSTOR 8
  29 .Os
  30 .Sh NAME
  31 .Nm gvirstor
  32 .Nd "control utility for virtual data storage devices"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm label
  36 .Op Fl hv
  37 .Op Fl s Ar virsize
  38 .Op Fl m Ar chunksize
  39 .Ar name
  40 .Ar prov ...
  41 .Nm
  42 .Cm stop
  43 .Op Fl fv
  44 .Ar name ...
  45 .Nm
  46 .Cm add
  47 .Op Fl vh
  48 .Ar name prov ...
  49 .Nm
  50 .Cm remove
  51 .Op Fl v
  52 .Ar name prov ...
  53 .Nm
  54 .Cm clear
  55 .Op Fl v
  56 .Ar prov ...
  57 .Nm
  58 .Cm dump
  59 .Ar prov ...
  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 setting up a virtual storage device of arbitrary
  72 large size
  73 .Pq for example, several TB ,
  74 consisting of an arbitrary number of physical storage devices with the
  75 total size which is equal to or smaller than the virtual size.
  76 Data for the virtual devices will be allocated from physical devices on
  77 demand.
  78 The idea behind
  79 .Nm
  80 is similar to the concept of Virtual Memory in operating systems,
  81 effectively allowing users to overcommit on storage
  82 .Pq free file system space .
  83 The concept is also known as "thin provisioning" in virtualization
  84 environments, only here it is implemented on the level of physical storage
  85 devices.
  86 .Pp
  87 The first argument to
  88 .Nm
  89 indicates an action to be performed:
  90 .Bl -tag -width ".Cm remove"
  91 .It Cm label
  92 Set up a virtual device from the given components with the specified
  93 .Ar name .
  94 Metadata is stored in the last sector of every component.
  95 Argument
  96 .Fl s Ar virsize
  97 is the size of new virtual device, with default being set to 2 TiB
  98 .Pq 2097152 MiB .
  99 Argument
 100 .Fl m Ar chunksize
 101 is the chunk size, with default being set to 4 MiB
 102 .Pq 4096 KiB .
 103 The default arguments are thus
 104 .Qq Fl s Ar 2097152 Fl m Ar 4096 .
 105 .It Cm stop
 106 Turn off an existing virtual device with the given
 107 .Ar name .
 108 This command does not touch on-disk metadata.
 109 As with other GEOM classes, stopped geoms cannot be started manually.
 110 .It Cm add
 111 Adds new components to existing virtual device with the given
 112 .Ar name .
 113 The specified virstor device must exist and be active
 114 .Pq i.e. module loaded, device present in Pa /dev .
 115 This action can be safely performed while the virstor device is in use
 116 .Pq Qo hot Qc operation .
 117 .It Cm remove
 118 Removes components from existing virtual device with the given
 119 .Ar name .
 120 Only unallocated providers can be removed.
 121 .It Cm clear
 122 Clear metadata on the given providers.
 123 .It Cm dump
 124 Dump metadata stored on the given providers.
 125 .It Cm list
 126 See
 127 .Xr geom 8 .
 128 .It Cm status
 129 See
 130 .Xr geom 8 .
 131 .It Cm load
 132 See
 133 .Xr geom 8 .
 134 .It Cm unload
 135 See
 136 .Xr geom 8 .
 137 .El
 138 .Pp
 139 Additional options:
 140 .Bl -tag -width ".Fl f"
 141 .It Fl f
 142 Force the removal of the specified virtual device.
 143 .It Fl h
 144 Hardcode providers' names in metadata.
 145 .It Fl v
 146 Be more verbose.
 147 .El
 148 .Sh EXAMPLES
 149 The following example shows how to create a virtual device of default size
 150 .Pq 2 TiB ,
 151 of default chunk
 152 .Pq extent
 153 size
 154 .Pq 4 MiB ,
 155 with two physical devices for backing storage.
 156 .Bd -literal -offset indent
 157 .No gvirstor label -v Ar mydata Ar /dev/ad4 Ar /dev/ad6
 158 .No newfs Ar /dev/virstor/mydata
 159 .Ed
 160 .Pp
 161 From now on, the virtual device will be available via the
 162 .Pa /dev/virstor/mydata
 163 device entry.
 164 To add a new physical device / component to an active virstor device:
 165 .Bd -literal -offset indent
 166 .No gvirstor add Ar mydata Ar ad8
 167 .Ed
 168 .Pp
 169 This will add physical storage of
 170 .Ar ad8
 171 to
 172 .Pa /dev/virstor/mydata
 173 device.
 174 .Pp
 175 To see the device status information
 176 .Pq including how much physical storage is still available for the virtual device ,
 177 use:
 178 .Bd -literal -offset indent
 179 gvirstor list
 180 .Ed
 181 .Pp
 182 All standard
 183 .Xr geom 8
 184 subcommands
 185 .Pq e.g. Cm status , Cm help
 186 are also supported.
 187 .Sh SYSCTL VARIABLES
 188 .Nm
 189 has several
 190 .Xr sysctl 8
 191 tunable variables.
 192 .Bd -literal -offset indent
 193 .Va int kern.geom.virstor.debug
 194 .Ed
 195 .Pp
 196 This sysctl controls verbosity of the kernel module, in the range
 197 1 to 15.
 198 Messages that are marked with higher verbosity levels than this are
 199 suppressed.
 200 Default value is 5 and it is not recommended to set this tunable to less
 201 than 2, because level 1 messages are error events, and level 2 messages
 202 are system warnings.
 203 .Bd -literal -offset indent
 204 .Va int kern.geom.virstor.chunk_watermark
 205 .Ed
 206 .Pp
 207 Value in this sysctl sets warning watermark level for physical chunk
 208 usage on a single component.
 209 The warning is issued when a virstor component has less than this many
 210 free chunks
 211 .Pq default 100 .
 212 .Bd -literal -offset indent
 213 .Va int kern.geom.virstor.component_watermark
 214 .Ed
 215 .Pp
 216 Value in this sysctl sets warning watermark level for component usage.
 217 The warning is issued when there are less than this many unallocated
 218 components
 219 .Pq default is 1 .
 220 .Pp
 221 All these sysctls are also available as
 222 .Xr loader 8
 223 tunables.
 224 .Sh DIAGNOSTICS
 225 .Ex -std
 226 .Pp
 227 .Nm
 228 kernel module issues log messages with prefixes in standardized format,
 229 which is useful for log message filtering and dispatching.
 230 Each message line begins with
 231 .Bd -literal -offset indent
 232 .Li GEOM_VIRSTOR[%d]:
 233 .Ed
 234 .Pp
 235 The number
 236 .Pq %d
 237 is message verbosity / importance level, in the range 1 to 15.
 238 If a message filtering, dispatching or operator alert system is used, it
 239 is recommended that messages with levels 1 and 2 be taken seriously
 240 .Pq for example, to catch out-of-space conditions as set by watermark
 241 sysctls.
 242 .Sh SEE ALSO
 243 .Xr geom 4 ,
 244 .Xr fstab 5 ,
 245 .Xr geom 8 ,
 246 .Xr glabel 8 ,
 247 .Xr newfs 8
 248 .Sh HISTORY
 249 The
 250 .Nm
 251 utility first appeared in
 252 .Fx 7.0 .
 253 .Sh BUGS
 254 Commands
 255 .Cm add
 256 and
 257 .Cm remove
 258 contain unavoidable critical sections which may make the virstor
 259 device unusable if a power failure
 260 .Pq or other disruptive event
 261 happens during their execution.
 262 It is recommended to run them when the system is quiescent.
 263 .Sh ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS
 264 There are several assumptions that
 265 .Nm
 266 has in its operation: that the size of the virtual storage device will not
 267 change once it is set, and that the sizes of individual physical storage
 268 components will always remain constant during their existence.
 269 For alternative ways to implement virtual or resizable file systems see
 270 .Xr zfs 1M ,
 271 .Xr gconcat 8
 272 and
 273 .Xr growfs 8 .
 274 .Pp
 275 Note that
 276 .Nm
 277 has nontrivial interaction with file systems which initialize a large
 278 number of on-disk structures during newfs.
 279 If such file systems attempt to spread their structures across the drive
 280 media
 281 .Pq like UFS/UFS2 does ,
 282 their efforts will be effectively foiled by sequential allocation of
 283 chunks in
 284 .Nm
 285 and all their structures will be physically allocated at the start
 286 of the first virstor component.
 287 This could have a significant impact on file system performance
 288 .Pq which can in some rare cases be even positive .
 289 .Sh AUTHOR
 290 .An Ivan Voras Aq ivoras@FreeBSD.org
 291 .Pp
 292 Sponsored by Google Summer of Code 2006.