sbin/geom/class/virstor/gvirstor.8

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