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