GVIRSTOR(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💾 GVIRSTOR(8) 💾 — the System Manager's Manual one, bestie

okay so this is gvirstor from section 8 of the manual (that's the sysadmin-y section, iykyk) and honestly? she's a whole vibe. thin provisioning but make it ✨physical storage devices✨. let's get into it 🫶

✨ NAME ✨

gvirstor — control utility for virtual data storage devices 💅

🎀 SYNOPSIS 🎀

gvirstor label [-hv] [-s virsize] [-m chunksize] name prov ...
gvirstor stop [-fv] name ...
gvirstor destroy [-fv] name ...
gvirstor add [-vh] name prov ...
gvirstor remove [-v] name prov ...
gvirstor clear [-v] prov ...
gvirstor dump prov ...
gvirstor list
gvirstor status
gvirstor load
gvirstor unload

🌸 DESCRIPTION 🌸

okay so <pink>gvirstor</pink> is the utility you use to set up a virtual storage device of arbitrary large size (like, think several TB, no big deal 😭), and that virtual device is made out of an arbitrary number of physical storage devices whose total size is equal to or smaller than the virtual size. yes, you read that right. the physical stuff is smaller. that's the whole point, bestie 💅

Data for the virtual devices gets allocated from the physical devices on demand. The idea behind <pink>gvirstor</pink> is basically Virtual Memory but for storage — hi, operating systems concept, we love to see it — and it effectively lets users overcommit on storage (that's free file system space, fyi). In virtualization land this concept is also known as "thin provisioning", except here it's implemented down at the level of physical storage devices. iconic behavior honestly 👑

The first argument to <pink>gvirstor</pink> tells it what action to perform:

  • label — sets up a virtual device from the given components with the specified name. Metadata is stored in the last sector of every component. The argument -s virsize is the size of the new virtual device, and the default is set to 2 TiB (2097152 MiB). The argument -m chunksize is the chunk size, defaulting to 4 MiB (4096 KiB). So the default arguments are literally just "-s 2097152 -m 4096". defaults ate, periodt ✨
  • stop — turns off an existing virtual device with the given name. This command does not touch on-disk metadata (so like, your data's fine, chill 🙈). As with other GEOM classes, stopped geoms cannot be started manually.
  • destroy — same as stop. yeah. that's the whole entry. twin behavior 💀
  • add — adds new components to an existing virtual device with the given name. The specified virstor device must exist and be active (i.e. module loaded, device present in /dev). This action can be safely performed while the virstor device is in use — that's a "hot" operation, bestie 🔥
  • remove — removes components from an existing virtual device with the given name. Only unallocated providers can be removed.
  • clear — clears metadata on the given providers.
  • dump — dumps metadata stored on the given providers.
  • list — see geom(8).
  • status — see geom(8).
  • load — see geom(8).
  • unload — see geom(8).

🌈 Additional options 🌈

  • -f — force the removal of the specified virtual device.
  • -h — hardcode providers' names in metadata.
  • -v — be more verbose. (she's chatty, we love her 🗣️)

🦋 EXAMPLES 🦋

The following example shows how to create a virtual device of default size (2 TiB), of default chunk (extent) size (4 MiB), with two physical devices for backing storage:

gvirstor label -v mydata /dev/ada4 /dev/ada6
newfs /dev/virstor/mydata

From now on, the virtual device will be available via the /dev/virstor/mydata device entry. slay 💖

To add a new physical device / component to an active virstor device:

gvirstor add mydata ada8

This will add physical storage of ada8 to the /dev/virstor/mydata device. hot-swap queen 🧚

To see the device status information (including how much physical storage is still available for the virtual device), use:

gvirstor list

All standard geom(8) subcommands (e.g. status, help) are also supported. 💅

⭐ SYSCTL VARIABLES ⭐

gvirstor has several sysctl(8) tunable variables, and here they are:

int kern.geom.virstor.debug

This sysctl controls verbosity of the kernel module, in the range 1 to 15. Messages that are marked with higher verbosity levels than this are suppressed. Default value is 5, and it is not recommended to set this tunable to less than 2, because level 1 messages are error events and level 2 messages are system warnings. so like, don't mute your errors bestie 😭

int kern.geom.virstor.chunk_watermark

Value in this sysctl sets the warning watermark level for physical chunk usage on a single component. The warning is issued when a virstor component has less than this many free chunks (default 100).

int kern.geom.virstor.component_watermark

Value in this sysctl sets the warning watermark level for component usage. The warning is issued when there are less than this many unallocated components (default is 1).

All these sysctls are also available as loader(8) tunables. 🎀

🔥 DIAGNOSTICS 🔥

The <pink>gvirstor</pink> utility exits 0 on success, and >0 if an error occurs.

The <pink>gvirstor</pink> kernel module issues log messages with prefixes in a standardized format, which is genuinely useful for log message filtering and dispatching. Each message line begins with:

GEOM_VIRSTOR[%d]:

The number (%d) is the message verbosity / importance level, in the range 1 to 15. If a message filtering, dispatching or operator alert system is used, it is recommended that messages with levels 1 and 2 be taken seriously (for example, to catch out-of-space conditions as set by the watermark sysctls). like, actually seriously. don't scroll past them 🙏

💜 SEE ALSO 💜

geom(4), fstab(5), geom(8), glabel(8), newfs(8)

👑 HISTORY 👑

The <pink>gvirstor</pink> utility first appeared in FreeBSD 7.0. a legend was born ✨

🌸 AUTHORS 🌸

Ivan Voras <ivoras@FreeBSD.org>

Sponsored by Google Summer of Code 2006. 🎀

💀 BUGS 💀

Commands add and remove contain unavoidable critical sections which may make the virstor device unusable if a power failure (or other disruptive event) happens during their execution. It is recommended to run them when the system is quiescent. no cap, just wait until things are chill first 😭

🧚 ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS 🧚

There are several assumptions that <pink>gvirstor</pink> has in its operation:

  • that the size of the virtual storage device will not change once it is set, and
  • that the sizes of individual physical storage components will always remain constant during their existence.

For alternative ways to implement virtual or resizable file systems see zfs(1M), gconcat(8) and growfs(8).

Note that <pink>gvirstor</pink> has nontrivial interaction with file systems which initialize a large number of on-disk structures during newfs. If such file systems attempt to spread their structures across the drive media (like UFS/UFS2 does), their efforts will be effectively foiled by sequential allocation of chunks in gvirstor and all their structures will be physically allocated at the start of the first virstor component. This could have a significant impact on file system performance (which can in some rare cases be even positive 🙈). it's giving "your fave tried their best but the chunk allocator said no" 💅

and that's the whole page, bestie 🫶 this one came from the Debian build of the manual, dated October 1, 2013 — vintage but still serving looks 💖✨

📦 where this page comes from