diff options
Diffstat (limited to 'lib/geom/concat/gconcat.8')
| -rw-r--r-- | lib/geom/concat/gconcat.8 | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/lib/geom/concat/gconcat.8 b/lib/geom/concat/gconcat.8 new file mode 100644 index 000000000000..165f809ffba8 --- /dev/null +++ b/lib/geom/concat/gconcat.8 @@ -0,0 +1,229 @@ +.\" Copyright (c) 2004-2005 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 23, 2025 +.Dt GCONCAT 8 +.Os +.Sh NAME +.Nm gconcat +.Nd "disk concatenation control utility" +.Sh SYNOPSIS +.Nm +.Cm create +.Op Fl v +.Ar name +.Ar prov ... +.Nm +.Cm destroy +.Op Fl fv +.Ar name ... +.Nm +.Cm label +.Op Fl hv +.Ar name +.Ar prov ... +.Nm +.Cm append +.Op Fl hv +.Ar name +.Ar prov +.Nm +.Cm stop +.Op Fl fv +.Ar name ... +.Nm +.Cm clear +.Op Fl v +.Ar prov ... +.Nm +.Cm dump +.Ar prov ... +.Nm +.Cm list +.Nm +.Cm status +.Nm +.Cm load +.Nm +.Cm unload +.Sh DESCRIPTION +The +.Nm +utility is used for device concatenation configuration. +The concatenation can be configured using two different methods: +.Dq manual +or +.Dq automatic . +When using the +.Dq manual +method, no metadata are stored on the devices, so the concatenated +device has to be configured by hand every time it is needed. +The +.Dq automatic +method uses on-disk metadata to detect devices. +Once devices are labeled, they will be automatically detected and +configured. +.Pp +The first argument to +.Nm +indicates an action to be performed: +.Bl -tag -width ".Cm destroy" +.It Cm create +Concatenate the given devices with specified +.Ar name . +This is the +.Dq manual +method. +The kernel module +.Pa geom_concat.ko +will be loaded if it is not loaded already. +.It Cm label +Concatenate the given devices with the specified +.Ar name . +This is the +.Dq automatic +method, where metadata are stored in every device's last sector. +The kernel module +.Pa geom_concat.ko +will be loaded if it is not loaded already. +.Pp +Additional options include: +.Bl -tag -width ".Fl h" +.It Fl h +Hardcode providers' names in metadata. +.El +.It Cm append +Append a new device to the end of an existing concatenate device +with the specified +.Ar name . +.Pp +If the existing device is using the +.Dq manual +method, the new device is simply appended as-is. +.Pp +If the existing device is using the +.Dq automatic +method, the device is appended persistently. +New +.Cm gconcat +metadata is written to all existing components, as well as to the +newly added one. +.Pp +Additional options include: +.Bl -tag -width ".Fl h" +.It Fl h +Hardcode providers' names in metadata. +.El +.It Cm stop +Turn off existing concatenate device by its +.Ar name . +This command does not touch on-disk metadata! +.Pp +Additional options include: +.Bl -tag -width ".Fl f" +.It Fl f +Stop the given device even if it is opened. +.El +.It Cm destroy +Same as +.Cm stop . +.It Cm clear +Clear metadata on the given devices. +.It Cm dump +Dump metadata stored on the given devices. +.It Cm list +See +.Xr geom 8 . +.It Cm status +See +.Xr geom 8 . +.It Cm load +See +.Xr geom 8 . +.It Cm unload +See +.Xr geom 8 . +.El +.Pp +Additional options: +.Bl -tag -width indent +.It Fl v +Be more verbose. +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables can be used to control the behavior of the +.Nm CONCAT +GEOM class. +The default value is shown next to each variable. +.Bl -tag -width indent +.It Va kern.geom.concat.debug : No 0 +Debug level of the +.Nm CONCAT +GEOM class. +This can be set to a number between 0 and 3 inclusive. +If set to 0 minimal debug information is printed, and if set to 3 the +maximum amount of debug information is printed. +.El +.Sh EXIT STATUS +Exit status is 0 on success, and 1 if the command fails. +.Sh EXAMPLES +The following example shows how to configure four disks for automatic +concatenation, create a file system on it, and mount it: +.Bd -literal -offset indent +gconcat label -v data /dev/da0 /dev/da1 /dev/da2 /dev/da3 +newfs /dev/concat/data +mount /dev/concat/data /mnt +[...] +umount /mnt +gconcat stop data +gconcat unload +.Ed +.Pp +Configure concatenated provider on one disk only. +Create file system. +Add two more disks and extend existing file system. +.Bd -literal -offset indent +gconcat label data /dev/da0 +newfs /dev/concat/data +gconcat label data /dev/da0 /dev/da1 /dev/da2 +growfs /dev/concat/data +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr loader.conf 5 , +.Xr geom 8 , +.Xr growfs 8 , +.Xr mount 8 , +.Xr newfs 8 , +.Xr sysctl 8 , +.Xr umount 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.3 . +.Sh AUTHORS +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org |