sbin/geom/class/stripe/gstripe.8

   1 .\" Copyright (c) 2004-2005 Pawel Jakub Dawidek <pjd@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 May 21, 2004
  28 .Dt GSTRIPE 8
  29 .Os
  30 .Sh NAME
  31 .Nm gstripe
  32 .Nd "control utility for striped devices"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm create
  36 .Op Fl v
  37 .Op Fl s Ar stripesize
  38 .Ar name
  39 .Ar prov prov ...
  40 .Nm
  41 .Cm destroy
  42 .Op Fl fv
  43 .Ar name ...
  44 .Nm
  45 .Cm label
  46 .Op Fl hv
  47 .Op Fl s Ar stripesize
  48 .Ar name
  49 .Ar prov prov ...
  50 .Nm
  51 .Cm stop
  52 .Op Fl fv
  53 .Ar name ...
  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 stripe on two or more disks.
  73 The striped device can be configured using two different methods:
  74 .Dq manual
  75 or
  76 .Dq automatic .
  77 When using the
  78 .Dq manual
  79 method, no metadata are stored on the devices, so the striped
  80 device has to be configured by hand every time it is needed.
  81 The
  82 .Dq automatic
  83 method uses on-disk metadata to detect devices.
  84 Once devices are labeled, they will be automatically detected and
  85 configured.
  86 .Pp
  87 The first argument to
  88 .Nm
  89 indicates an action to be performed:
  90 .Bl -tag -width ".Cm destroy"
  91 .It Cm create
  92 Set up a striped device from the given devices with specified
  93 .Ar name .
  94 This is the
  95 .Dq manual
  96 method and the stripe will not exist after a reboot (see
  97 .Sx DESCRIPTION
  98 above).
  99 The kernel module
 100 .Pa geom_stripe.ko
 101 will be loaded if it is not loaded already.
 102 .It Cm label
 103 Set up a striped device from the given devices with the specified
 104 .Ar name .
 105 This is the
 106 .Dq automatic
 107 method, where metadata are stored in every device's last sector.
 108 The kernel module
 109 .Pa geom_stripe.ko
 110 will be loaded if it is not loaded already.
 111 .It Cm stop
 112 Turn off an existing striped device by its
 113 .Ar name .
 114 This command does not touch on-disk metadata!
 115 .It Cm destroy
 116 Same as
 117 .Cm stop .
 118 .It Cm clear
 119 Clear metadata on the given devices.
 120 .It Cm dump
 121 Dump metadata stored on the given devices.
 122 .It Cm list
 123 See
 124 .Xr geom 8 .
 125 .It Cm status
 126 See
 127 .Xr geom 8 .
 128 .It Cm load
 129 See
 130 .Xr geom 8 .
 131 .It Cm unload
 132 See
 133 .Xr geom 8 .
 134 .El
 135 .Pp
 136 Additional options:
 137 .Bl -tag -width ".Fl s Ar stripesize"
 138 .It Fl f
 139 Force the removal of the specified striped device.
 140 .It Fl h
 141 Hardcode providers' names in metadata.
 142 .It Fl s Ar stripesize
 143 Specifies size of stripe block in bytes.
 144 The
 145 .Ar stripesize
 146 must be a multiple of the largest sector size of all the providers.
 147 .It Fl v
 148 Be more verbose.
 149 .El
 150 .Sh SYSCTL VARIABLES
 151 The following
 152 .Xr sysctl 8
 153 variables can be used to control the behavior of the
 154 .Nm STRIPE
 155 GEOM class.
 156 The default value is shown next to each variable.
 157 .Bl -tag -width indent
 158 .It Va kern.geom.stripe.debug : No 0
 159 Debug level of the
 160 .Nm STRIPE
 161 GEOM class.
 162 This can be set to a number between 0 and 3 inclusive.
 163 If set to 0 minimal debug information is printed, and if set to 3 the
 164 maximum amount of debug information is printed.
 165 .It Va kern.geom.stripe.fast : No 0
 166 If set to a non-zero value enable
 167 .Dq "fast mode"
 168 instead of the normal
 169 .Dq "economic mode" .
 170 Compared to
 171 .Dq "economic mode" ,
 172 .Dq "fast mode"
 173 uses more memory, but it is much faster for smaller stripe sizes.
 174 If enough memory cannot be allocated,
 175 .Nm STRIPE
 176 will fall back to
 177 .Dq "economic mode" .
 178 .It Va kern.geom.stripe.maxmem : No 13107200
 179 Maximum amount of memory that can be consumed by
 180 .Dq "fast mode"
 181 (in bytes).
 182 This
 183 .Xr sysctl 8
 184 variable is read-only and can only be set as a tunable in
 185 .Xr loader.conf 5 .
 186 .It Va kern.geom.stripe.fast_failed
 187 A count of how many times
 188 .Dq "fast mode"
 189 has failed due to an insufficient amount of memory.
 190 If this value is large, you should consider increasing the
 191 .Va kern.geom.stripe.maxmem
 192 value.
 193 .El
 194 .Sh EXIT STATUS
 195 Exit status is 0 on success, and 1 if the command fails.
 196 .Sh EXAMPLES
 197 The following example shows how to set up a striped device from four disks with a
 198 128KB stripe size for automatic configuration,
 199 create a file system on it,
 200 and mount it:
 201 .Bd -literal -offset indent
 202 gstripe label -v -s 131072 data /dev/da0 /dev/da1 /dev/da2 /dev/da3
 203 newfs /dev/stripe/data
 204 mount /dev/stripe/data /mnt
 205 [...]
 206 umount /mnt
 207 gstripe stop data
 208 gstripe unload
 209 .Ed
 210 .Sh COMPATIBILITY
 211 The
 212 .Nm
 213 interleave is in number of bytes,
 214 unlike
 215 .Xr ccdconfig 8
 216 which use the number of sectors.
 217 A
 218 .Xr ccdconfig 8
 219 .Ar ileave
 220 of
 221 .Ql 128
 222 is 64 KB (128 512B sectors).
 223 The same stripe interleave would be specified as
 224 .Ql 65536
 225 for
 226 .Nm .
 227 .Sh SEE ALSO
 228 .Xr geom 4 ,
 229 .Xr loader.conf 5 ,
 230 .Xr ccdconfig 8 ,
 231 .Xr geom 8 ,
 232 .Xr gvinum 8 ,
 233 .Xr mount 8 ,
 234 .Xr newfs 8 ,
 235 .Xr sysctl 8 ,
 236 .Xr umount 8
 237 .Sh HISTORY
 238 The
 239 .Nm
 240 utility appeared in
 241 .Fx 5.3 .
 242 .Sh AUTHORS
 243 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org