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