sbin/gvinum/gvinum.8

   1 .\"  Copyright (c) 2005 Chris Jones
   2 .\"  All rights reserved.
   3 .\"
   4 .\" This software was developed for the FreeBSD Project by Chris Jones
   5 .\" thanks to the support of Google's Summer of Code program and
   6 .\" mentoring by Lukas Ertl.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 23, 2006
  32 .Dt GVINUM 8
  33 .Os
  34 .Sh NAME
  35 .Nm gvinum
  36 .Nd Logical Volume Manager control program
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Ar command
  40 .Op Fl options
  41 .Sh COMMANDS
  42 .Bl -tag -width indent
  43 .It Ic checkparity Oo Fl f Oc Ar plex
  44 Check the parity blocks of a RAID-5 plex.
  45 The parity check will start at the
  46 beginning of the plex if the
  47 .Fl f
  48 flag is specified, or otherwise at the location of the parity check pointer,
  49 the first location at which plex's parity is incorrect.
  50 All subdisks in the
  51 plex must be up for a parity check.
  52 .It Ic create Op Ar description-file
  53 Create a volume as described in
  54 .Ar description-file .
  55 If no
  56 .Ar description-file
  57 provided, opens an editor and provides the current
  58 .Nm
  59 configuration for editing.
  60 .It Ic help
  61 Provides a synopsis of
  62 .Nm
  63 commands and arguments.
  64 .It Ic l | list Oo Fl rvV Oc Op Ar volume | plex | subdisk
  65 .It Ic ld Oo Fl rvV Oc Op Ar drive ...
  66 .It Ic ls Oo Fl rvV Oc Op Ar subdisk ...
  67 .It Ic lp Oo Fl rvV Oc Op Ar plex ...
  68 .It Ic lv Oo Fl rvV Oc Op Ar volume ...
  69 List information about the relevant object(s).
  70 The
  71 .Fl r
  72 flag provides recursive display, showing each object's subordinate objects in
  73 proper relation.
  74 The
  75 .Fl v
  76 and
  77 .Fl V
  78 flags provide progressively more detailed output.
  79 .It Ic move | mv Fl f Ar drive subdisk Op Ar ...
  80 Move the subdisk(s) to the specified drive.
  81 The
  82 .Fl f
  83 flag is required, as all data on the indicated subdisk(s) will be destroyed as
  84 part of the move.
  85 This can currently only be done when the subdisk is
  86 not being accessed.
  87 .Pp
  88 If the subdisk(s) form part of a RAID-5 plex, the disk(s) will need to be set
  89 to the
  90 .Dq up
  91 state and the plex will require a
  92 .Ic rebuildparity
  93 command; if the subdisk(s) form part of a plex that is mirrored with other
  94 plexes, the plex will require restarting and will sync once restarted.
  95 Moving
  96 more than one subdisk in a RAID-5 plex or subdisks from both sides of a
  97 mirrored plex volume will destroy data.
  98 Note that parity rebuilds and syncing
  99 must be started manually after a move.
 100 .It Ic printconfig
 101 Write a copy of the current configuration to standard output.
 102 .It Ic quit
 103 Exit
 104 .Nm
 105 when running in interactive mode.
 106 Normally this would be done by entering the
 107 EOF character.
 108 .It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname
 109 Change the name of the specified object.
 110 The
 111 .Fl r
 112 flag will recursively rename subordinate objects.
 113 .Pp
 114 Note that device nodes will not be renamed until
 115 .Nm
 116 is restarted.
 117 .It Ic rebuildparity Oo Fl f Oc Ar plex
 118 Rebuild the parity blocks of a RAID-5 plex.
 119 The parity rebuild will start at
 120 the beginning of the plex if the
 121 .Fl f
 122 flag is specified, or otherwise at the location of the parity check pointer.
 123 All subdisks in the plex must be up for a parity check.
 124 .It Ic resetconfig
 125 Reset the complete
 126 .Nm
 127 configuration.
 128 .It Ic rm Oo Fl r Oc Ar volume | plex | subdisk
 129 Remove an object and, if
 130 .Fl r
 131 is specified, its subordinate objects.
 132 .It Ic saveconfig
 133 Save
 134 .Nm
 135 configuration to disk after configuration failures.
 136 .It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive
 137 Set state without influencing other objects, for diagnostic purposes
 138 only.
 139 The
 140 .Fl f
 141 flag forces state changes regardless of whether they are legal.
 142 .It Ic start
 143 Read configuration from all vinum drives.
 144 .It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk
 145 Allow the system to access the objects.
 146 The
 147 .Fl S
 148 flag is currently ignored.
 149 .El
 150 .Sh DESCRIPTION
 151 The
 152 .Nm
 153 utility communicates with the kernel component of the GVinum logical volume
 154 manager.
 155 It is designed either for interactive use, when started without
 156 command line arguments, or to execute a single command if the command is
 157 supplied on the command line.
 158 In interactive mode,
 159 .Nm
 160 maintains a command line history.
 161 .Sh OPTIONS
 162 The
 163 .Nm
 164 commands may be followed by an option.
 165 .Bl -tag -width indent
 166 .It Fl f
 167 The
 168 .Fl f
 169 .Pq Dq force
 170 option overrides safety checks.
 171 It should be used with extreme caution.
 172 This
 173 option is required in order to use the
 174 .Ic move
 175 command.
 176 .It Fl r
 177 The
 178 .Fl r
 179 .Pq Dq recursive
 180 option applies the command recursively to subordinate objects.
 181 For example, in
 182 conjunction with the
 183 .Ic lv
 184 command, the
 185 .Fl r
 186 option will also show information about the plexes and subdisks belonging to
 187 the volume.
 188 It is also used by the
 189 .Ic rename
 190 command to indicate that subordinate objects such as subdisks should be renamed
 191 to match the object(s) specified and by the
 192 .Ic rm
 193 command to delete plexes belonging to a volume and so on.
 194 .It Fl v
 195 The
 196 .Fl v
 197 .Pq Dq verbose
 198 option provides more detailed output.
 199 .It Fl V
 200 The
 201 .Fl V
 202 .Pq Dq "very verbose"
 203 option provides even more detailed output than
 204 .Fl v .
 205 .El
 206 .Sh ENVIRONMENT
 207 .Bl -tag -width ".Ev EDITOR"
 208 .It Ev EDITOR
 209 The name of the editor to use for editing configuration files, by
 210 default
 211 .Xr vi 1
 212 is invoked.
 213 .El
 214 .Sh FILES
 215 .Bl -tag -width ".Pa /dev/gvinum/plex"
 216 .It Pa /dev/gvinum
 217 directory with device nodes for
 218 .Nm
 219 objects
 220 .It Pa /dev/gvinum/plex
 221 directory containing device nodes for
 222 .Nm
 223 plexes
 224 .It Pa /dev/gvinum/sd
 225 directory containing device nodes for
 226 .Nm
 227 subdisks
 228 .El
 229 .Sh SEE ALSO
 230 .Xr geom 4 ,
 231 .Xr geom 8
 232 .Sh HISTORY
 233 The
 234 .Nm
 235 utility first appeared in
 236 .Fx 5.3 .
 237 The
 238 .Nm vinum
 239 utility, on which
 240 .Nm
 241 is based, was written by
 242 .An "Greg Lehey" .
 243 .Pp
 244 The
 245 .Nm
 246 utility
 247 was written by
 248 .An "Lukas Ertl" .
 249 The
 250 .Ic move
 251 and
 252 .Ic rename
 253 commands and
 254 documentation were added by
 255 .An "Chris Jones"
 256 through the 2005 Google Summer
 257 of Code program.
 258 .Sh AUTHORS
 259 .An Lukas Ertl Aq le@FreeBSD.org
 260 .An Chris Jones Aq soc-cjones@FreeBSD.org
 261 .Sh BUGS
 262 Currently,
 263 .Nm
 264 does not rename devices in
 265 .Pa /dev/gvinum
 266 until reloaded.
 267 .Pp
 268 The
 269 .Fl S
 270 initsize flag to
 271 .Ic start
 272 is ignored.
 273 .Pp
 274 The
 275 .Ic stop
 276 command does not work.
 277 .Pp
 278 Moving subdisks that are not part of a mirrored or RAID-5 volume will
 279 destroy data.
 280 It is perhaps a bug to permit this.
 281 .Pp
 282 Plexes in which subdisks have been moved do not automatically sync or
 283 rebuild parity.
 284 This may leave data unprotected and is perhaps unwise.
 285 .Pp
 286 Currently,
 287 .Nm
 288 does not yet fully implement all of the functions found in
 289 .Xr vinum 4 .
 290 Specifically, the following commands from
 291 .Xr vinum 4
 292 are not supported:
 293 .Bl -tag -width indent
 294 .It Ic attach Ar plex volume Op Cm rename
 295 .It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename
 296 Attach a plex to a volume, or a subdisk to a plex.
 297 .It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
 298 Create a concatenated volume from the specified drives.
 299 .It Ic debug
 300 Cause the volume manager to enter the kernel debugger.
 301 .It Ic debug Ar flags
 302 Set debugging flags.
 303 .It Ic detach Oo Fl f Oc Op Ar plex | subdisk
 304 Detach a plex or subdisk from the volume or plex to which it is
 305 attached.
 306 .It Ic dumpconfig Op Ar drive ...
 307 List the configuration information stored on the specified drives, or all
 308 drives in the system if no drive names are specified.
 309 .It Ic info Op Fl vV
 310 List information about volume manager state.
 311 .It Ic label Ar volume
 312 Create a volume label.
 313 .It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives
 314 Create a mirrored volume from the specified drives.
 315 .It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk
 316 Reset statistics counters for the specified objects, or for all objects if none
 317 are specified.
 318 .It Ic setdaemon Op Ar value
 319 Set daemon configuration.
 320 .It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk
 321 Terminate access to the objects, or stop
 322 .Nm
 323 if no parameters are specified.
 324 .It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
 325 Create a striped volume from the specified drives.
 326 .El