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