From owner-svn-doc-head@FreeBSD.ORG Wed Feb 25 19:22:05 2015 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id C2BB9597; Wed, 25 Feb 2015 19:22:05 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id AC039A11; Wed, 25 Feb 2015 19:22:05 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t1PJM5tc081416; Wed, 25 Feb 2015 19:22:05 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t1PJM5dB081414; Wed, 25 Feb 2015 19:22:05 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201502251922.t1PJM5dB081414@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Wed, 25 Feb 2015 19:22:05 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r46294 - head/en_US.ISO8859-1/articles/vinum X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 25 Feb 2015 19:22:06 -0000 Author: wblock Date: Wed Feb 25 19:22:04 2015 New Revision: 46294 URL: https://svnweb.freebsd.org/changeset/doc/46294 Log: Restore the vinum chapter as an article. Added: - copied from r41710, head/en_US.ISO8859-1/books/handbook/vinum/ head/en_US.ISO8859-1/articles/vinum/article.xml - copied, changed from r41710, head/en_US.ISO8859-1/books/handbook/vinum/chapter.xml Directory Properties: head/en_US.ISO8859-1/articles/vinum/ (props changed) Deleted: head/en_US.ISO8859-1/articles/vinum/chapter.xml Modified: head/en_US.ISO8859-1/articles/vinum/Makefile Modified: head/en_US.ISO8859-1/articles/vinum/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/handbook/vinum/Makefile Thu May 23 06:12:40 2013 (r41710) +++ head/en_US.ISO8859-1/articles/vinum/Makefile Wed Feb 25 19:22:04 2015 (r46294) @@ -4,12 +4,26 @@ # $FreeBSD$ # -CHAPTERS= vinum/chapter.xml +DOC?= article -VPATH= .. +FORMATS?= html +WITH_ARTICLE_TOC?= YES -MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= -DOC_PREFIX?= ${.CURDIR}/../../../.. +SRCS= article.xml + +IMAGES_EN= vinum-concat.pic +IMAGES_EN+= vinum-mirrored-vol.pic +IMAGES_EN+= vinum-raid10-vol.pic +IMAGES_EN+= vinum-raid5-org.pic +IMAGES_EN+= vinum-simple-vol.pic +IMAGES_EN+= vinum-striped-vol.pic +IMAGES_EN+= vinum-striped.pic + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" -.include "../Makefile" Copied and modified: head/en_US.ISO8859-1/articles/vinum/article.xml (from r41710, head/en_US.ISO8859-1/books/handbook/vinum/chapter.xml) ============================================================================== --- head/en_US.ISO8859-1/books/handbook/vinum/chapter.xml Thu May 23 06:12:40 2013 (r41710, copy source) +++ head/en_US.ISO8859-1/articles/vinum/article.xml Wed Feb 25 19:22:04 2015 (r46294) @@ -1,4 +1,9 @@ + +
- - + + The <filename>vinum</filename> Volume Manager + + Greg Lehey + Originally written by - - - The <devicename>vinum</devicename> Volume Manager + - + Synopsis No matter the type of disks, there are always potential @@ -38,9 +44,9 @@ redundant, disks. In addition to supporting various cards and controllers for hardware Redundant Array of Independent Disks RAID systems, the base &os; system - includes the vinum volume manager, a + includes the vinum volume manager, a block device driver that implements virtual disk drives and - addresses these three problems. vinum + addresses these three problems. vinum provides more flexibility, performance, and reliability than traditional disk storage and implements RAID-0, RAID-1, and @@ -49,16 +55,16 @@ This chapter provides an overview of potential problems with traditional disk storage, and an introduction to the - vinum volume manager. + vinum volume manager. - Starting with &os; 5, vinum + Starting with &os; 5, vinum has been rewritten in order to fit into the GEOM architecture, while retaining the + xlink:href="&url.books.handbook;/geom.html">GEOM architecture, while retaining the original ideas, terminology, and on-disk metadata. This rewrite is called gvinum (for GEOM vinum). While this chapter uses the term - vinum, any command invocations should + vinum, any command invocations should be performed with gvinum. The name of the kernel module has changed from the original vinum.ko to @@ -66,12 +72,12 @@ reside under /dev/gvinum instead of /dev/vinum. As of - &os; 6, the original vinum + &os; 6, the original vinum implementation is no longer available in the code base. - + Access Bottlenecks Modern systems frequently need to access data in a highly @@ -96,7 +102,7 @@ to be atomic as it does not make any sense to interrupt them. - Consider a typical transfer of + Consider a typical transfer of about 10 kB: the current generation of high-performance disks can position the heads in an average of 3.5 ms. The fastest drives spin at 15,000 rpm, so the average @@ -147,10 +153,14 @@ organization. -
+
Concatenated Organization - + + + + +
@@ -184,14 +194,18 @@ organization. -
+
Striped Organization - + + + + +
- + Data Integrity The final problem with disks is that they are unreliable. @@ -239,10 +253,10 @@ An alternative solution is parity, implemented in RAID levels 2, 3, 4 and 5. Of these, RAID-5 is the most interesting. As - implemented in vinum, it is a variant + implemented in vinum, it is a variant on a striped organization which dedicates one block of each stripe to parity one of the other blocks. As implemented by - vinum, a + vinum, a RAID-5 plex is similar to a striped plex, except that it implements RAID-5 by including a parity block in each stripe. As required by @@ -251,10 +265,14 @@ blocks indicate the relative block numbers. -
+
<acronym>RAID</acronym>-5 Organization - + + + + +
Compared to mirroring, RAID-5 has the @@ -268,11 +286,11 @@ all the remaining drives. - - <devicename>vinum</devicename> Objects + + <filename>vinum</filename> Objects In order to address these problems, - vinum implements a four-level hierarchy + vinum implements a four-level hierarchy of objects: @@ -293,21 +311,21 @@ - Since vinum exists within the + Since vinum exists within the &unix; disk storage framework, it would be possible to use &unix; partitions as the building block for multi-disk plexes. In fact, this turns out to be too inflexible as &unix; disks can have only a limited number of partitions. - Instead, vinum subdivides a single + Instead, vinum subdivides a single &unix; partition, the drive, into contiguous areas called subdisks, which are used as building blocks for plexes. - Subdisks reside on vinum + Subdisks reside on vinum drives, currently &unix; partitions. - vinum drives can contain any + vinum drives can contain any number of subdisks. With the exception of a small area at the beginning of the drive, which is used for storing configuration and state information, the entire drive is @@ -317,13 +335,13 @@ The following sections describe the way these objects provide the functionality required of - vinum. + vinum. Volume Size Considerations Plexes can include multiple subdisks spread over all - drives in the vinum configuration. + drives in the vinum configuration. As a result, the size of an individual drive does not limit the size of a plex or a volume. @@ -331,7 +349,7 @@ Redundant Data Storage - vinum implements mirroring by + vinum implements mirroring by attaching multiple plexes to a volume. Each plex is a representation of the data in a volume. A volume may contain between one and eight plexes. @@ -348,7 +366,7 @@ Which Plex Organization? - vinum implements both + vinum implements both concatenation and striping at the plex level: @@ -374,7 +392,7 @@ By choosing an optimum sized stripe, about 256 kB, the load can be evened out on the component drives. Extending a plex by adding new subdisks is so complicated - that vinum does not implement + that vinum does not implement it. @@ -382,8 +400,8 @@ summarizes the advantages and disadvantages of each plex organization. - - <devicename>vinum</devicename> Plex + <table xml:id="vinum-comparison" frame="none"> + <title><filename>vinum</filename> Plex Organizations @@ -421,26 +439,26 @@ - + Some Examples - vinum maintains a + vinum maintains a configuration database which describes the objects known to an individual system. Initially, the user creates the configuration database from one or more configuration files using &man.gvinum.8;. - vinum stores a copy of its + vinum stores a copy of its configuration database on each disk device under its control. This database is updated on each state change, so that a restart accurately restores the state of each - vinum object. + vinum object. The Configuration File The configuration file describes individual - vinum objects. The definition of a + vinum objects. The definition of a simple volume might be: drive a device /dev/da3h @@ -448,7 +466,7 @@ plex org concat sd length 512m drive a - This file describes four vinum + This file describes four vinum objects: @@ -487,7 +505,7 @@ derived from the plex name by adding the suffix .sx, where x is the number of the subdisk in - the plex. Thus vinum gives this + the plex. Thus vinum gives this subdisk the name myvol.p0.s0. @@ -516,11 +534,15 @@ linkend="vinum-simple-vol"/>. -
- A Simple <devicename>vinum</devicename> + <figure xml:id="vinum-simple-vol"> + <title>A Simple <filename>vinum</filename> Volume - + + + + +
This figure, and the ones which follow, represent a @@ -555,7 +577,7 @@ In this example, it was not necessary to specify a definition of drive a again, since - vinum keeps track of all objects in + vinum keeps track of all objects in its configuration database. After processing this definition, the configuration looks like: @@ -583,11 +605,15 @@ structure graphically. -
- A Mirrored <devicename>vinum</devicename> + <figure xml:id="vinum-mirrored-vol"> + <title>A Mirrored <filename>vinum</filename> Volume - + + + + +
In this example, each plex contains the full 512 MB @@ -618,7 +644,7 @@ sd length 128m drive d As before, it is not necessary to define the drives which - are already known to vinum. After + are already known to vinum. After processing this definition, the configuration looks like: @@ -651,11 +677,15 @@ S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB -
- A Striped <devicename>vinum</devicename> + <figure xml:id="vinum-striped-vol"> + <title>A Striped <filename>vinum</filename> Volume - + + + + +
This volume is represented in Resilience and Performance - With sufficient hardware, + With sufficient hardware, it is possible to build volumes which show both increased resilience and increased performance compared to standard &unix; partitions. A typical configuration file might @@ -697,19 +727,23 @@ structure of this volume. -
- A Mirrored, Striped <devicename>vinum</devicename> + <figure xml:id="vinum-raid10-vol"> + <title>A Mirrored, Striped <filename>vinum</filename> Volume - + + + + +
- + Object Naming - vinum assigns default names to + vinum assigns default names to plexes and subdisks, although they may be overridden. Overriding the default names is not recommended as it does not bring a significant advantage and it can cause @@ -721,16 +755,16 @@ subdisks may be up to 64 characters long, and the names of drives may be up to 32 characters long. - vinum objects are assigned device + vinum objects are assigned device nodes in the hierarchy /dev/gvinum. The configuration - shown above would cause vinum to create + shown above would cause vinum to create the following device nodes: Device entries for each volume. These are the main - devices used by vinum. The + devices used by vinum. The configuration above would include the devices /dev/gvinum/myvol, /dev/gvinum/mirror, @@ -790,7 +824,7 @@ Although it is recommended that plexes and subdisks should not be allocated specific names, - vinum drives must be named. This makes + vinum drives must be named. This makes it possible to move a drive to a different location and still recognize it automatically. Drive names may be up to 32 characters long. @@ -800,20 +834,20 @@ Volumes appear to the system to be identical to disks, with one exception. Unlike &unix; drives, - vinum does not partition volumes, + vinum does not partition volumes, which thus do not contain a partition table. This has required modification to some disk utilities, notably &man.newfs.8;, so that it does not try to interpret the last - letter of a vinum volume name as a + letter of a vinum volume name as a partition identifier. For example, a disk drive may have a name like /dev/ad0a or /dev/da2h. These names represent the first partition - (a) on the first (0) IDE disk - (ad) and the eighth partition - (h) on the third (2) SCSI disk - (da) respectively. By contrast, a - vinum volume might be called + (a) on the first (0) IDE disk + (ad) and the eighth partition + (h) on the third (2) SCSI disk + (da) respectively. By contrast, a + vinum volume might be called /dev/gvinum/concat, which has no relationship with a partition name. @@ -824,14 +858,14 @@ - - Configuring <devicename>vinum</devicename> + + Configuring <filename>vinum</filename> The GENERIC kernel does not contain - vinum. It is possible to build a - custom kernel which includes vinum, but + vinum. It is possible to build a + custom kernel which includes vinum, but this is not recommended. The standard way to start - vinum is as a kernel module. + vinum is as a kernel module. &man.kldload.8; is not needed because when &man.gvinum.8; starts, it checks whether the module has been loaded, and if it is not, it loads it automatically. @@ -840,10 +874,10 @@ Startup - vinum stores configuration + vinum stores configuration information on the disk slices in essentially the same form as in the configuration files. When reading from the - configuration database, vinum + configuration database, vinum recognizes a number of keywords which are not allowed in the configuration files. For example, a disk configuration might contain the following text: @@ -871,15 +905,15 @@ sd name bigraid.p0.s4 drive e plex bigra The obvious differences here are the presence of explicit location information and naming, both of which are allowed but discouraged, and the information on the states. - vinum does not store information + vinum does not store information about drives in the configuration information. It finds the drives by scanning the configured disk drives for partitions - with a vinum label. This enables - vinum to identify drives correctly + with a vinum label. This enables + vinum to identify drives correctly even if they have been assigned different &unix; drive IDs. - + Automatic Startup Gvinum always features an @@ -889,14 +923,14 @@ sd name bigraid.p0.s4 drive e plex bigra geom_vinum_load="YES" to /boot/loader.conf. - When vinum is started with + When vinum is started with gvinum start, - vinum reads the configuration - database from one of the vinum + vinum reads the configuration + database from one of the vinum drives. Under normal circumstances, each drive contains an identical copy of the configuration database, so it does not matter which drive is read. After a crash, - however, vinum must determine + however, vinum must determine which drive was updated most recently and read the configuration from this drive. It then updates the configuration, if necessary, from progressively older @@ -905,12 +939,12 @@ sd name bigraid.p0.s4 drive e plex bigra - - Using <devicename>vinum</devicename> for the Root + <sect1 xml:id="vinum-root"> + <title>Using <filename>vinum</filename> for the Root File System For a machine that has fully-mirrored file systems using - vinum, it is desirable to also + vinum, it is desirable to also mirror the root file system. Setting up such a configuration is less trivial than mirroring an arbitrary file system because: @@ -919,7 +953,7 @@ sd name bigraid.p0.s4 drive e plex bigra The root file system must be available very early during the boot process, so the - vinum infrastructure must + vinum infrastructure must already be available at this time. @@ -927,20 +961,20 @@ sd name bigraid.p0.s4 drive e plex bigra contains the system bootstrap and the kernel. These must be read using the host system's native utilities, such as the BIOS, which often cannot be taught about the details - of vinum. + of vinum. In the following sections, the term root volume is generally used to describe the - vinum volume that contains the root + vinum volume that contains the root file system. - Starting up <devicename>vinum</devicename> Early + <title>Starting up <filename>vinum</filename> Early Enough for the Root File System - vinum must be available early + vinum must be available early in the system boot as &man.loader.8; must be able to load the vinum kernel module before starting the kernel. This can be accomplished by putting this line in @@ -951,13 +985,13 @@ sd name bigraid.p0.s4 drive e plex bigra - Making a <devicename>vinum</devicename>-based Root + <title>Making a <filename>vinum</filename>-based Root Volume Accessible to the Bootstrap The current &os; bootstrap is only 7.5 KB of code and does not understand the internal - vinum structures. This means that it - cannot parse the vinum configuration + vinum structures. This means that it + cannot parse the vinum configuration data or figure out the elements of a boot volume. Thus, some workarounds are necessary to provide the bootstrap code with the illusion of a standard a partition @@ -989,7 +1023,7 @@ sd name bigraid.p0.s4 drive e plex bigra partitions is located at the same offset within its device, compared with other devices containing plexes of the root volume. However, it is probably a good idea to create the - vinum volumes that way so the + vinum volumes that way so the resulting mirrored devices are symmetric, to avoid confusion. @@ -1005,7 +1039,7 @@ sd name bigraid.p0.s4 drive e plex bigra &prompt.root; gvinum l -rv root - vinum offsets and sizes are + vinum offsets and sizes are measured in bytes. They must be divided by 512 in order to obtain the block numbers that are to be used by bsdlabel. @@ -1018,13 +1052,13 @@ sd name bigraid.p0.s4 drive e plex bigra &prompt.root; bsdlabel -e devname devname must be either the - name of the disk, like da0 for + name of the disk, like da0 for disks without a slice table, or the name of the - slice, like ad0s1. + slice, like ad0s1. If there is already an a partition on the device from a - pre-vinum root file system, it + pre-vinum root file system, it should be renamed to something else so that it remains accessible (just in case), but will no longer be used by default to bootstrap the system. A currently mounted root @@ -1034,7 +1068,7 @@ sd name bigraid.p0.s4 drive e plex bigra disk that is not been currently booted is manipulated first. - The offset of the vinum + The offset of the vinum partition on this device (if any) must be added to the offset of the respective root volume subdisk on this device. The resulting value will become the @@ -1051,9 +1085,9 @@ sd name bigraid.p0.s4 drive e plex bigra That way, a new a partition will be established that overlaps the - vinum partition on this device. + vinum partition on this device. bsdlabel will only allow for this - overlap if the vinum partition + overlap if the vinum partition has properly been marked using the vinum fstype. @@ -1070,8 +1104,8 @@ sd name bigraid.p0.s4 drive e plex bigra It should be remembered that all files containing control information must be relative to the root file system in the - vinum volume which, when setting up - a new vinum root volume, might not + vinum volume which, when setting up + a new vinum root volume, might not match the root file system that is currently active. So in particular, /etc/fstab and /boot/loader.conf need to be taken care @@ -1079,7 +1113,7 @@ sd name bigraid.p0.s4 drive e plex bigra At next reboot, the bootstrap should figure out the appropriate control information from the new - vinum-based root file system, and act + vinum-based root file system, and act accordingly. At the end of the kernel initialization process, after all devices have been announced, the prominent notice that shows the success of this setup is a message like: @@ -1088,10 +1122,10 @@ sd name bigraid.p0.s4 drive e plex bigra - Example of a <devicename>vinum</devicename>-based Root + <title>Example of a <filename>vinum</filename>-based Root Setup - After the vinum root volume has + After the vinum root volume has been set up, the output of gvinum l -rv root could look like: @@ -1131,18 +1165,18 @@ Subdisk root.p1.s0: parameter for the faked a partition matches the value outlined above, while the offset parameter is the sum of the offset - within the vinum partition + within the vinum partition h, and the offset of this partition within the device or slice. This is a typical setup that is necessary to avoid the problem described in . The entire a partition is completely within the h partition containing all the - vinum data for this device. + vinum data for this device. In the above example, the entire device is dedicated to - vinum and there is no leftover - pre-vinum root partition. + vinum and there is no leftover + pre-vinum root partition. @@ -1163,7 +1197,7 @@ Subdisk root.p1.s0: using set or unset. - If the vinum kernel module was + If the vinum kernel module was not yet in the list of modules to load automatically, type load geom_vinum. @@ -1185,15 +1219,15 @@ Subdisk root.p1.s0: alternate choice would be something like ufs:da0d which could be a hypothetical partition containing the - pre-vinum root file system. Care + pre-vinum root file system. Care should be taken if one of the alias a partitions is entered here, that it actually references the subdisks of the - vinum root device, because in a + vinum root device, because in a mirrored setup, this would only mount one piece of a mirrored root device. If this file system is to be mounted read-write later on, it is necessary to remove the other - plex(es) of the vinum root volume + plex(es) of the vinum root volume since these plexes would otherwise carry inconsistent data. @@ -1207,45 +1241,45 @@ Subdisk root.p1.s0: process starts), an attempt can be made to interrupt the primary bootstrap by pressing space. This will make the bootstrap stop - in stage two. An attempt + in stage two. An attempt can be made here to boot off an alternate partition, like the partition containing the previous root file system that has been moved away from a. - + Nothing Boots, the Bootstrap Panics This situation will happen if the bootstrap had been - destroyed by the vinum - installation. Unfortunately, vinum + destroyed by the vinum + installation. Unfortunately, vinum accidentally leaves only 4 KB at the beginning of its partition free before starting to write its - vinum header information. However, + vinum header information. However, the stage one and two bootstraps plus the bsdlabel require 8 - KB. So if a vinum partition was + KB. So if a vinum partition was started at offset 0 within a slice or disk that was meant to - be bootable, the vinum setup will + be bootable, the vinum setup will trash the bootstrap. Similarly, if the above situation has been recovered, by booting from a Fixit media, and the bootstrap has been re-installed using - bsdlabel -B as described in , the bootstrap will trash the - vinum header, and - vinum will no longer find its - disk(s). Though no actual vinum - configuration data or data in vinum + bsdlabel -B as described in , the bootstrap will trash the + vinum header, and + vinum will no longer find its + disk(s). Though no actual vinum + configuration data or data in vinum volumes will be trashed, and it would be possible to recover all the data by entering exactly the same - vinum configuration data again, the + vinum configuration data again, the situation is hard to fix. It is necessary to move the - entire vinum partition by at least - 4 KB, in order to have the vinum + entire vinum partition by at least + 4 KB, in order to have the vinum header and the system bootstrap no longer collide. - +