File:  [DragonFly] / src / share / man / man4 / vinum.4
Revision 1.3: download - view: text, annotated - select for diffs
Wed Nov 19 00:51:38 2003 UTC (11 years ago) by dillon
Branches: MAIN
CVS tags: HEAD
Change the system name from 'FreeBSD' to 'DragonFly'.  We are now officially
DragonFly 1.0-CURRENT.  The change is fairly straight forward but involves
adding support for the 'DragonFly' OS type in various gnu contributed pieces
(typically configure based), as well as compiler and BFD support for building
GCC and friends (basically just copied the FreeBSD files for DragonFly).

Additionally, hack the ports makefiles with UNAME_xxx environment variables
so ports builds think its still a FreeBSD-4.8 system.  Otherwise most of the
ports will fail.

    1: .\"  Hey, Emacs, edit this file in -*- nroff-fill -*- mode
    2: .\"-
    3: .\" Copyright (c) 1997, 1998
    4: .\"	Nan Yang Computer Services Limited.  All rights reserved.
    5: .\"
    6: .\"  This software is distributed under the so-called ``Berkeley
    7: .\"  License'':
    8: .\"
    9: .\" Redistribution and use in source and binary forms, with or without
   10: .\" modification, are permitted provided that the following conditions
   11: .\" are met:
   12: .\" 1. Redistributions of source code must retain the above copyright
   13: .\"    notice, this list of conditions and the following disclaimer.
   14: .\" 2. Redistributions in binary form must reproduce the above copyright
   15: .\"    notice, this list of conditions and the following disclaimer in the
   16: .\"    documentation and/or other materials provided with the distribution.
   17: .\" 3. All advertising materials mentioning features or use of this software
   18: .\"    must display the following acknowledgement:
   19: .\"	This product includes software developed by Nan Yang Computer
   20: .\"      Services Limited.
   21: .\" 4. Neither the name of the Company nor the names of its contributors
   22: .\"    may be used to endorse or promote products derived from this software
   23: .\"    without specific prior written permission.
   24: .\"
   25: .\" This software is provided ``as is'', and any express or implied
   26: .\" warranties, including, but not limited to, the implied warranties of
   27: .\" merchantability and fitness for a particular purpose are disclaimed.
   28: .\" In no event shall the company or contributors be liable for any
   29: .\" direct, indirect, incidental, special, exemplary, or consequential
   30: .\" damages (including, but not limited to, procurement of substitute
   31: .\" goods or services; loss of use, data, or profits; or business
   32: .\" interruption) however caused and on any theory of liability, whether
   33: .\" in contract, strict liability, or tort (including negligence or
   34: .\" otherwise) arising in any way out of the use of this software, even if
   35: .\" advised of the possibility of such damage.
   36: .\"
   37: .\" $FreeBSD: src/share/man/man4/vinum.4,v 1.22.2.9 2002/04/22 08:19:35 kuriyama Exp $
   38: .\" $DragonFly: src/share/man/man4/vinum.4,v 1.3 2003/11/19 00:51:38 dillon Exp $
   39: .\"
   40: .Dd October 5, 1999
   41: .Dt vinum 4
   42: .Os
   43: .Sh NAME
   44: .Nm vinum
   45: .Nd Logical Volume Manager
   46: .Sh SYNOPSIS
   47: .Cd "kldload vinum"
   48: .Cd "kldload Vinum"
   49: .Sh DESCRIPTION
   50: .Nm
   51: is a logical volume manager inspired by, but not derived from, the Veritas
   52: Volume Manager.  It provides the following features:
   53: .Bl -bullet
   54: .It
   55: It provides device-independent logical disks, called \fIvolumes\fP.  Volumes are
   56: not restricted to the size of any disk on the system.
   57: .It
   58: The volumes consist of one or more \fIplexes\fP, each of which contain the
   59: entire address space of a volume.  This represents an implementation of RAID-1
   60: (mirroring).  Multiple plexes can also be used for
   61: .\" XXX What about sparse plexes?  Do we want them?
   62: .if t .sp
   63: .Bl -bullet
   64: .It
   65: Increased read throughput.
   66: .Nm
   67: will read data from the least active disk, so if a volume has plexes on multiple
   68: disks, more data can be read in parallel.
   69: .Nm
   70: reads data from only one plex, but it writes data to all plexes.
   71: .It
   72: Increased reliability.  By storing plexes on different disks, data will remain
   73: available even if one of the plexes becomes unavailable.  In comparison with a
   74: RAID-5 plex (see below), using multiple plexes requires more storage space, but
   75: gives better performance, particularly in the case of a drive failure.
   76: .It
   77: Additional plexes can be used for on-line data reorganization.  By attaching an
   78: additional plex and subsequently detaching one of the older plexes, data can be
   79: moved on-line without compromising access.
   80: .It
   81: An additional plex can be used to obtain a consistent dump of a file system.  By
   82: attaching an additional plex and detaching at a specific time, the detached plex
   83: becomes an accurate snapshot of the file system at the time of detachment.
   84: .\" Make sure to flush!
   85: .El
   86: .It
   87: Each plex consists of one or more logical disk slices, called \fIsubdisks\fP.
   88: Subdisks are defined as a contiguous block of physical disk storage.  A plex may
   89: consist of any reasonable number of subdisks (in other words, the real limit is
   90: not the number, but other factors, such as memory and performance, associated
   91: with maintaining a large number of subdisks).
   92: .It
   93: A number of mappings between subdisks and plexes are available:
   94: .Bl -bullet
   95: .It
   96: \fIConcatenated plexes\fP\| consist of one or more subdisks, each of which
   97: is mapped to a contiguous part of the plex address space.
   98: .It
   99: \fIStriped plexes\fP\| consist of two or more subdisks of equal size.  The file
  100: address space is mapped in \fIstripes\fP, integral fractions of the subdisk
  101: size.  Consecutive plex address space is mapped to stripes in each subdisk in
  102: .if n turn.
  103: .if t \{\
  104: turn.
  105: .ig
  106: .\" FIXME
  107: .br
  108: .ne 1.5i
  109: .PS
  110: move right 2i
  111: down
  112: SD0: box
  113: SD1: box
  114: SD2: box
  115: 
  116: "plex 0" at SD0.n+(0,.2)
  117: "subdisk 0" rjust at SD0.w-(.2,0)
  118: "subdisk 1" rjust at SD1.w-(.2,0)
  119: "subdisk 2" rjust at SD2.w-(.2,0)
  120: .PE
  121: ..
  122: .\}
  123: The subdisks of a striped plex must all be the same size.
  124: .It
  125: \fIRAID-5 plexes\fP\| require at least three equal-sized subdisks.  They
  126: resemble striped plexes, except that in each stripe, one subdisk stores parity
  127: information.  This subdisk changes in each stripe: in the first stripe, it is the
  128: first subdisk, in the second it is the second subdisk, etc.  In the event of a
  129: single disk failure,
  130: .Nm
  131: will recover the data based on the information stored on the remaining subdisks.
  132: This mapping is particularly suited to read-intensive access.  The subdisks of a
  133: RAID-5 plex must all be the same size.
  134: .\" Make sure to flush!
  135: .El
  136: .It
  137: .Nm Drives
  138: are the lowest level of the storage hierarchy.  They represent disk special
  139: devices.
  140: .It
  141: .Nm
  142: offers automatic startup.  Unlike UNIX file systems,
  143: .Nm
  144: volumes contain all the configuration information needed to ensure that they are
  145: started correctly when the subsystem is enabled.  This is also a significant
  146: advantage over the Veritas\(tm File System.  This feature regards the presence
  147: of the volumes.  It does not mean that the volumes will be mounted
  148: automatically, since the standard startup procedures with
  149: .Pa /etc/fstab
  150: perform this function.
  151: .El
  152: .Sh KERNEL CONFIGURATION
  153: .Nm
  154: is currently supplied as a kernel loadable module (kld), and does not require
  155: configuration.  As with other klds, it is absolutely necessary to match the kld
  156: to the version of the operating system.  Failure to do so will cause
  157: .Nm
  158: to issue an error message and terminate.
  159: .Pp
  160: It is possible to configure
  161: .Nm
  162: in the kernel, but this is not recommended.  To do so, add this line to the
  163: kernel configuration file:
  164: .Bd -literal -offset indent
  165: pseudo-device	vinum
  166: .Ed
  167: .Pp
  168: .Ss DEBUG OPTIONS
  169: The current version of
  170: .Nm ,
  171: both the kernel module and the user program
  172: .Xr vinum 8 ,
  173: include significant debugging support.  It is not recommended to remove
  174: this support at the moment, but if you do you must remove it from both the
  175: kernel and the user components.  To do this, edit the files
  176: .Pa /usr/src/sbin/vinum/Makefile
  177: and
  178: .Pa /usr/src/sys/modules/vinum/Makefile
  179: and edit the CFLAGS variable to remove the -DVINUMDEBUG option.  If you have
  180: configured
  181: .Nm
  182: into the kernel, either specify the line
  183: .Bd -literal -offset indent
  184: options		VINUMDEBUG
  185: .Ed
  186: .Pp
  187: in the kernel configuration file or remove the -DVINUMDEBUG option from
  188: .Pa /usr/src/sbin/vinum/Makefile
  189: as described above.
  190: .Pp
  191: If the VINUMDEBUG variables do not match,
  192: .Xr vinum 8
  193: will fail with a message
  194: explaining the problem and what to do to correct it.
  195: .Pp
  196: .Nm
  197: was previously available in two versions: a freely available version which did
  198: not contain RAID-5 functionality, and a full version including RAID-5
  199: functionality, which was available only from Cybernet Systems Inc.  The present
  200: version of
  201: .Nm
  202: includes the RAID-5 functionality.
  203: .Sh RUNNING VINUM
  204: .Nm
  205: is part of the base
  206: .Fx
  207: system.  It does not require installation.
  208: To start it, start the
  209: .Nm
  210: program, which will load the kld if it is not already present.
  211: Before using
  212: .Nm ,
  213: it must be configured.  See
  214: .Xr vinum 8
  215: for information on how to create a
  216: .Nm
  217: configuration.
  218: .Pp
  219: Normally, you start a configured version of
  220: .Nm
  221: at boot time.  Set the variable
  222: .Ar start_vinum
  223: in
  224: .Pa /etc/rc.conf
  225: to
  226: .Ar YES
  227: to start
  228: .Nm
  229: at boot time.
  230: .Pp
  231: If
  232: .Nm
  233: is loaded as a kld (the recommended way), the
  234: .Nm
  235: .Ar stop
  236: command will unload it.  You can also do this with the
  237: .Nm kldunload
  238: command.
  239: .Pp
  240: The kld can only be unloaded when idle, in other words when no volumes are
  241: mounted and no other instances of the
  242: .Nm
  243: program are active.  Unloading the kld does not harm the data in the volumes.
  244: .Ss CONFIGURING AND STARTING OBJECTS
  245: Use the
  246: .Xr vinum 8
  247: utility to configure and start
  248: .Nm
  249: objects.
  250: .Sh IOCTL CALLS
  251: .Pa ioctl
  252: calls are intended for the use of the
  253: .Nm
  254: configuration program only.  They are described in the header file
  255: .Pa /sys/sys/vinumio.h
  256: .Ss DISK LABELS
  257: Conventional disk special devices have a
  258: .Em disk label
  259: in the second sector of the device.  See
  260: .Xr disklabel 5
  261: for more details.  This disk label describes the layout of the partitions within
  262: the device.
  263: .Nm
  264: does not subdivide volumes, so volumes do not contain a physical disk label.
  265: For convenience,
  266: .Nm
  267: implements the ioctl calls DIOCGDINFO (get disk label), DIOCGPART (get partition
  268: information), DIOCWDINFO (write partition information) and DIOCSDINFO (set
  269: partition information).  DIOCGDINFO and DIOCGPART refer to an internal
  270: representation of the disk label which is not present on the volume.  As a
  271: result, the
  272: .Fl r
  273: option of
  274: .Xr disklabel 8 ,
  275: which reads the
  276: .if t ``raw disk'',
  277: .if n "raw disk",
  278: will fail.
  279: .Pp
  280: In general,
  281: .Xr disklabel 8
  282: serves no useful purpose on a vinum volume.  If you run it, it will show you
  283: three partitions, a, b and c, all the same except for the fstype, for example:
  284: .br
  285: .ne 1i
  286: .Bd -literal -offset
  287: 3 partitions:
  288: #        size   offset    fstype   [fsize bsize bps/cpg]
  289:   a:     2048        0    4.2BSD     1024  8192     0   # (Cyl.    0 - 0)
  290:   b:     2048        0      swap                        # (Cyl.    0 - 0)
  291:   c:     2048        0    unused        0     0         # (Cyl.    0 - 0)
  292: .Ed
  293: .Pp
  294: .Nm
  295: ignores the DIOCWDINFO and DIOCSDINFO ioctls, since there is nothing to change.
  296: As a result, any attempt to modify the disk label will be silently ignored.
  297: .Sh MAKING FILE SYSTEMS
  298: Since
  299: .Nm
  300: volumes do not contain partitions, the names do not need to conform to the
  301: standard rules for naming disk partitions.  For a physical disk partition, the
  302: last letter of the device name specifies the partition identifier (a to h).
  303: .Nm
  304: volumes need not conform to this convention, but if they do not,
  305: .Nm newfs
  306: will complain that it cannot determine the partition.  To solve this problem,
  307: use the
  308: .Fl v
  309: flag to
  310: .Nm newfs .
  311: For example, if you have a volume
  312: .Pa concat ,
  313: use the following command to create a ufs file system on it:
  314: .Pp
  315: .Bd -literal
  316:   # newfs -v /dev/vinum/concat
  317: .Ed
  318: .Pp
  319: .Sh OBJECT NAMING
  320: .Nm
  321: assigns default names to plexes and subdisks, although they may be overridden.
  322: We do not recommend overriding the default names.  Experience with the
  323: .if t Veritas\(tm
  324: .if n Veritas(tm)
  325: volume manager, which allows arbitary naming of objects, has shown that this
  326: flexibility does not bring a significant advantage, and it can cause confusion.
  327: .sp
  328: Names may contain any non-blank character, but it is recommended to restrict
  329: them to letters, digits and the underscore characters.  The names of volumes,
  330: plexes and subdisks may be up to 64 characters long, and the names of drives may
  331: up to 32 characters long.  When choosing volume and plex names, bear in mind
  332: that automatically generated plex and subdisk names are longer than the name
  333: from which they are derived.
  334: .Bl -bullet
  335: .It
  336: When
  337: .Xr vinum 8
  338: creates or deletes objects, it creates a directory
  339: .Pa /dev/vinum ,
  340: in which it makes device entries for each volume.  It also creates the
  341: subdirectories
  342: .Pa /dev/vinum/plex
  343: and
  344: .Pa /dev/vinum/sd ,
  345: in which it stores device entries for the plexes and subdisks.  In addition, it
  346: creates two more directories,
  347: .Pa /dev/vinum/vol
  348: and
  349: .Pa /dev/vinum/drive ,
  350: in which it stores hierarchical information for volumes and drives.
  351: .It
  352: In addition,
  353: .Nm
  354: creates three super-devices,
  355: .Pa /dev/vinum/control ,
  356: .Pa /dev/vinum/Control
  357: and
  358: .Pa /dev/vinum/controld .
  359: .Pa /dev/vinum/control
  360: is used by
  361: .Xr vinum 8
  362: when it has been compiled without the VINUMDEBUG option,
  363: .Pa /dev/vinum/Control
  364: is used by
  365: .Xr vinum 8
  366: when it has been compiled with the VINUMDEBUG option,
  367: and
  368: .Pa /dev/vinum/controld
  369: is used by the
  370: .Nm
  371: daemon.  The two control devices for
  372: .Xr vinum 8
  373: are used to synchronize the debug status of kernel and user modules.
  374: .It
  375: Unlike
  376: .Nm UNIX
  377: drives,
  378: .Nm
  379: volumes are not subdivided into partitions, and thus do not contain a disk
  380: label.  Unfortunately, this confuses a number of utilities, notably
  381: .Nm newfs ,
  382: which normally tries to interpret the last letter of a
  383: .Nm
  384: volume name as a partition identifier.  If you use a volume name which does not
  385: end in the letters
  386: .Ar a
  387: to
  388: .Ar c ,
  389: you must use the
  390: .Fl v
  391: flag to
  392: .Nm newfs
  393: in order to tell it to ignore this convention.
  394: .\"
  395: .It
  396: Plexes do not need to be assigned explicit names.  By default, a plex name is
  397: the name of the volume followed by the letters \f(CW.p\fR and the number of the
  398: plex.  For example, the plexes of volume
  399: .Ar vol3
  400: are called
  401: .Ar vol3.p0 ,
  402: .Ar vol3.p1
  403: and so on.  These names can be overridden, but it is not recommended.
  404: .br
  405: .It
  406: Like plexes, subdisks are assigned names automatically, and explicit naming is
  407: discouraged.  A subdisk name is the name of the plex followed by the letters
  408: \f(CW\&.s\fR and a number identifying the subdisk.  For example, the subdisks of
  409: plex
  410: .Ar vol3.p0
  411: are called
  412: .Ar vol3.p0.s0 ,
  413: .Ar vol3.p0.s1
  414: and so on.
  415: .br
  416: .It
  417: By contrast,
  418: .Nm drives
  419: must be named.  This makes it possible to move a drive to a different location
  420: and still recognize it automatically.  Drive names may be up to 32 characters
  421: long.
  422: .El
  423: .Pp
  424: EXAMPLE
  425: .Pp
  426: Assume the
  427: .Nm
  428: objects described in the section CONFIGURATION FILE in
  429: .Xr vinum 8 .
  430: The directory
  431: .Ar /dev/vinum
  432: looks like:
  433: .Bd -literal -offset indent
  434: # ls -lR /dev/vinum
  435: total 5
  436: crwxr-xr--  1 root  wheel   91,   2 Mar 30 16:08 concat
  437: crwx------  1 root  wheel   91, 0x40000000 Mar 30 16:08 control
  438: crwx------  1 root  wheel   91, 0x40000001 Mar 30 16:08 controld
  439: drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 drive
  440: drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 plex
  441: drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 rvol
  442: drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 sd
  443: crwxr-xr--  1 root  wheel   91,   3 Mar 30 16:08 strcon
  444: crwxr-xr--  1 root  wheel   91,   1 Mar 30 16:08 stripe
  445: crwxr-xr--  1 root  wheel   91,   0 Mar 30 16:08 tinyvol
  446: drwxrwxrwx  7 root  wheel       512 Mar 30 16:08 vol
  447: crwxr-xr--  1 root  wheel   91,   4 Mar 30 16:08 vol5
  448: 
  449: /dev/vinum/drive:
  450: total 0
  451: crw-r-----  1 root  operator    4,  15 Oct 21 16:51 drive2
  452: crw-r-----  1 root  operator    4,  31 Oct 21 16:51 drive4
  453: 
  454: /dev/vinum/plex:
  455: total 0
  456: crwxr-xr--  1 root  wheel   91, 0x10000002 Mar 30 16:08 concat.p0
  457: crwxr-xr--  1 root  wheel   91, 0x10010002 Mar 30 16:08 concat.p1
  458: crwxr-xr--  1 root  wheel   91, 0x10000003 Mar 30 16:08 strcon.p0
  459: crwxr-xr--  1 root  wheel   91, 0x10010003 Mar 30 16:08 strcon.p1
  460: crwxr-xr--  1 root  wheel   91, 0x10000001 Mar 30 16:08 stripe.p0
  461: crwxr-xr--  1 root  wheel   91, 0x10000000 Mar 30 16:08 tinyvol.p0
  462: crwxr-xr--  1 root  wheel   91, 0x10000004 Mar 30 16:08 vol5.p0
  463: crwxr-xr--  1 root  wheel   91, 0x10010004 Mar 30 16:08 vol5.p1
  464: 
  465: /dev/vinum/sd:
  466: total 0
  467: crwxr-xr--  1 root  wheel   91, 0x20000002 Mar 30 16:08 concat.p0.s0
  468: crwxr-xr--  1 root  wheel   91, 0x20100002 Mar 30 16:08 concat.p0.s1
  469: crwxr-xr--  1 root  wheel   91, 0x20010002 Mar 30 16:08 concat.p1.s0
  470: crwxr-xr--  1 root  wheel   91, 0x20000003 Mar 30 16:08 strcon.p0.s0
  471: crwxr-xr--  1 root  wheel   91, 0x20100003 Mar 30 16:08 strcon.p0.s1
  472: crwxr-xr--  1 root  wheel   91, 0x20010003 Mar 30 16:08 strcon.p1.s0
  473: crwxr-xr--  1 root  wheel   91, 0x20110003 Mar 30 16:08 strcon.p1.s1
  474: crwxr-xr--  1 root  wheel   91, 0x20000001 Mar 30 16:08 stripe.p0.s0
  475: crwxr-xr--  1 root  wheel   91, 0x20100001 Mar 30 16:08 stripe.p0.s1
  476: crwxr-xr--  1 root  wheel   91, 0x20000000 Mar 30 16:08 tinyvol.p0.s0
  477: crwxr-xr--  1 root  wheel   91, 0x20100000 Mar 30 16:08 tinyvol.p0.s1
  478: crwxr-xr--  1 root  wheel   91, 0x20000004 Mar 30 16:08 vol5.p0.s0
  479: crwxr-xr--  1 root  wheel   91, 0x20100004 Mar 30 16:08 vol5.p0.s1
  480: crwxr-xr--  1 root  wheel   91, 0x20010004 Mar 30 16:08 vol5.p1.s0
  481: crwxr-xr--  1 root  wheel   91, 0x20110004 Mar 30 16:08 vol5.p1.s1
  482: 
  483: /dev/vinum/vol:
  484: total 5
  485: crwxr-xr--  1 root  wheel   91,   2 Mar 30 16:08 concat
  486: drwxr-xr-x  4 root  wheel       512 Mar 30 16:08 concat.plex
  487: crwxr-xr--  1 root  wheel   91,   3 Mar 30 16:08 strcon
  488: drwxr-xr-x  4 root  wheel       512 Mar 30 16:08 strcon.plex
  489: crwxr-xr--  1 root  wheel   91,   1 Mar 30 16:08 stripe
  490: drwxr-xr-x  3 root  wheel       512 Mar 30 16:08 stripe.plex
  491: crwxr-xr--  1 root  wheel   91,   0 Mar 30 16:08 tinyvol
  492: drwxr-xr-x  3 root  wheel       512 Mar 30 16:08 tinyvol.plex
  493: crwxr-xr--  1 root  wheel   91,   4 Mar 30 16:08 vol5
  494: drwxr-xr-x  4 root  wheel       512 Mar 30 16:08 vol5.plex
  495: 
  496: /dev/vinum/vol/concat.plex:
  497: total 2
  498: crwxr-xr--  1 root  wheel   91, 0x10000002 Mar 30 16:08 concat.p0
  499: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 concat.p0.sd
  500: crwxr-xr--  1 root  wheel   91, 0x10010002 Mar 30 16:08 concat.p1
  501: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 concat.p1.sd
  502: 
  503: /dev/vinum/vol/concat.plex/concat.p0.sd:
  504: total 0
  505: crwxr-xr--  1 root  wheel   91, 0x20000002 Mar 30 16:08 concat.p0.s0
  506: crwxr-xr--  1 root  wheel   91, 0x20100002 Mar 30 16:08 concat.p0.s1
  507: 
  508: /dev/vinum/vol/concat.plex/concat.p1.sd:
  509: total 0
  510: crwxr-xr--  1 root  wheel   91, 0x20010002 Mar 30 16:08 concat.p1.s0
  511: 
  512: /dev/vinum/vol/strcon.plex:
  513: total 2
  514: crwxr-xr--  1 root  wheel   91, 0x10000003 Mar 30 16:08 strcon.p0
  515: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 strcon.p0.sd
  516: crwxr-xr--  1 root  wheel   91, 0x10010003 Mar 30 16:08 strcon.p1
  517: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 strcon.p1.sd
  518: 
  519: /dev/vinum/vol/strcon.plex/strcon.p0.sd:
  520: total 0
  521: crwxr-xr--  1 root  wheel   91, 0x20000003 Mar 30 16:08 strcon.p0.s0
  522: crwxr-xr--  1 root  wheel   91, 0x20100003 Mar 30 16:08 strcon.p0.s1
  523: 
  524: /dev/vinum/vol/strcon.plex/strcon.p1.sd:
  525: total 0
  526: crwxr-xr--  1 root  wheel   91, 0x20010003 Mar 30 16:08 strcon.p1.s0
  527: crwxr-xr--  1 root  wheel   91, 0x20110003 Mar 30 16:08 strcon.p1.s1
  528: 
  529: /dev/vinum/vol/stripe.plex:
  530: total 1
  531: crwxr-xr--  1 root  wheel   91, 0x10000001 Mar 30 16:08 stripe.p0
  532: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 stripe.p0.sd
  533: 
  534: /dev/vinum/vol/stripe.plex/stripe.p0.sd:
  535: total 0
  536: crwxr-xr--  1 root  wheel   91, 0x20000001 Mar 30 16:08 stripe.p0.s0
  537: crwxr-xr--  1 root  wheel   91, 0x20100001 Mar 30 16:08 stripe.p0.s1
  538: 
  539: /dev/vinum/vol/tinyvol.plex:
  540: total 1
  541: crwxr-xr--  1 root  wheel   91, 0x10000000 Mar 30 16:08 tinyvol.p0
  542: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 tinyvol.p0.sd
  543: 
  544: /dev/vinum/vol/tinyvol.plex/tinyvol.p0.sd:
  545: total 0
  546: crwxr-xr--  1 root  wheel   91, 0x20000000 Mar 30 16:08 tinyvol.p0.s0
  547: crwxr-xr--  1 root  wheel   91, 0x20100000 Mar 30 16:08 tinyvol.p0.s1
  548: 
  549: /dev/vinum/vol/vol5.plex:
  550: total 2
  551: crwxr-xr--  1 root  wheel   91, 0x10000004 Mar 30 16:08 vol5.p0
  552: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 vol5.p0.sd
  553: crwxr-xr--  1 root  wheel   91, 0x10010004 Mar 30 16:08 vol5.p1
  554: drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 vol5.p1.sd
  555: 
  556: /dev/vinum/vol/vol5.plex/vol5.p0.sd:
  557: total 0
  558: crwxr-xr--  1 root  wheel   91, 0x20000004 Mar 30 16:08 vol5.p0.s0
  559: crwxr-xr--  1 root  wheel   91, 0x20100004 Mar 30 16:08 vol5.p0.s1
  560: 
  561: /dev/vinum/vol/vol5.plex/vol5.p1.sd:
  562: total 0
  563: crwxr-xr--  1 root  wheel   91, 0x20010004 Mar 30 16:08 vol5.p1.s0
  564: crwxr-xr--  1 root  wheel   91, 0x20110004 Mar 30 16:08 vol5.p1.s1
  565: .Ed
  566: .Pp
  567: In the case of unattached plexes and subdisks, the naming is reversed.  Subdisks
  568: are named after the disk on which they are located, and plexes are named after
  569: the subdisk.
  570: .\" XXX
  571: .Nm This mapping is still to be determined.
  572: .Ss OBJECT STATES
  573: .Pp
  574: Each
  575: .Nm
  576: object has a \fIstate\fR associated with it.
  577: .Nm
  578: uses this state to determine the handling of the object.
  579: .Pp
  580: .Ss VOLUME STATES
  581: Volumes may have the following states:
  582: .sp
  583: .Bl -hang -width 14n
  584: .It Li down
  585: The volume is completely inaccessible.
  586: .It Li up
  587: The volume is up and at least partially functional.  Not all plexes may be
  588: available.
  589: .El
  590: .Ss "PLEX STATES"
  591: Plexes may have the following states:
  592: .sp
  593: .ne 1i
  594: .Bl -hang -width 14n
  595: .It Li referenced
  596: A plex entry which has been referenced as part of a volume, but which is
  597: currently not known.
  598: .It Li faulty
  599: A plex which has gone completely down because of I/O errors.
  600: .It Li down
  601: A plex which has been taken down by the administrator.
  602: .It Li initializing
  603: A plex which is being initialized.
  604: .sp
  605: The remaining states represent plexes which are at least partially up.
  606: .It Li corrupt
  607: A plex entry which is at least partially up.  Not all subdisks are available,
  608: and an inconsistency has occurred.  If no other plex is uncorrupted, the volume
  609: is no longer consistent.
  610: .It Li degraded
  611: A RAID-5 plex entry which is accessible, but one subdisk is down, requiring
  612: recovery for many I/O requests.
  613: .It Li flaky
  614: A plex which is really up, but which has a reborn subdisk which we don't
  615: completely trust, and which we don't want to read if we can avoid it.
  616: .It Li up
  617: A plex entry which is completely up.  All subdisks are up.
  618: .El
  619: .sp 2v
  620: .Ss "SUBDISK STATES"
  621: Subdisks can have the following states:
  622: .sp
  623: .ne 1i
  624: .Bl -hang -width 14n
  625: .It Li empty
  626: A subdisk entry which has been created completely.  All fields are correct, and
  627: the disk has been updated, but the on the disk is not valid.
  628: .It Li referenced
  629: A subdisk entry which has been referenced as part of a plex, but which is
  630: currently not known.
  631: .It Li initializing
  632: A subdisk entry which has been created completely and which is currently being
  633: initialized.
  634: .sp
  635: The following states represent invalid data.
  636: .It Li obsolete
  637: A subdisk entry which has been created completely.  All fields are correct, the
  638: config on disk has been updated, and the data was valid, but since then the
  639: drive has been taken down, and as a result updates have been missed.
  640: .It Li stale
  641: A subdisk entry which has been created completely.  All fields are correct, the
  642: disk has been updated, and the data was valid, but since then the drive has been
  643: crashed and updates have been lost.
  644: .sp
  645: The following states represent valid, inaccessible data.
  646: .It Li crashed
  647: A subdisk entry which has been created completely.  All fields are correct, the
  648: disk has been updated, and the data was valid, but since then the drive has gone
  649: down.  No attempt has been made to write to the subdisk since the crash, so the
  650: data is valid.
  651: .It Li down
  652: A subdisk entry which was up, which contained valid data, and which was taken
  653: down by the administrator.  The data is valid.
  654: .It Li reviving
  655: The subdisk is currently in the process of being revived.  We can write but not
  656: read.
  657: .sp
  658: The following states represent accessible subdisks with valid data.
  659: .It Li reborn
  660: A subdisk entry which has been created completely.  All fields are correct, the
  661: disk has been updated, and the data was valid, but since then the drive has gone
  662: down and up again.  No updates were lost, but it is possible that the subdisk
  663: has been damaged.  We won't read from this subdisk if we have a choice.  If this
  664: is the only subdisk which covers this address space in the plex, we set its
  665: state to up under these circumstances, so this status implies that there is
  666: another subdisk to fulfil the request.
  667: .It Li up
  668: A subdisk entry which has been created completely.  All fields are correct, the
  669: disk has been updated, and the data is valid.
  670: .El
  671: .sp 2v
  672: .Ss "DRIVE STATES"
  673: Drives can have the following states:
  674: .sp
  675: .ne 1i
  676: .Bl -hang -width 14n
  677: .It Li referenced
  678: At least one subdisk refers to the drive, but it is not currently accessible to
  679: the system.  No device name is known.
  680: .It Li down
  681: The drive is not accessible.
  682: .It Li up
  683: The drive is up and running.
  684: .El
  685: .sp 2v
  686: .Sh BUGS
  687: .Bl -enum
  688: .It
  689: .Nm
  690: is a new product.  Bugs can be expected.  The configuration mechanism is not yet
  691: fully functional.  If you have difficulties, please look at the section
  692: DEBUGGING PROBLEMS WITH VINUM before reporting problems.
  693: .It
  694: Kernels with the
  695: .Nm
  696: pseudo-device appear to work, but are not supported.  If you have trouble with
  697: this configuration, please first replace the kernel with a non-Vinum
  698: kernel and test with the kld module.
  699: .It
  700: Detection of differences between the version of the kernel and the kld is not
  701: yet implemented.
  702: .It
  703: The RAID-5 functionality is new in
  704: .Fx 3.3 .
  705: Some problems have been
  706: reported with
  707: .Nm
  708: in combination with soft updates, but these are not reproducible on all
  709: systems.  If you are planning to use
  710: .Nm
  711: in a production environment, please test carefully.
  712: .El
  713: .Sh DEBUGGING PROBLEMS WITH VINUM
  714: Solving problems with
  715: .Nm
  716: can be a difficult affair.  This section suggests some approaches.
  717: .Ss Configuration problems
  718: .Pp
  719: It is relatively easy (too easy) to run into problems with the
  720: .Nm
  721: configuration.  If you do, the first thing you should do is stop configuration
  722: updates:
  723: .if t .ps -3
  724: .if t .vs -3
  725: .Bd -literal
  726: # \fBvinum setdaemon 4\fP
  727: .Ed
  728: .if t .vs
  729: .if t .ps
  730: .Pp
  731: This will stop updates and any further corruption of the on-disk configuration.
  732: .Pp
  733: Next, look at the on-disk configuration with the
  734: .Nm vinum dumpconfig
  735: command, for example:
  736: .if t .ps -3
  737: .if t .vs -3
  738: .Bd -literal
  739: # \fBvinum dumpconfig\fP
  740: Drive 4:        Device /dev/da3h
  741:                 Created on crash.lemis.com at Sat May 20 16:32:44 2000
  742:                 Config last updated Sat May 20 16:32:56 2000
  743:                 Size:        601052160 bytes (573 MB)
  744: volume obj state up
  745: volume src state up
  746: volume raid state down
  747: volume r state down
  748: volume foo state up
  749: plex name obj.p0 state corrupt org concat vol obj
  750: plex name obj.p1 state corrupt org striped 128b vol obj
  751: plex name src.p0 state corrupt org striped 128b vol src
  752: plex name src.p1 state up org concat vol src
  753: plex name raid.p0 state faulty org disorg vol raid
  754: plex name r.p0 state faulty org disorg vol r
  755: plex name foo.p0 state up org concat vol foo
  756: plex name foo.p1 state faulty org concat vol foo
  757: sd name obj.p0.s0 drive drive2 plex obj.p0 state reborn len 409600b driveoffset 265b plexoffset 0b
  758: sd name obj.p0.s1 drive drive4 plex obj.p0 state up len 409600b driveoffset 265b plexoffset 409600b
  759: sd name obj.p1.s0 drive drive1 plex obj.p1 state up len 204800b driveoffset 265b plexoffset 0b
  760: sd name obj.p1.s1 drive drive2 plex obj.p1 state reborn len 204800b driveoffset 409865b plexoffset 128b
  761: sd name obj.p1.s2 drive drive3 plex obj.p1 state up len 204800b driveoffset 265b plexoffset 256b
  762: sd name obj.p1.s3 drive drive4 plex obj.p1 state up len 204800b driveoffset 409865b plexoffset 384b
  763: .Ed
  764: .if t .vs
  765: .if t .ps
  766: .Pp
  767: The configuration on all disks should be the same.  If this is not the case,
  768: please save the output to a file and report the problem.  There is probably
  769: little that can be done to recover the on-disk configuration, but if you keep a
  770: copy of the files used to create the objects, you should be able to re-create
  771: them.  The
  772: .Cm create
  773: command does not change the subdisk data, so this will not cause data
  774: corruption.  You may need to use the
  775: .Cm resetconfig
  776: command if you have this kind of trouble.
  777: .Ss Kernel Panics
  778: .Pp
  779: In order to analyse a panic which you suspect comes from
  780: .Nm
  781: you will need to build a debug kernel.  See the online handbook at
  782: .Pa /usr/share/doc/en/books/developers-handbook/kerneldebug.html
  783: (if installed) or
  784: .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/kerneldebug.html
  785: for more details of how to do this.
  786: .Pp
  787: Perform the following steps to analyse a
  788: .Nm
  789: problem:
  790: .Bl -enum
  791: .It
  792: Copy the files
  793: .Pa /usr/src/sys/modules/vinum/.gdbinit.crash ,
  794: .Pa /usr/src/sys/modules/vinum/.gdbinit.kernel ,
  795: .Pa /usr/src/sys/modules/vinum/.gdbinit.serial ,
  796: .Pa /usr/src/sys/modules/vinum/.gdbinit.vinum
  797: and
  798: .Pa /usr/src/sys/modules/vinum/.gdbinit.vinum.paths
  799: to the directory in which you will be performing the analysis, typically
  800: .Pa /var/crash .
  801: .It
  802: Make sure that you build the
  803: .Nm
  804: module with debugging information.  The standard
  805: .Pa Makefile
  806: builds a module with debugging symbols by default.  If the version of
  807: .Nm
  808: in
  809: .Pa /modules
  810: does not contain symbols, you will not get an error message, but the stack trace
  811: will not show the symbols.  Check the module before starting
  812: .Nm gdb :
  813: .Bd -literal
  814: $ file /modules/vinum.ko
  815: /modules/vinum.ko: ELF 32-bit LSB shared object, Intel 80386,
  816:   version 1 (FreeBSD), not stripped
  817: .Ed
  818: .Pp
  819: If the output shows that
  820: .Pa /modules/vinum.ko
  821: is stripped, you will have to find a version which is not.  Usually this will be
  822: either in
  823: .Pa /usr/obj/sys/modules/vinum/vinum.ko
  824: (if you have built
  825: .Nm
  826: with a
  827: .Ar make world )
  828: or
  829: .Pa /usr/src/sys/modules/vinum/vinum.ko
  830: (if you have built
  831: .Nm
  832: in this directory).  Modify the file
  833: .Pa .gdbinit.vinum.paths
  834: accordingly.
  835: .It
  836: Either take a dump or use remote serial
  837: .Cm gdb
  838: to analyse the problem.  To analyse a dump, say
  839: .Pa /var/crash/vmcore.5 ,
  840: link
  841: .Pa /var/crash/.gdbinit.crash
  842: to
  843: .Pa /var/crash/.gdbinit
  844: and enter:
  845: .Bd -literal
  846: # cd /var/crash
  847: # gdb -k kernel.debug vmcore.5
  848: .Ed
  849: .Pp
  850: This example assumes that you have installed the correct debug kernel at
  851: .Pa /var/crash/kernel.debug .
  852: If not, substitute the correct name of the debug kernel.
  853: .Pp
  854: To perform remote serial debugging,
  855: link
  856: .Pa /var/crash/.gdbinit.serial
  857: to
  858: .Pa /var/crash/.gdbinit
  859: and enter
  860: .Bd -literal
  861: # cd /var/crash
  862: # gdb -k kernel.debug
  863: .Ed
  864: .Pp
  865: In this case, the
  866: .Pa .gdbinit
  867: file performs the functions necessary to establish connection.  The remote
  868: machine must already be in debug mode: enter the kernel debugger and select
  869: .Nm gdb .
  870: The serial
  871: .Pa .gdbinit
  872: file expects the serial connection to run at 38400 bits per second; if you run
  873: at a different speed, edit the file accordingly (look for the
  874: .Ar remotebaud
  875: specification).
  876: .Pp
  877: The following example shows a remote debugging session using the
  878: .Ar debug
  879: command of
  880: .Xr vinum 8 :
  881: .if t .ps -3
  882: .if t .vs -3
  883: .Bd -literal
  884: GDB 4.16 (i386-unknown-dragonfly), Copyright 1996 Free Software Foundation, Inc.
  885: Debugger (msg=0xf1093174 "vinum debug") at ../../i386/i386/db_interface.c:318
  886: 318                 in_Debugger = 0;
  887: #1  0xf108d9bc in vinumioctl (dev=0x40001900, cmd=0xc008464b, data=0xf6dedee0 "",
  888:     flag=0x3, p=0xf68b7940) at
  889:     /usr/src/sys/modules/Vinum/../../dev/Vinum/vinumioctl.c:102
  890: 102             Debugger ("vinum debug");
  891: (kgdb) bt
  892: #0  Debugger (msg=0xf0f661ac "vinum debug") at ../../i386/i386/db_interface.c:318
  893: #1  0xf0f60a7c in vinumioctl (dev=0x40001900, cmd=0xc008464b, data=0xf6923ed0 "",
  894:       flag=0x3, p=0xf688e6c0) at
  895:       /usr/src/sys/modules/vinum/../../dev/vinum/vinumioctl.c:109
  896: #2  0xf01833b7 in spec_ioctl (ap=0xf6923e0c) at ../../miscfs/specfs/spec_vnops.c:424
  897: #3  0xf0182cc9 in spec_vnoperate (ap=0xf6923e0c) at ../../miscfs/specfs/spec_vnops.c:129
  898: #4  0xf01eb3c1 in ufs_vnoperatespec (ap=0xf6923e0c) at ../../ufs/ufs/ufs_vnops.c:2312
  899: #5  0xf017dbb1 in vn_ioctl (fp=0xf1007ec0, com=0xc008464b, data=0xf6923ed0 "",
  900:       p=0xf688e6c0) at vnode_if.h:395
  901: #6  0xf015dce0 in ioctl (p=0xf688e6c0, uap=0xf6923f84) at ../../kern/sys_generic.c:473
  902: #7  0xf0214c0b in syscall (frame={tf_es = 0x27, tf_ds = 0x27, tf_edi = 0xefbfcff8,
  903:       tf_esi = 0x1, tf_ebp = 0xefbfcf90, tf_isp = 0xf6923fd4, tf_ebx = 0x2,
  904:       tf_edx = 0x804b614, tf_ecx = 0x8085d10, tf_eax = 0x36, tf_trapno = 0x7,
  905:       tf_err = 0x2, tf_eip = 0x8060a34, tf_cs = 0x1f, tf_eflags = 0x286,
  906:       tf_esp = 0xefbfcf78, tf_ss = 0x27}) at ../../i386/i386/trap.c:1100
  907: #8  0xf020a1fc in Xint0x80_syscall ()
  908: #9  0x804832d in ?? ()
  909: #10 0x80482ad in ?? ()
  910: #11 0x80480e9 in ?? ()
  911: .Ed
  912: .if t .vs
  913: .if t .ps
  914: .Pp
  915: When entering from the debugger, it's important that the source of frame 1
  916: (listed by the
  917: .Pa .gdbinit
  918: file at the top of the example) contains the text
  919: .if t .ps -3
  920: .if t .vs -3
  921: .Bd -literal
  922: Debugger ("vinum debug");
  923: .Ed
  924: .if t .vs
  925: .if t .ps
  926: .Pp
  927: This is an indication that the address specifications are correct.  If you get
  928: some other output, your symbols and the kernel module are out of sync, and the
  929: trace will be meaningless.
  930: .El
  931: .Pp
  932: For an initial investigation, the most important information is the output of
  933: the
  934: .Nm bt
  935: (backtrace) command above.
  936: .Ss Reporting problems with Vinum
  937: .Pp
  938: If you find any bugs in
  939: .Nm ,
  940: please report them to Greg Lehey <grog@lemis.com>.  Supply the following
  941: information:
  942: .Pp
  943: .Bl -bullet
  944: .It
  945: The output of the
  946: .Nm
  947: .Cm list
  948: command.
  949: .It
  950: Any messages printed in
  951: .Pa /var/log/messages .
  952: All such messages will be identified by the text
  953: .Nm
  954: at the beginning.
  955: .It
  956: If you have a panic, a stack trace as described above.
  957: .El
  958: .Sh AUTHORS
  959: .An Greg Lehey Aq grog@lemis.com .
  960: .Sh HISTORY
  961: .Nm
  962: first appeared in
  963: .Fx 3.0 .
  964: The RAID-5 component of
  965: .Nm
  966: was developed by Cybernet Inc.
  967: .Pa www.cybernet.com
  968: for its NetMAX product.
  969: .Sh SEE ALSO
  970: .Xr disklabel 5 ,
  971: .Xr disklabel 8 ,
  972: .Xr newfs 8 ,
  973: .Xr vinum 8