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