1 .\" Copyright (c) 2006-2011 Ivan Voras <ivoras@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd "control utility for virtual data storage devices"
75 utility is used for setting up a virtual storage device of arbitrary
77 .Pq for example, several TB ,
78 consisting of an arbitrary number of physical storage devices with the
79 total size which is equal to or smaller than the virtual size.
80 Data for the virtual devices will be allocated from physical devices on
84 is similar to the concept of Virtual Memory in operating systems,
85 effectively allowing users to overcommit on storage
86 .Pq free file system space .
87 The concept is also known as "thin provisioning" in virtualization
88 environments, only here it is implemented on the level of physical storage
93 indicates an action to be performed:
94 .Bl -tag -width ".Cm remove"
96 Set up a virtual device from the given components with the specified
98 Metadata is stored in the last sector of every component.
101 is the size of new virtual device, with default being set to 2 TiB
105 is the chunk size, with default being set to 4 MiB
107 The default arguments are thus
108 .Qq Fl s Ar 2097152 Fl m Ar 4096 .
110 Turn off an existing virtual device with the given
112 This command does not touch on-disk metadata.
113 As with other GEOM classes, stopped geoms cannot be started manually.
118 Adds new components to existing virtual device with the given
120 The specified virstor device must exist and be active
121 .Pq i.e. module loaded, device present in Pa /dev .
122 This action can be safely performed while the virstor device is in use
123 .Pq Qo hot Qc operation .
125 Removes components from existing virtual device with the given
127 Only unallocated providers can be removed.
129 Clear metadata on the given providers.
131 Dump metadata stored on the given providers.
147 .Bl -tag -width ".Fl f"
149 Force the removal of the specified virtual device.
151 Hardcode providers' names in metadata.
156 The following example shows how to create a virtual device of default size
162 with two physical devices for backing storage.
163 .Bd -literal -offset indent
164 .No gvirstor label -v Ar mydata Ar /dev/ada4 Ar /dev/ada6
165 .No newfs Ar /dev/virstor/mydata
168 From now on, the virtual device will be available via the
169 .Pa /dev/virstor/mydata
171 To add a new physical device / component to an active virstor device:
172 .Bd -literal -offset indent
173 .No gvirstor add Ar mydata Ar ada8
176 This will add physical storage of
179 .Pa /dev/virstor/mydata
182 To see the device status information
183 .Pq including how much physical storage is still available for the virtual device ,
185 .Bd -literal -offset indent
192 .Pq e.g. Cm status , Cm help
199 .Bd -literal -offset indent
200 .Va int kern.geom.virstor.debug
203 This sysctl controls verbosity of the kernel module, in the range
205 Messages that are marked with higher verbosity levels than this are
207 Default value is 5 and it is not recommended to set this tunable to less
208 than 2, because level 1 messages are error events, and level 2 messages
210 .Bd -literal -offset indent
211 .Va int kern.geom.virstor.chunk_watermark
214 Value in this sysctl sets warning watermark level for physical chunk
215 usage on a single component.
216 The warning is issued when a virstor component has less than this many
219 .Bd -literal -offset indent
220 .Va int kern.geom.virstor.component_watermark
223 Value in this sysctl sets warning watermark level for component usage.
224 The warning is issued when there are less than this many unallocated
228 All these sysctls are also available as
235 kernel module issues log messages with prefixes in standardized format,
236 which is useful for log message filtering and dispatching.
237 Each message line begins with
238 .Bd -literal -offset indent
239 .Li GEOM_VIRSTOR[%d]:
244 is message verbosity / importance level, in the range 1 to 15.
245 If a message filtering, dispatching or operator alert system is used, it
246 is recommended that messages with levels 1 and 2 be taken seriously
247 .Pq for example, to catch out-of-space conditions as set by watermark
258 utility first appeared in
261 .An Ivan Voras Aq Mt ivoras@FreeBSD.org
263 Sponsored by Google Summer of Code 2006.
269 contain unavoidable critical sections which may make the virstor
270 device unusable if a power failure
271 .Pq or other disruptive event
272 happens during their execution.
273 It is recommended to run them when the system is quiescent.
274 .Sh ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS
275 There are several assumptions that
277 has in its operation: that the size of the virtual storage device will not
278 change once it is set, and that the sizes of individual physical storage
279 components will always remain constant during their existence.
280 For alternative ways to implement virtual or resizable file systems see
288 has nontrivial interaction with file systems which initialize a large
289 number of on-disk structures during newfs.
290 If such file systems attempt to spread their structures across the drive
292 .Pq like UFS/UFS2 does ,
293 their efforts will be effectively foiled by sequential allocation of
296 and all their structures will be physically allocated at the start
297 of the first virstor component.
298 This could have a significant impact on file system performance
299 .Pq which can in some rare cases be even positive .