[src/trunk]: src/share/man/man4 Preliminary docco for vinum.

[grog <grog%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5f2db3c3aedc
branches:  trunk
changeset: 553424:5f2db3c3aedc
user:      grog <grog%NetBSD.org@localhost>
date:      Thu Oct 16 08:29:52 2003 +0000

description:
Preliminary docco for vinum.

diffstat:

 share/man/man4/vinum.4 |  691 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 691 insertions(+), 0 deletions(-)

diffs (truncated from 695 to 300 lines):

diff -r 9998a243bfa5 -r 5f2db3c3aedc share/man/man4/vinum.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/vinum.4    Thu Oct 16 08:29:52 2003 +0000
@@ -0,0 +1,691 @@
+.\"  Hey, Emacs, edit this file in -*- nroff-fill -*- mode
+.\"-
+.\" Copyright (c) 1997, 1998
+.\"    Nan Yang Computer Services Limited.  All rights reserved.
+.\"
+.\"  This software is distributed under the so-called ``Berkeley
+.\"  License'':
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by Nan Yang Computer
+.\"      Services Limited.
+.\" 4. Neither the name of the Company nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"  
+.\" This software is provided ``as is'', and any express or implied
+.\" warranties, including, but not limited to, the implied warranties of
+.\" merchantability and fitness for a particular purpose are disclaimed.
+.\" In no event shall the company or contributors be liable for any
+.\" direct, indirect, incidental, special, exemplary, or consequential
+.\" damages (including, but not limited to, procurement of substitute
+.\" goods or services; loss of use, data, or profits; or business
+.\" interruption) however caused and on any theory of liability, whether
+.\" in contract, strict liability, or tort (including negligence or
+.\" otherwise) arising in any way out of the use of this software, even if
+.\" advised of the possibility of such damage.
+.\"
+.\" $Id: vinum.4,v 1.1 2003/10/16 08:29:52 grog Exp $
+.\" $NetBSD: vinum.4,v 1.1 2003/10/16 08:29:52 grog Exp $
+.\"
+.Dd 5 October 1999
+.Dt vinum 4
+.Sh NAME
+.Nm vinum
+.Nd Logical Volume Manager
+.Sh SYNOPSIS
+.Cd "kldload vinum"
+.Cd "kldload Vinum"
+.Sh DESCRIPTION
+.Nm
+is a logical volume manager inspired by, but not derived from, the Veritas
+Volume Manager.  It provides the following features:
+.Bl -bullet
+.It
+It provides device-independent logical disks, called \fIvolumes\fP.  Volumes are
+not restricted to the size of any disk on the system.
+.It
+The volumes consist of one or more \fIplexes\fP, each of which contain the
+entire address space of a volume.  This represents an implementation of RAID-1
+(mirroring).  Multiple plexes can also be used for
+.\" XXX What about sparse plexes?  Do we want them?
+.if t .sp
+.Bl -bullet
+.It
+Increased read throughput.
+.Nm
+will read data from the least active disk, so if a volume has plexes on multiple
+disks, more data can be read in parallel.
+.Nm
+reads data from only one plex, but it writes data to all plexes.
+.It
+Increased reliability.  By storing plexes on different disks, data will remain
+available even if one of the plexes becomes unavailable.  In comparison with a
+RAID-5 or RAID-4 plex (see below), using multiple plexes requires more storage
+space, but gives better performance, particularly in the case of a drive
+failure.
+.It
+Additional plexes can be used for on-line data reorganization.  By attaching an
+additional plex and subsequently detaching one of the older plexes, data can be
+moved on-line without compromising access.
+.It
+An additional plex can be used to obtain a consistent dump of a file system.  By
+attaching an additional plex and detaching at a specific time, the detached plex
+becomes an accurate snapshot of the file system at the time of detachment.
+.\" Make sure to flush!
+.El
+.It
+Each plex consists of one or more logical disk slices, called \fIsubdisks\fP.
+Subdisks are defined as a contiguous block of physical disk storage.  A plex may
+consist of any reasonable number of subdisks (in other words, the real limit is
+not the number, but other factors, such as memory and performance, associated
+with maintaining a large number of subdisks).
+.It
+A number of mappings between subdisks and plexes are available:
+.Bl -bullet
+.It
+\fIConcatenated plexes\fP\| consist of one or more subdisks, each of which
+is mapped to a contiguous part of the plex address space.
+.It
+\fIStriped plexes\fP\| consist of two or more subdisks of equal size.  The file
+address space is mapped in \fIstripes\fP, integral fractions of the subdisk
+size.  Consecutive plex address space is mapped to stripes in each subdisk in
+.if n turn.
+.if t \{\
+turn.
+.ig
+.\" FIXME
+.br
+.ne 1.5i
+.PS
+move right 2i
+down
+SD0: box
+SD1: box
+SD2: box
+
+"plex 0" at SD0.n+(0,.2)
+"subdisk 0" rjust at SD0.w-(.2,0)
+"subdisk 1" rjust at SD1.w-(.2,0)
+"subdisk 2" rjust at SD2.w-(.2,0)
+.PE
+..
+.\}
+The subdisks of a striped plex must all be the same size.
+.It
+\fIRAID-5 plexes\fP\| require at least three equal-sized subdisks.  They
+resemble striped plexes, except that in each stripe, one subdisk stores parity
+information.  This subdisk changes in each stripe: in the first stripe, it is the
+first subdisk, in the second it is the second subdisk, etc.  In the event of a
+single disk failure,
+.Nm
+will recover the data based on the information stored on the remaining subdisks.
+This mapping is particularly suited to read-intensive access.  The subdisks of a
+RAID-5 plex must all be the same size.
+.It
+.Nm
+also supports \fIRAID-4 plexes\fP.  They have no advantage over RAID-5.  The
+only difference is that the parity information resides on the same subdisk for
+each stripe.  The subdisks of a RAID-4 plex must all be the same size.
+.\" Make sure to flush!
+.El
+.It
+.Nm Drives
+are the lowest level of the storage hierarchy.  They represent disk special
+devices.
+.It
+.Nm
+offers automatic startup.  Unlike
+.Ux
+file systems,
+.Nm
+volumes contain all the configuration information needed to ensure that they are
+started correctly when the subsystem is enabled.  This is also a significant
+advantage over the Veritas\(tm File System.  This feature regards the presence
+of the volumes.  It does not mean that the volumes will be mounted
+automatically, since the standard startup procedures with
+.Pa /etc/fstab 
+perform this function.
+.El
+.Sh KERNEL CONFIGURATION
+.Nm
+is intended to be used as a loadable kernel loadable module (LKM).  Currently it
+must be compiled into the kernel.  To do so, add this line to the kernel
+configuration file:
+.Bd -literal -offset indent
+pseudo-device  vinum
+.Ed
+.Pp
+.Ss DEBUG OPTIONS
+The current version of
+.Nm vinum ,
+both the kernel module and the user program
+.Xr vinum 8 ,
+include significant debugging support.
+Enable it with the following entry in the kernel configuration file:
+.Bd -literal -offset indent
+options         VINUMDEBUG
+.Ed
+.Sh RUNNING VINUM
+.Nm
+is part of the base NetBSD system.  It does not require installation.
+To start it, start the
+.Nm vinum
+program, which will load the kld if it is not already present.
+Before using
+.Nm vinum ,
+it must be configured.  See
+.Xr vinum 8
+for information on how to create a
+.Nm
+configuration.
+.Pp
+Normally, you start a configured version of
+.Nm
+at boot time.  Set the variable
+.Ar start_vinum
+in
+.Pa /etc/rc.conf
+to
+.Ar YES
+to start
+.Nm
+at boot time.
+.Pp
+If
+.Nm
+is loaded as a kld (the recommended way), the
+.Nm vinum Ar stop
+command will unload it.  You can also do this with the
+.Nm kldunload
+command.
+.Pp
+The kld can only be unloaded when idle, in other words when no volumes are
+mounted and no other instances of the
+.Nm
+program are active.  Unloading the kld does not harm the data in the volumes.
+.Ss CONFIGURING AND STARTING OBJECTS
+Use the
+.Xr vinum 8
+utility to configure and start
+.Nm 
+objects.
+.Sh IOCTL CALLS
+.Pa ioctl
+calls are intended for the use of the
+.Nm
+configuration program only.  They are described in the header file
+.Pa /sys/dev/vinum/vinumio.h
+.Ss DISK LABELS
+Conventional disk special devices have a
+.Em disk label
+in the second sector of the device.  See
+.Xr disklabel 5
+for more details.  This disk label describes the layout of the partitions within
+the device.
+.Nm
+does not subdivide volumes, so volumes do not contain a physical disk label.
+For convenience,
+.Nm
+implements the ioctl calls DIOCGDINFO (get disk label), DIOCGPART (get partition
+information), DIOCWDINFO (write partition information) and DIOCSDINFO (set
+partition information).  DIOCGDINFO and DIOCGPART refer to an internal
+representation of the disk label which is not present on the volume.  As a
+result, the
+.Fl r
+option of
+.Xr disklabel 8 ,
+which reads the 
+.if t ``raw disk'', 
+.if n "raw disk", 
+will fail.
+.Pp
+In general, 
+.Xr disklabel 8
+serves no useful purpose on a vinum volume.  If you run it, it will show you
+three partitions, a, b and c, all the same except for the fstype, for example:
+.br
+.ne 1i
+.Bd -literal -offset
+3 partitions:
+#        size   offset    fstype   [fsize bsize bps/cpg]
+  a:     2048        0    4.2BSD     1024  8192     0   # (Cyl.    0 - 0)
+  b:     2048        0      swap                        # (Cyl.    0 - 0)
+  c:     2048        0    unused        0     0         # (Cyl.    0 - 0)
+.Ed
+.Pp
+.Nm
+ignores the DIOCWDINFO and DIOCSDINFO ioctls, since there is nothing to change.
+As a result, any attempt to modify the disk label will be silently ignored.
+.Sh MAKING FILE SYSTEMS
+Since
+.Nm
+volumes do not contain partitions, the names do not need to conform to the
+standard rules for naming disk partitions.  For a physical disk partition, the
+last letter of the device name specifies the partition identifier (a to h).
+.Nm
+volumes need not conform to this convention, but if they do not,
+.Nm newfs
+will complain that it cannot determine the partition.  To solve this problem,
+use the
+.Fl v
+flag to
+.Nm newfs .
+For example, if you have a volume
+.Pa concat ,
+use the following command to create a ufs file system on it:
+.Pp
+.Bd -literal
+  # newfs -v /dev/vinum/concat
+.Ed
+.Pp
+.Sh OBJECT NAMING
+.Nm
+assigns default names to plexes and subdisks, although they may be overridden.
+We do not recommend overriding the default names.  Experience with the
+.if t Veritas\(tm
+.if n Veritas(tm)