GVINUM(8)

📦 version 14.5, in freebsd 14.5

💖 GVINUM 💖

hey bestie, welcome to the manual page for gvinum — the System Manager's Manual's very own Logical Volume Manager control program. yes she's iconic, yes she's also deprecated (more on that in a sec 🫣), and yes we're gonna read the whole thing together. grab a snack. 🍓

🌸 NAME 🌸

gvinum — Logical Volume Manager control program

🚨 DEPRECATION NOTICE 🚨

okay so this is important, please actually read it: gvinum and the associated geom(4) kernel support is deprecated, and is not available in FreeBSD 15.0 and later. 😭

Users are advised to migrate to gconcat(8), gmirror(8), gstripe(8), graid(8), or zfs(8). More information is available at https://wiki.freebsd.org/DeprecationPlan/gvinum.

✨ SYNOPSIS ✨

gvinum [command] [-options]

🎀 COMMANDS 🎀

okay so this is the whole menu of things she can do. every single one. no skipping. 💅

  • attach plex volume [rename]
  • attach subdisk plex [offset] [rename] — Attach a plex to a volume, or a subdisk to a plex. If offset is specified, the subdisk will be attached to the given offset within the plex. If rename is specified, the subdisk or plex will change name according to the object it attaches to.
  • checkparity [-f] plex — Check the parity blocks of a RAID-5 plex. The parity check will start at the beginning of the plex if the -f flag is specified, or otherwise at the location of the parity check pointer, the first location at which plex's parity is incorrect. All subdisks in the plex must be up for a parity check.
  • concat [-fv] [-n name] drives — Create a concatenated volume from the specified drives. If no name is specified, a unique name will be set by gvinum.
  • create [-f] [description-file] — Create a volume as described in description-file. If no description-file provided, opens an editor and provides the current gvinum configuration for editing. The -f flag will make gvinum ignore any errors regarding creating objects that already exists. However, in contrast to vinum, objects that are not properly named in the description-file will not be created when the -f flag is given. 👀 (yes, that's a real difference, don't @ me)
  • detach [-f] [plex | subdisk] — Detach a plex or subdisk from the volume or plex to which it is attached.
  • grow plex device — Grow a plex by creating a gvinum drive and subdisk on device and attach it to the plex. If required by the plex organization, it will be put into the growable state.
  • help — Provides a synopsis of gvinum commands and arguments. (the "bestie help me" of commands 🫶)
  • l | list [-rvV] [volume | plex | subdisk]
  • ld [-rvV] [drive ...]
  • ls [-rvV] [subdisk ...]
  • lp [-rvV] [plex ...]
  • lv [-rvV] [volume ...] — List information about the relevant object(s). The -r flag provides recursive display, showing each object's subordinate objects in proper relation. The -v and -V flags provide progressively more detailed output.
  • mirror [-fsv] [-n name] drives — Create a mirrored volume from the specified drives. It requires at least a multiple of 2 drives. If no name is specified, a unique name will be set by gvinum. If the -s flag is specified, a striped mirror will be created, and thus requires a multiple of 4 drives.
  • move | mv -f drive subdisk [...] — Move the subdisk(s) to the specified drive. The -f flag is required, as all data on the indicated subdisk(s) will be destroyed as part of the move. This can currently only be done when the subdisk is not being accessed.

If a single subdisk is moved, and it forms a part of a RAID-5 plex, the moved subdisks will need to be set to the “stale” state, and the plex will require a start command. If multiple subdisk(s) is moved, and form part of a RAID-5 plex, the moved disk(s) will need to be set to the “up” state and the plex will require a rebuildparity command. If the subdisk(s) form part of a plex that is mirrored with other plexes, the plex will require restarting and will sync once restarted. Moving more than one subdisk in a RAID-5 plex or subdisks from both sides of a mirrored plex volume will destroy data. Note that parity rebuilds and syncing must be started manually after a move. 💀

  • printconfig — Write a copy of the current configuration to standard output.
  • quit — Exit gvinum when running in interactive mode. Normally this would be done by entering the EOF character.
  • raid5 [-fv] [-s stripesize] [-n name] drives — Create a RAID-5 volume from the specified drives. If no name is specified, a unique name will be set by gvinum. This organization requires at least three drives.
  • rename [-r] drive | subdisk | plex | volume newname — Change the name of the specified object. The -r flag will recursively rename subordinate objects.
