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