lib/geom/concat/gconcat.8

   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
  73 The
  74 .Nm
  75 utility is used for device concatenation configuration.
  76 The concatenation can be configured using two different methods:
  77 .Dq manual
  78 or
  79 .Dq automatic .
  80 When using the
  81 .Dq manual
  82 method, no metadata are stored on the devices, so the concatenated
  83 device has to be configured by hand every time it is needed.
  84 The
  85 .Dq automatic
  86 method uses on-disk metadata to detect devices.
  87 Once devices are labeled, they will be automatically detected and
  88 configured.
  89 .Pp
  90 The first argument to
  91 .Nm
  92 indicates an action to be performed:
  93 .Bl -tag -width ".Cm destroy"
  94 .It Cm create
  95 Concatenate the given devices with specified
  96 .Ar name .
  97 This is the
  98 .Dq manual
  99 method.
 100 The kernel module
 101 .Pa geom_concat.ko
 102 will be loaded if it is not loaded already.
 103 .It Cm label
 104 Concatenate the given devices with the specified
 105 .Ar name .
 106 This is the
 107 .Dq automatic
 108 method, where metadata are stored in every device's last sector.
 109 The kernel module
 110 .Pa geom_concat.ko
 111 will be loaded if it is not loaded already.
 112 .Pp
 113 Additional options include:
 114 .Bl -tag -width ".Fl h"
 115 .It Fl h
 116 Hardcode providers' names in metadata.
 117 .El
 118 .It Cm append
 119 Append a new device to the end of an existing concatenate device
 120 with the specified
 121 .Ar name .
 122 .Pp
 123 If the existing device is using the
 124 .Dq manual
 125 method, the new device is simply appended as-is.
 126 .Pp
 127 If the existing device is using the
 128 .Dq automatic
 129 method, the device is appended persistently.
 130 New
 131 .Cm gconcat
 132 metadata is written to all existing components, as well as to the
 133 newly added one.
 134 .Pp
 135 Additional options include:
 136 .Bl -tag -width ".Fl h"
 137 .It Fl h
 138 Hardcode providers' names in metadata.
 139 .El
 140 .It Cm stop
 141 Turn off existing concatenate device by its
 142 .Ar name .
 143 This command does not touch on-disk metadata!
 144 .Pp
 145 Additional options include:
 146 .Bl -tag -width ".Fl f"
 147 .It Fl f
 148 Stop the given device even if it is opened.
 149 .El
 150 .It Cm destroy
 151 Same as
 152 .Cm stop .
 153 .It Cm clear
 154 Clear metadata on the given devices.
 155 .It Cm dump
 156 Dump metadata stored on the given devices.
 157 .It Cm list
 158 See
 159 .Xr geom 8 .
 160 .It Cm status
 161 See
 162 .Xr geom 8 .
 163 .It Cm load
 164 See
 165 .Xr geom 8 .
 166 .It Cm unload
 167 See
 168 .Xr geom 8 .
 169 .El
 170 .Pp
 171 Additional options:
 172 .Bl -tag -width indent
 173 .It Fl v
 174 Be more verbose.
 175 .El
 176 .Sh SYSCTL VARIABLES
 177 The following
 178 .Xr sysctl 8
 179 variables can be used to control the behavior of the
 180 .Nm CONCAT
 181 GEOM class.
 182 The default value is shown next to each variable.
 183 .Bl -tag -width indent
 184 .It Va kern.geom.concat.debug : No 0
 185 Debug level of the
 186 .Nm CONCAT
 187 GEOM class.
 188 This can be set to a number between 0 and 3 inclusive.
 189 If set to 0 minimal debug information is printed, and if set to 3 the
 190 maximum amount of debug information is printed.
 191 .El
 192 .Sh EXIT STATUS
 193 Exit status is 0 on success, and 1 if the command fails.
 194 .Sh EXAMPLES
 195 The following example shows how to configure four disks for automatic
 196 concatenation, create a file system on it, and mount it:
 197 .Bd -literal -offset indent
 198 gconcat label -v data /dev/da0 /dev/da1 /dev/da2 /dev/da3
 199 newfs /dev/concat/data
 200 mount /dev/concat/data /mnt
 201 [...]
 202 umount /mnt
 203 gconcat stop data
 204 gconcat unload
 205 .Ed
 206 .Pp
 207 Configure concatenated provider on one disk only.
 208 Create file system.
 209 Add two more disks and extend existing file system.
 210 .Bd -literal -offset indent
 211 gconcat label data /dev/da0
 212 newfs /dev/concat/data
 213 gconcat label data /dev/da0 /dev/da1 /dev/da2
 214 growfs /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
 227 The
 228 .Nm
 229 utility appeared in
 230 .Fx 5.3 .
 231 .Sh AUTHORS
 232 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org