⚠️ Note that device nodes will not be renamed until gvinum is restarted. so don't panic when you don't see it yet, bestie.
  • rebuildparity [-f] plex — Rebuild the parity blocks of a RAID-5 plex. The parity rebuild will start at the beginning of the plex if the -f flag is specified, or otherwise at the location of the parity check pointer. All subdisks in the plex must be up for a parity check.
  • resetconfig [-f] — Reset the complete gvinum configuration. (nuclear option fr fr 🧨)
  • rm [-r] volume | plex | subdisk — Remove an object and, if -r is specified, its subordinate objects.
  • saveconfig — Save gvinum configuration to disk after configuration failures.
  • setstate [-f] state volume | plex | subdisk | drive — Set state without influencing other objects, for diagnostic purposes only. The -f flag forces state changes regardless of whether they are legal.
  • start — Read configuration from all vinum drives.
  • start [-S size] volume | plex | subdisk — Allow the system to access the objects. If necessary, plexes will be synced and rebuilt. If a subdisk was added to a running RAID-5 or striped plex, gvinum will expand into this subdisk and grow the whole RAID-5 array. This can be done without unmounting your filesystem. The -S flag is currently ignored.
  • stop [-f] [volume | plex | subdisk] — Terminate access to the objects, or stop gvinum if no parameters are specified.
  • stripe [-fv] [-n name] drives — Create a striped volume from the specified drives. If no name is specified, a unique name will be set by gvinum. This organization requires at least two drives.

🦋 DESCRIPTION 🦋

The gvinum utility communicates with the kernel component of the GVinum logical volume manager. It is designed either for interactive use, when started without command line arguments, or to execute a single command if the command is supplied on the command line. In interactive mode, gvinum maintains a command line history. (main character energy: she remembers what you said last time 💅)

🌈 OPTIONS 🌈

