sbin/geom/class/virstor/gvirstor.8

   1 .\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   2 .\" Copyright (c) 2005 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 July 8, 2006
  29 .Dt GVIRSTOR 8
  30 .Os
  31 .Sh NAME
  32 .Nm gvirstor
  33 .Nd "provides virtual data storage geom"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Cm label
  37 .Op Fl hv
  38 .Op Fl s Ar virsize
  39 .Op Fl m Ar chunksize
  40 .Ar name
  41 .Ar prov ...
  42 .Nm
  43 .Cm stop
  44 .Op Fl fv
  45 .Ar name ...
  46 .Nm
  47 .Cm add
  48 .Op Fl vh
  49 .Ar name prov ...
  50 .Nm
  51 .Cm remove
  52 .Op Fl v
  53 .Ar name prov ...
  54 .Nm
  55 .Cm clear
  56 .Op Fl v
  57 .Ar prov ...
  58 .Nm
  59 .Cm dump
  60 .Ar prov ...
  61 .Nm
  62 .Cm list
  63 .Nm
  64 .Cm status
  65 .Nm
  66 .Cm load
  67 .Nm
  68 .Cm unload
  69 .Sh DESCRIPTION
  70 The
  71 .Nm
  72 utility is used for setting up a storage device of arbitrary large size (for example,
  73 several TB), consisting of an arbitrary number of physical storage devices with
  74 total size <= the virtual size. Data for the virtual devices will be allocated from
  75 physical devices on demand. In short, this is the virtual storage functionality.
  76 The first argument to
  77 .Nm
  78 indicates an action to be performed:
  79 .Bl -tag -width ".Cm destroy"
  80 .It Cm label
  81 Set up a virtual device from the given components with the specified
  82 .Ar name .
  83 Metadata are stored in the last sector of every component.
  84 Argument
  85 .Ar virsize
  86 is the size of new virtual device, with default being 2 TiB (2097152 MiB).
  87 Argument
  88 .Ar chunksize
  89 is the chunk size, with default being 4 MiB (4096 KiB).
  90 The default is thus "-s 2097152 -m 4096".
  91 .It Cm stop
  92 Turn off an existing virtual device by its
  93 .Ar name .
  94 This command does not touch on-disk metadata.
  95 As with other GEOM classes, stopped geoms cannot be started manually.
  96 .It Cm add
  97 Adds new components to existing virtual device by its
  98 .Ar name .
  99 The specified virstor device must exist and be active (i.e.
 100 module loaded, device present in /dev).
 101 .It Cm remove
 102 Removes components from existing virtual device by its
 103 .Ar name .
 104 Only unallocated providers can be removed.
 105 .It Cm clear
 106 Clear metadata on the given providers.
 107 .It Cm dump
 108 Dump metadata stored on the given providers.
 109 .It Cm list
 110 See
 111 .Xr geom 8 .
 112 .It Cm status
 113 See
 114 .Xr geom 8 .
 115 .It Cm load
 116 See
 117 .Xr geom 8 .
 118 .It Cm unload
 119 See
 120 .Xr geom 8 .
 121 .El
 122 .Pp
 123 Additional options:
 124 .Bl -tag -width ".Fl f"
 125 .It Fl f
 126 Force the removal of the specified virtual device.
 127 .It Fl h
 128 Hardcode providers' names in metadata.
 129 .It Fl v
 130 Be more verbose.
 131 .El
 132 .Sh EXIT STATUS
 133 Exit status is 0 on success, and 1 if the command fails.
 134 .Sh EXAMPLES
 135 The following example shows how to create a virtual device of default size
 136 (2 TiB), of default chunk (extent) size (4 MiB), with two physical devices for
 137 backing storage.
 138 .Bd -literal -offset indent
 139 gvirstor label -v mydata /dev/ad4 /dev/ad6
 140 newfs /dev/virstor/mydata
 141 .Ed
 142 .Pp
 143 From now on, the virtual device will be available via the
 144 .Pa /dev/virstor/mydata
 145 device entry.
 146 To add a new physical device / provider to an active virstor device:
 147 .Bd -literal -offset indent
 148 gvirstor add mydata ad8
 149 .Ed
 150 .Pp
 151 This will add physical storage (from ad8) to
 152 .Pa /dev/virstor/mydata
 153 device.
 154 To see device status information (including how much physical storage
 155 is still available for the virtual device), use:
 156 .Bd -literal -offset indent
 157 gvirstor list
 158 .Ed
 159 .Pp
 160 All standard
 161 .Xr geom 8
 162 subcommands (e.g. "status", "help") are also supported.
 163 .Sh SYSCTLs
 164 .Nm
 165 has several
 166 .Xr sysctl 8
 167 tunable variables.
 168 .Bd -literal -offset indent
 169 .Pa int kern.geom.virstor.debug
 170 .Ed
 171 .Pp
 172 This sysctl controls verbosity of the kernel module, in the range
 173 1 to 15. Messages that are marked with higher verbosity levels than
 174 this are supressed. Default value is 5 and it's not
 175 recommented to set this tunable to less than 2, because level 1 messages
 176 are error events, and level 2 messages are system warnings.
 177 .Bd -literal -offset indent
 178 .Pa int kern.geom.virstor.chunk_watermark
 179 .Ed
 180 .Pp
 181 Value in this sysctl sets warning watermark level for physical chunk usage
 182 on a single component. The warning is issued when a virstor component
 183 has less than this many free chunks (default 100).
 184 .Bd -literal -offset indent
 185 .Pa int kern.geom.virstor.component_watermark
 186 .Ed
 187 .Pp
 188 Value in this sysctl sets warning watermark level for component usage.
 189 The warning is issed when there are less than this many unallocated
 190 components (default is 1).
 191 .Pp
 192 All these sysctls are also available as
 193 .Xr loader 8
 194 tunables.
 195 .Sh LOG MESSAGES
 196 .Nm
 197 kernel module issues log messages with prefixes in standardised format,
 198 which is useful for log message filtering and dispatching. Each message
 199 line begins with
 200 .Bd -literal -offset indent
 201 .Pa GEOM_VIRSTOR[%d]:
 202 .Ed
 203 .Pp
 204 The number (%d) is message verbosity / importance level, in the range
 205 1 to 15. If a message filtering, dispatching or operator alert system is
 206 used, it is recommended that messages with levels 1 and 2 be taken
 207 seriously (for example, to catch out-of-space conditions as set by
 208 watermark sysctls).
 209 .Sh SEE ALSO
 210 .Xr geom 4 ,
 211 .Xr geom 8 ,
 212 .Xr newfs 8 ,
 213 .Xr fstab 5 ,
 214 .Xr glabel 8
 215 .Sh HISTORY
 216 The
 217 .Nm
 218 utility appeared in
 219 .Fx 7.0 .
 220 .Sh BUGS
 221 Commands "add" and "remove" contain unavoidable critical sections
 222 which may make the virstor device unusable if a power failure (or
 223 other disruptive event) happens during their execution.
 224 It's recommended to run them when the system is quiescent.
 225 .Sh AUTHOR
 226 .An Ivan Voras Aq ivoras@FreeBSD.org
 227 Sponsored by Google Summer of Code 2006