sbin/gvinum/gvinum.8

   1 .\"  Copyright (c) 2005 Chris Jones
   2 .\"  All rights reserved.
   3 .\"
   4 .\" This software was developed for the FreeBSD Project by Chris Jones
   5 .\" thanks to the support of Google's Summer of Code program and
   6 .\" mentoring by Lukas Ertl.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd October 1, 2013
  32 .Dt GVINUM 8
  33 .Os
  34 .Sh NAME
  35 .Nm gvinum
  36 .Nd Logical Volume Manager control program
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Ar command
  40 .Op Fl options
  41 .Sh COMMANDS
  42 .Bl -tag -width indent
  43 .It Ic attach Ar plex volume Op Cm rename
  44 .It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename
  45 Attach a plex to a volume, or a subdisk to a plex.
  46 If offset is specified, the subdisk will be attached to the given offset within
  47 the plex.
  48 If rename is specified, the subdisk or plex will change name according to the
  49 object it attaches to.
  50 .It Ic checkparity Oo Fl f Oc Ar plex
  51 Check the parity blocks of a RAID-5 plex.
  52 The parity check will start at the
  53 beginning of the plex if the
  54 .Fl f
  55 flag is specified, or otherwise at the location of the parity check pointer,
  56 the first location at which plex's parity is incorrect.
  57 All subdisks in the
  58 plex must be up for a parity check.
  59 .It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
  60 Create a concatenated volume from the specified drives.
  61 If no name is specified, a unique name will be set by
  62 .Ic gvinum .
  63 .It Ic create Oo Fl f Oc Op Ar description-file
  64 Create a volume as described in
  65 .Ar description-file .
  66 If no
  67 .Ar description-file
  68 provided, opens an editor and provides the current
  69 .Nm
  70 configuration for editing.
  71 The
  72 .Fl f
  73 flag will make gvinum ignore any errors regarding creating objects that already
  74 exists.
  75 However, in contrast to vinum, objects that are not properly named in the
  76 .Ar description-file
  77 will not be created when the
  78 .Fl f
  79 flag is given.
  80 .It Ic detach Oo Fl f Oc Op Ar plex | subdisk
  81 Detach a plex or subdisk from the volume or plex to which it is
  82 attached.
  83 .It Ic grow Ar plex device
  84 Grow a plex by creating a gvinum drive and subdisk on device and attach it to
  85 the plex.
  86 If required by the plex organization, it will be put into the growable state.
  87 .It Ic help
  88 Provides a synopsis of
  89 .Nm
  90 commands and arguments.
  91 .It Ic l | list Oo Fl rvV Oc Op Ar volume | plex | subdisk
  92 .It Ic ld Oo Fl rvV Oc Op Ar drive ...
  93 .It Ic ls Oo Fl rvV Oc Op Ar subdisk ...
  94 .It Ic lp Oo Fl rvV Oc Op Ar plex ...
  95 .It Ic lv Oo Fl rvV Oc Op Ar volume ...
  96 List information about the relevant object(s).
  97 The
  98 .Fl r
  99 flag provides recursive display, showing each object's subordinate objects in
 100 proper relation.
 101 The
 102 .Fl v
 103 and
 104 .Fl V
 105 flags provide progressively more detailed output.
 106 .It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives
 107 Create a mirrored volume from the specified drives.
 108 It requires at least a multiple of 2 drives.
 109 If no name is specified, a unique name will be set by gvinum.
 110 If the
 111 .Fl s
 112 flag is specified, a striped mirror will be created, and thus requires a
 113 multiple of 4 drives.
 114 .It Ic move | mv Fl f Ar drive subdisk Op Ar ...
 115 Move the subdisk(s) to the specified drive.
 116 The
 117 .Fl f
 118 flag is required, as all data on the indicated subdisk(s) will be destroyed as
 119 part of the move.
 120 This can currently only be done when the subdisk is
 121 not being accessed.
 122 .Pp
 123 If a single subdisk is moved, and it forms a part of a RAID-5 plex, the moved
 124 subdisks will need to be set to the
 125 .Dq stale
 126 state, and the plex will require a
 127 .Ic start
 128 command.
 129 If multiple subdisk(s) is moved, and form part of a RAID-5 plex, the
 130 moved disk(s) will need to be set to the
 131 .Dq up
 132 state and the plex will require a
 133 .Ic rebuildparity
 134 command.
 135 If the subdisk(s) form part of a plex that is mirrored with other
 136 plexes, the plex will require restarting and will sync once restarted.
 137 Moving
 138 more than one subdisk in a RAID-5 plex or subdisks from both sides of a
 139 mirrored plex volume will destroy data.
 140 Note that parity rebuilds and syncing
 141 must be started manually after a move.
 142 .It Ic printconfig
 143 Write a copy of the current configuration to standard output.
 144 .It Ic quit
 145 Exit
 146 .Nm
 147 when running in interactive mode.
 148 Normally this would be done by entering the
 149 EOF character.
 150 .It Ic raid5 Oo Fl fv Oc Oo Fl s Ar stripesize Oc Oo Fl n Ar name Oc Ar drives
 151 Create a RAID-5 volume from the specified drives.
 152 If no name is specified, a unique name will be set by
 153 .Ic gvinum .
 154 This organization requires at least three drives.
 155 .It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname
 156 Change the name of the specified object.
 157 The
 158 .Fl r
 159 flag will recursively rename subordinate objects.
 160 .Pp
 161 Note that device nodes will not be renamed until
 162 .Nm
 163 is restarted.
 164 .It Ic rebuildparity Oo Fl f Oc Ar plex
 165 Rebuild the parity blocks of a RAID-5 plex.
 166 The parity rebuild will start at
 167 the beginning of the plex if the
 168 .Fl f
 169 flag is specified, or otherwise at the location of the parity check pointer.
 170 All subdisks in the plex must be up for a parity check.
 171 .It Ic resetconfig
 172 Reset the complete
 173 .Nm
 174 configuration.
 175 .It Ic rm Oo Fl r Oc Ar volume | plex | subdisk
 176 Remove an object and, if
 177 .Fl r
 178 is specified, its subordinate objects.
 179 .It Ic saveconfig
 180 Save
 181 .Nm
 182 configuration to disk after configuration failures.
 183 .It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive
 184 Set state without influencing other objects, for diagnostic purposes
 185 only.
 186 The
 187 .Fl f
 188 flag forces state changes regardless of whether they are legal.
 189 .It Ic start
 190 Read configuration from all vinum drives.
 191 .It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk
 192 Allow the system to access the objects.
 193 If necessary, plexes will be synced and rebuilt.
 194 If a subdisk was added to a running RAID-5 or striped plex, gvinum will
 195 expand into this subdisk and grow the whole RAID-5 array.
 196 This can be done without unmounting your filesystem.
 197 The
 198 .Fl S
 199 flag is currently ignored.
 200 .It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk
 201 Terminate access to the objects, or stop
 202 .Nm
 203 if no parameters are specified.
 204 .It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
 205 Create a striped volume from the specified drives. If no name is specified,
 206 a unique name will be set by
 207 .Ic gvinum .
 208 This organization requires at least two drives.
 209 .El
 210 .Sh DESCRIPTION
 211 The
 212 .Nm
 213 utility communicates with the kernel component of the GVinum logical volume
 214 manager.
 215 It is designed either for interactive use, when started without
 216 command line arguments, or to execute a single command if the command is
 217 supplied on the command line.
 218 In interactive mode,
 219 .Nm
 220 maintains a command line history.
 221 .Sh OPTIONS
 222 The
 223 .Nm
 224 commands may be followed by an option.
 225 .Bl -tag -width indent
 226 .It Fl f
 227 The
 228 .Fl f
 229 .Pq Dq force
 230 option overrides safety checks.
 231 It should be used with extreme caution.
 232 This
 233 option is required in order to use the
 234 .Ic move
 235 command.
 236 .It Fl r
 237 The
 238 .Fl r
 239 .Pq Dq recursive
 240 option applies the command recursively to subordinate objects.
 241 For example, in
 242 conjunction with the
 243 .Ic lv
 244 command, the
 245 .Fl r
 246 option will also show information about the plexes and subdisks belonging to
 247 the volume.
 248 It is also used by the
 249 .Ic rename
 250 command to indicate that subordinate objects such as subdisks should be renamed
 251 to match the object(s) specified and by the
 252 .Ic rm
 253 command to delete plexes belonging to a volume and so on.
 254 .It Fl v
 255 The
 256 .Fl v
 257 .Pq Dq verbose
 258 option provides more detailed output.
 259 .It Fl V
 260 The
 261 .Fl V
 262 .Pq Dq "very verbose"
 263 option provides even more detailed output than
 264 .Fl v .
 265 .El
 266 .Sh ENVIRONMENT
 267 .Bl -tag -width ".Ev EDITOR"
 268 .It Ev EDITOR
 269 The name of the editor to use for editing configuration files, by
 270 default
 271 .Xr vi 1
 272 is invoked.
 273 .El
 274 .Sh FILES
 275 .Bl -tag -width ".Pa /dev/gvinum/plex"
 276 .It Pa /dev/gvinum
 277 directory with device nodes for
 278 .Nm
 279 objects
 280 .El
 281 .Sh EXAMPLES
 282 To create a mirror on disks /dev/ada1 and /dev/ada2, create a filesystem,
 283 mount, unmount and then stop
 284 .Ic gvinum :
 285 .Pp
 286 .Dl "gvinum mirror /dev/ada1 /dev/ada2"
 287 .Dl "newfs /dev/gvinum/gvinumvolume0"
 288 .Dl "mount /dev/gvinum/gvinumvolume0 /mnt"
 289 .Dl "..."
 290 .Dl "unmount /mnt"
 291 .Dl "gvinum stop"
 292 .Pp
 293 To create a striped mirror on disks /dev/ada1 /dev/ada2 /dev/ada3 and
 294 /dev/ada4 named "data" and create a filesystem:
 295 .Pp
 296 .Dl "gvinum mirror -s -n data /dev/ada1 /dev/ada2 /dev/ada3 /dev/ada4"
 297 .Dl "newfs /dev/gvinum/data"
 298 .Pp
 299 To create a raid5 array on disks /dev/ada1 /dev/ada2 and /dev/ada3,
 300 with stripesize 493k you can use the raid5 command:
 301 .Pp
 302 .Dl "gvinum raid5 -s 493k /dev/ada1 /dev/ada2 /dev/ada3"
 303 .Pp
 304 Then the volume will be created automatically.
 305 Afterwards, you have to initialize the volume:
 306 .Pp
 307 .Dl "gvinum start myraid5vol"
 308 .Pp
 309 The initialization will start, and the states will be updated when it's
 310 finished.
 311 The list command will give you information about its progress.
 312 .Pp
 313 Imagine that one of the drives fails, and the output of 'printconfig' looks
 314 something like this:
 315 .Pp
 316 .Dl "drive gvinumdrive1 device /dev/ada2"
 317 .Dl "drive gvinumdrive2 device /dev/???"
 318 .Dl "drive gvinumdrive0 device /dev/ada1"
 319 .Dl "volume myraid5vol"
 320 .Dl "plex name myraid5vol.p0 org raid5 986s vol myraid5vol"
 321 .Dl "sd name myraid5vol.p0.s2 drive gvinumdrive2 len 32538s driveoffset 265s"
 322 .Dl "plex myraid5vol.p0 plexoffset 1972s"
 323 .Dl "sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset 265s"
 324 .Dl "plex myraid5vol.p0 plexoffset 986s"
 325 .Dl "sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset 265s"
 326 .Dl "plex myraid5vol.p0 plexoffset 0s"
 327 .Pp
 328 Create a new drive with this configuration:
 329 .Pp
 330 .Dl "drive gdrive4 device /dev/ada4"
 331 .Pp
 332 Then move the stale subdisk to the new drive:
 333 .Pp
 334 .Dl "gvinum move gdrive4 myraid5vol.p0.s2"
 335 .Pp
 336 Then, initiate the rebuild:
 337 .Pp
 338 .Dl "gvinum start myraid5vol.p0"
 339 .Pp
 340 The plex will go up form degraded mode after the rebuild is finished.
 341 The plex can still be used while the rebuild is in progress, although requests
 342 might be delayed.
 343 .Pp
 344 Given the configuration as in the previous example, growing a RAID-5 or STRIPED
 345 array is accomplished by using the grow command:
 346 .Pp
 347 .Dl "gvinum grow myraid5vol.p0 /dev/ada4"
 348 .Pp
 349 If everything went ok, the plex state should now be set to growable.
 350 You can then start the growing with the
 351 .Ic start
 352 command:
 353 .Pp
 354 .Dl "gvinum start myraid5vol.p0"
 355 .Pp
 356 As with rebuilding, you can watch the progress using the
 357 .Ic list
 358 command.
 359 .Pp
 360 For a more advanced usage and detailed explanation of gvinum, the
 361 handbook is recommended.
 362 .Sh SEE ALSO
 363 .Xr geom 4 ,
 364 .Xr geom 8
 365 .Sh HISTORY
 366 The
 367 .Nm
 368 utility first appeared in
 369 .Fx 5.3 .
 370 The
 371 .Nm vinum
 372 utility, on which
 373 .Nm
 374 is based, was written by
 375 .An "Greg Lehey" .
 376 .Pp
 377 The
 378 .Nm
 379 utility
 380 was written by
 381 .An "Lukas Ertl" .
 382 The
 383 .Ic move
 384 and
 385 .Ic rename
 386 commands and
 387 documentation were added by
 388 .An "Chris Jones"
 389 through the 2005 Google Summer
 390 of Code program.
 391 A partial rewrite of gvinum was done by
 392 .An "Lukas Ertl"
 393 and
 394 .An "Ulf Lilleengen"
 395 through the 2007 Google Summer of Code program.
 396 The documentation have been updated to reflect the new functionality.
 397 .Sh AUTHORS
 398 .An Lukas Ertl Aq le@FreeBSD.org
 399 .An Chris Jones Aq soc-cjones@FreeBSD.org
 400 .An Ulf Lilleengen Aq lulf@FreeBSD.org
 401 .Sh BUGS
 402 Currently,
 403 .Nm
 404 does not rename devices in
 405 .Pa /dev/gvinum
 406 until reloaded.
 407 .Pp
 408 The
 409 .Fl S
 410 initsize flag to
 411 .Ic start
 412 is ignored.
 413 .Pp
 414 Moving subdisks that are not part of a mirrored or RAID-5 volume will
 415 destroy data.
 416 It is perhaps a bug to permit this.
 417 .Pp
 418 Plexes in which subdisks have been moved do not automatically sync or
 419 rebuild parity.
 420 This may leave data unprotected and is perhaps unwise.
 421 .Pp
 422 Currently,
 423 .Nm
 424 does not yet fully implement all of the functions found in
 425 .Nm vinum .
 426 Specifically, the following commands from
 427 .Nm vinum
 428 are not supported:
 429 .Bl -tag -width indent
 430 .It Ic debug
 431 Cause the volume manager to enter the kernel debugger.
 432 .It Ic debug Ar flags
 433 Set debugging flags.
 434 .It Ic dumpconfig Op Ar drive ...
 435 List the configuration information stored on the specified drives, or all
 436 drives in the system if no drive names are specified.
 437 .It Ic info Op Fl vV
 438 List information about volume manager state.
 439 .It Ic label Ar volume
 440 Create a volume label.
 441 .It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk
 442 Reset statistics counters for the specified objects, or for all objects if none
 443 are specified.
 444 .It Ic setdaemon Op Ar value
 445 Set daemon configuration.
 446 .El