The gvinum commands may be followed by an option.

  • -f — The -f (“force”) option overrides safety checks. It should be used with extreme caution. This option is required in order to use the move command.
  • -r — The -r (“recursive”) option applies the command recursively to subordinate objects. For example, in conjunction with the lv command, the -r option will also show information about the plexes and subdisks belonging to the volume. It is also used by the rename command to indicate that subordinate objects such as subdisks should be renamed to match the object(s) specified and by the rm command to delete plexes belonging to a volume and so on.
  • -v — The -v (“verbose”) option provides more detailed output.
  • -V — The -V (“very verbose”) option provides even more detailed output than -v. (she's extra and we love her 💖)

🌿 ENVIRONMENT 🌿

  • EDITOR — The name of the editor to use for editing configuration files, by default vi(1) is invoked.

📁 FILES 📁

  • /dev/gvinum — directory with device nodes for gvinum objects

💫 EXAMPLES 💫

To create a mirror on disks /dev/ada1 and /dev/ada2, create a filesystem, mount, unmount and then stop gvinum:

gvinum mirror /dev/ada1 /dev/ada2
newfs /dev/gvinum/gvinumvolume0
mount /dev/gvinum/gvinumvolume0 /mnt
...
unmount /mnt
gvinum stop

To create a striped mirror on disks /dev/ada1 /dev/ada2 /dev/ada3 and /dev/ada4 named "data" and create a filesystem:

gvinum mirror -s -n data /dev/ada1 /dev/ada2 /dev/ada3 /dev/ada4
newfs /dev/gvinum/data

To create a raid5 array on disks /dev/ada1 /dev/ada2 and /dev/ada3, with stripesize 493k you can use the raid5 command:

gvinum raid5 -s 493k /dev/ada1 /dev/ada2 /dev/ada3

Then the volume will be created automatically. Afterwards, you have to initialize the volume:

gvinum start myraid5vol

The initialization will start, and the states will be updated when it's finished. The list command will give you information about its progress. 👑

Imagine that one of the drives fails, and the output of 'printconfig' looks something like this:

drive gvinumdrive1 device /dev/ada2
drive gvinumdrive2 device /dev/???
drive gvinumdrive0 device /dev/ada1
volume myraid5vol
plex name myraid5vol.p0 org raid5 986s vol myraid5vol
sd name myraid5vol.p0.s2 drive gvinumdrive2 len 32538s driveoffset
265s
plex myraid5vol.p0 plexoffset 1972s
sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset
265s
plex myraid5vol.p0 plexoffset 986s
sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset
265s
plex myraid5vol.p0 plexoffset 0s

Create a new drive with this configuration:

drive gdrive4 device /dev/ada4

Then move the stale subdisk to the new drive:

gvinum move gdrive4 myraid5vol.p0.s2

Then, initiate the rebuild:

gvinum start myraid5vol.p0

The plex will go up from degraded mode after the rebuild is finished. The plex can still be used while the rebuild is in progress, although requests might be delayed.

Given the configuration as in the previous example, growing a RAID-5 or STRIPED array is accomplished by using the grow command:

gvinum grow myraid5vol.p0 /dev/ada4

If everything went ok, the plex state should now be set to growable. You can then start the growing with the start command:

gvinum start myraid5vol.p0

As with rebuilding, you can watch the progress using the list command.

For a more advanced usage and detailed explanation of gvinum, the handbook is recommended. 📖

🌟 SEE ALSO 🌟

geom(4), geom(8)

🌸 HISTORY 🌸

okay so story time, bestie 💖 — gvinum first showed up in FreeBSD 5.3. and like, it didn't come from nowhere: the vinum utility, which gvinum is literally based on, was written by Greg Lehey. iconic lineage fr 🔥

the gvinum utility itself was written by Lukas Ertl. then Chris Jones added the move and rename commands and the documentation, all through the 2005 Google Summer of Code program 🎀. a partial rewrite of gvinum was done by Lukas Ertl and Ulf Lilleengen through the 2007 Google Summer of Code program, and the documentation has been updated to reflect the new functionality. glow-up behavior, no cap ✨

👑 AUTHORS 👑

the brains behind the whole vibe, give them their flowers 🫶:

  • Lukas Ertl <le@FreeBSD.org>
  • Chris Jones <soc-cjones@FreeBSD.org>
  • Ulf Lilleengen <lulf@FreeBSD.org>

💀 BUGS 💀

okay bestie, this is the part where we sit down and have a little talk 🙈. none of this is a vibe, but you need to know it:

  • Currently, gvinum does not rename devices in /dev/gvinum until reloaded. so like, the name change is giving nothing until you reload 😭
  • The -S initsize flag to start is ignored. literally ignored. don't count on it.
  • Moving subdisks that are not part of a mirrored or RAID-5 volume will destroy data. It is perhaps a bug to permit this. so yeah — data gone, unalive, periodt 💀
  • Plexes in which subdisks have been moved do not automatically sync or rebuild parity. This may leave data unprotected and is perhaps unwise. unprotected data is not the serve you think it is 🚩
  • Currently, gvinum does not yet fully implement all of the functions found in vinum. Specifically, the following commands from vinum are not supported — like, they're just not in the group chat:
  • debug — Cause the volume manager to enter the kernel debugger.
  • debug flags — Set debugging flags.
  • dumpconfig [drive ...] — List the configuration information stored on the specified drives, or all drives in the system if no drive names are specified.
  • info [-vV] — List information about volume manager state.
  • label volume — Create a volume label.
  • resetstats [-r] [volume | plex | subdisk] — Reset statistics counters for the specified objects, or for all objects if none are specified.
  • setdaemon [value] — Set daemon configuration.
bestie please read the destroy-data one twice. i'm so serious. 🫶

and that's the whole page, you made it to the end!! 🌈 this one's from the Debian build, dated January 23, 2025, and it lives at section GVINUM(8) 🎀 go forth and configure your volumes responsibly, mwah 💅✨

📦 where this page comes from
  • freebsd 14.5: base 14.5
  • Copyright (c) 2005 Chris Jones
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms