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