1.\" Copyright (c) 2004-2005 Pawel Jakub Dawidek <pjd@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 12.\" 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 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd June 14, 2021 28.Dt GCONCAT 8 29.Os 30.Sh NAME 31.Nm gconcat 32.Nd "disk concatenation control utility" 33.Sh SYNOPSIS 34.Nm 35.Cm create 36.Op Fl v 37.Ar name 38.Ar prov ... 39.Nm 40.Cm destroy 41.Op Fl fv 42.Ar name ... 43.Nm 44.Cm label 45.Op Fl hv 46.Ar name 47.Ar prov ... 48.Nm 49.Cm append 50.Op Fl hv 51.Ar name 52.Ar prov 53.Nm 54.Cm stop 55.Op Fl fv 56.Ar name ... 57.Nm 58.Cm clear 59.Op Fl v 60.Ar prov ... 61.Nm 62.Cm dump 63.Ar prov ... 64.Nm 65.Cm list 66.Nm 67.Cm status 68.Nm 69.Cm load 70.Nm 71.Cm unload 72.Sh DESCRIPTION 73The 74.Nm 75utility is used for device concatenation configuration. 76The concatenation can be configured using two different methods: 77.Dq manual 78or 79.Dq automatic . 80When using the 81.Dq manual 82method, no metadata are stored on the devices, so the concatenated 83device has to be configured by hand every time it is needed. 84The 85.Dq automatic 86method uses on-disk metadata to detect devices. 87Once devices are labeled, they will be automatically detected and 88configured. 89.Pp 90The first argument to 91.Nm 92indicates an action to be performed: 93.Bl -tag -width ".Cm destroy" 94.It Cm create 95Concatenate the given devices with specified 96.Ar name . 97This is the 98.Dq manual 99method. 100The kernel module 101.Pa geom_concat.ko 102will be loaded if it is not loaded already. 103.It Cm label 104Concatenate the given devices with the specified 105.Ar name . 106This is the 107.Dq automatic 108method, where metadata are stored in every device's last sector. 109The kernel module 110.Pa geom_concat.ko 111will be loaded if it is not loaded already. 112.Pp 113Additional options include: 114.Bl -tag -width ".Fl h" 115.It Fl h 116Hardcode providers' names in metadata. 117.El 118.It Cm append 119Append a new device to the end of an existing concatenate device 120with the specified 121.Ar name . 122.Pp 123If the existing device is using the 124.Dq manual 125method, the new device is simply appended as-is. 126.Pp 127If the existing device is using the 128.Dq automatic 129method, the device is appended persistently. 130New 131.Cm gconcat 132metadata is written to all existing components, as well as to the 133newly added one. 134.Pp 135Additional options include: 136.Bl -tag -width ".Fl h" 137.It Fl h 138Hardcode providers' names in metadata. 139.El 140.It Cm stop 141Turn off existing concatenate device by its 142.Ar name . 143This command does not touch on-disk metadata! 144.Pp 145Additional options include: 146.Bl -tag -width ".Fl f" 147.It Fl f 148Stop the given device even if it is opened. 149.El 150.It Cm destroy 151Same as 152.Cm stop . 153.It Cm clear 154Clear metadata on the given devices. 155.It Cm dump 156Dump metadata stored on the given devices. 157.It Cm list 158See 159.Xr geom 8 . 160.It Cm status 161See 162.Xr geom 8 . 163.It Cm load 164See 165.Xr geom 8 . 166.It Cm unload 167See 168.Xr geom 8 . 169.El 170.Pp 171Additional options: 172.Bl -tag -width indent 173.It Fl v 174Be more verbose. 175.El 176.Sh SYSCTL VARIABLES 177The following 178.Xr sysctl 8 179variables can be used to control the behavior of the 180.Nm CONCAT 181GEOM class. 182The default value is shown next to each variable. 183.Bl -tag -width indent 184.It Va kern.geom.concat.debug : No 0 185Debug level of the 186.Nm CONCAT 187GEOM class. 188This can be set to a number between 0 and 3 inclusive. 189If set to 0 minimal debug information is printed, and if set to 3 the 190maximum amount of debug information is printed. 191.El 192.Sh EXIT STATUS 193Exit status is 0 on success, and 1 if the command fails. 194.Sh EXAMPLES 195The following example shows how to configure four disks for automatic 196concatenation, create a file system on it, and mount it: 197.Bd -literal -offset indent 198gconcat label -v data /dev/da0 /dev/da1 /dev/da2 /dev/da3 199newfs /dev/concat/data 200mount /dev/concat/data /mnt 201[...] 202umount /mnt 203gconcat stop data 204gconcat unload 205.Ed 206.Pp 207Configure concatenated provider on one disk only. 208Create file system. 209Add two more disks and extend existing file system. 210.Bd -literal -offset indent 211gconcat label data /dev/da0 212newfs /dev/concat/data 213gconcat label data /dev/da0 /dev/da1 /dev/da2 214growfs /dev/concat/data 215.Ed 216.Sh SEE ALSO 217.Xr geom 4 , 218.Xr loader.conf 5 , 219.Xr geom 8 , 220.Xr growfs 8 , 221.Xr gvinum 8 , 222.Xr mount 8 , 223.Xr newfs 8 , 224.Xr sysctl 8 , 225.Xr umount 8 226.Sh HISTORY 227The 228.Nm 229utility appeared in 230.Fx 5.3 . 231.Sh AUTHORS 232.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org 233