svn commit: r46294 - head/en_US.ISO8859-1/articles/vinum
Warren Block
wblock at FreeBSD.org
Wed Feb 25 19:22:06 UTC 2015
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 @@
<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="en">
<!--
The Vinum Volume Manager
By Greg Lehey (grog at lemis dot com)
@@ -10,20 +15,21 @@
$FreeBSD$
-->
-<chapter id="vinum-vinum">
- <chapterinfo>
+ <info>
+ <title>The <filename>vinum</filename> Volume Manager</title>
+
<authorgroup>
<author>
+ <personname>
<firstname>Greg</firstname>
<surname>Lehey</surname>
+ </personname>
<contrib>Originally written by </contrib>
</author>
</authorgroup>
- </chapterinfo>
-
- <title>The <devicename>vinum</devicename> Volume Manager</title>
+ </info>
- <sect1 id="vinum-synopsis">
+ <sect1 xml:id="vinum-synopsis">
<title>Synopsis</title>
<para>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 <acronym>RAID</acronym> systems, the base &os; system
- includes the <devicename>vinum</devicename> volume manager, a
+ includes the <filename>vinum</filename> volume manager, a
block device driver that implements virtual disk drives and
- addresses these three problems. <devicename>vinum</devicename>
+ addresses these three problems. <filename>vinum</filename>
provides more flexibility, performance, and reliability than
traditional disk storage and implements
<acronym>RAID</acronym>-0, <acronym>RAID</acronym>-1, and
@@ -49,16 +55,16 @@
<para>This chapter provides an overview of potential problems with
traditional disk storage, and an introduction to the
- <devicename>vinum</devicename> volume manager.</para>
+ <filename>vinum</filename> volume manager.</para>
<note>
- <para>Starting with &os; 5, <devicename>vinum</devicename>
+ <para>Starting with &os; 5, <filename>vinum</filename>
has been rewritten in order to fit into the <link
- linkend="GEOM">GEOM architecture</link>, while retaining the
+ xlink:href="&url.books.handbook;/geom.html">GEOM architecture</link>, while retaining the
original ideas, terminology, and on-disk metadata. This
rewrite is called <emphasis>gvinum</emphasis> (for <emphasis>
GEOM vinum</emphasis>). While this chapter uses the term
- <devicename>vinum</devicename>, any command invocations should
+ <filename>vinum</filename>, any command invocations should
be performed with <command>gvinum</command>. The name of the
kernel module has changed from the original
<filename>vinum.ko</filename> to
@@ -66,12 +72,12 @@
reside under <filename
class="directory">/dev/gvinum</filename> instead of
<filename class="directory">/dev/vinum</filename>. As of
- &os; 6, the original <devicename>vinum</devicename>
+ &os; 6, the original <filename>vinum</filename>
implementation is no longer available in the code base.</para>
</note>
</sect1>
- <sect1 id="vinum-access-bottlenecks">
+ <sect1 xml:id="vinum-access-bottlenecks">
<title>Access Bottlenecks</title>
<para>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.</para>
- <para><anchor id="vinum-latency"/> Consider a typical transfer of
+ <para><anchor xml:id="vinum-latency"/> 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.</para>
<para>
- <figure id="vinum-concat">
+ <figure xml:id="vinum-concat">
<title>Concatenated Organization</title>
- <graphic fileref="vinum/vinum-concat"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-concat"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
<indexterm>
@@ -184,14 +194,18 @@
organization.</para>
<para>
- <figure id="vinum-striped">
+ <figure xml:id="vinum-striped">
<title>Striped Organization</title>
- <graphic fileref="vinum/vinum-striped"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-striped"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
</sect1>
- <sect1 id="vinum-data-integrity">
+ <sect1 xml:id="vinum-data-integrity">
<title>Data Integrity</title>
<para>The final problem with disks is that they are unreliable.
@@ -239,10 +253,10 @@
<para>An alternative solution is <emphasis>parity</emphasis>,
implemented in <acronym>RAID</acronym> levels 2, 3, 4 and 5.
Of these, <acronym>RAID-5</acronym> is the most interesting. As
- implemented in <devicename>vinum</devicename>, it is a variant
+ implemented in <filename>vinum</filename>, 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
- <devicename>vinum</devicename>, a
+ <filename>vinum</filename>, a
<acronym>RAID-5</acronym> plex is similar to a striped plex,
except that it implements <acronym>RAID-5</acronym> by
including a parity block in each stripe. As required by
@@ -251,10 +265,14 @@
blocks indicate the relative block numbers.</para>
<para>
- <figure id="vinum-raid5-org">
+ <figure xml:id="vinum-raid5-org">
<title><acronym>RAID</acronym>-5 Organization</title>
- <graphic fileref="vinum/vinum-raid5-org"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-raid5-org"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
<para>Compared to mirroring, <acronym>RAID-5</acronym> has the
@@ -268,11 +286,11 @@
all the remaining drives.</para>
</sect1>
- <sect1 id="vinum-objects">
- <title><devicename>vinum</devicename> Objects</title>
+ <sect1 xml:id="vinum-objects">
+ <title><filename>vinum</filename> Objects</title>
<para>In order to address these problems,
- <devicename>vinum</devicename> implements a four-level hierarchy
+ <filename>vinum</filename> implements a four-level hierarchy
of objects:</para>
<itemizedlist>
@@ -293,21 +311,21 @@
</listitem>
<listitem>
- <para>Since <devicename>vinum</devicename> exists within the
+ <para>Since <filename>vinum</filename> 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, <devicename>vinum</devicename> subdivides a single
+ Instead, <filename>vinum</filename> subdivides a single
&unix; partition, the <emphasis>drive</emphasis>, into
contiguous areas called <emphasis>subdisks</emphasis>, which
are used as building blocks for plexes.</para>
</listitem>
<listitem>
- <para>Subdisks reside on <devicename>vinum</devicename>
+ <para>Subdisks reside on <filename>vinum</filename>
<emphasis>drives</emphasis>, currently &unix; partitions.
- <devicename>vinum</devicename> drives can contain any
+ <filename>vinum</filename> 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 @@
<para>The following sections describe the way these objects
provide the functionality required of
- <devicename>vinum</devicename>.</para>
+ <filename>vinum</filename>.</para>
<sect2>
<title>Volume Size Considerations</title>
<para>Plexes can include multiple subdisks spread over all
- drives in the <devicename>vinum</devicename> configuration.
+ drives in the <filename>vinum</filename> configuration.
As a result, the size of an individual drive does not limit
the size of a plex or a volume.</para>
</sect2>
@@ -331,7 +349,7 @@
<sect2>
<title>Redundant Data Storage</title>
- <para><devicename>vinum</devicename> implements mirroring by
+ <para><filename>vinum</filename> 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.</para>
@@ -348,7 +366,7 @@
<sect2>
<title>Which Plex Organization?</title>
- <para><devicename>vinum</devicename> implements both
+ <para><filename>vinum</filename> implements both
concatenation and striping at the plex level:</para>
<itemizedlist>
@@ -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 <devicename>vinum</devicename> does not implement
+ that <filename>vinum</filename> does not implement
it.</para>
</listitem>
</itemizedlist>
@@ -382,8 +400,8 @@
<para><xref linkend="vinum-comparison"/> summarizes the
advantages and disadvantages of each plex organization.</para>
- <table id="vinum-comparison" frame="none">
- <title><devicename>vinum</devicename> Plex
+ <table xml:id="vinum-comparison" frame="none">
+ <title><filename>vinum</filename> Plex
Organizations</title>
<tgroup cols="5">
@@ -421,26 +439,26 @@
</sect2>
</sect1>
- <sect1 id="vinum-examples">
+ <sect1 xml:id="vinum-examples">
<title>Some Examples</title>
- <para><devicename>vinum</devicename> maintains a
+ <para><filename>vinum</filename> maintains a
<emphasis>configuration database</emphasis> 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;.
- <devicename>vinum</devicename> stores a copy of its
+ <filename>vinum</filename> stores a copy of its
configuration database on each disk
<emphasis>device</emphasis> under its control. This database is
updated on each state change, so that a restart accurately
restores the state of each
- <devicename>vinum</devicename> object.</para>
+ <filename>vinum</filename> object.</para>
<sect2>
<title>The Configuration File</title>
<para>The configuration file describes individual
- <devicename>vinum</devicename> objects. The definition of a
+ <filename>vinum</filename> objects. The definition of a
simple volume might be:</para>
<programlisting> drive a device /dev/da3h
@@ -448,7 +466,7 @@
plex org concat
sd length 512m drive a</programlisting>
- <para>This file describes four <devicename>vinum</devicename>
+ <para>This file describes four <filename>vinum</filename>
objects:</para>
<itemizedlist>
@@ -487,7 +505,7 @@
derived from the plex name by adding the suffix
<emphasis>.s</emphasis><emphasis>x</emphasis>, where
<emphasis>x</emphasis> is the number of the subdisk in
- the plex. Thus <devicename>vinum</devicename> gives this
+ the plex. Thus <filename>vinum</filename> gives this
subdisk the name <emphasis>myvol.p0.s0</emphasis>.</para>
</listitem>
</itemizedlist>
@@ -516,11 +534,15 @@
linkend="vinum-simple-vol"/>.</para>
<para>
- <figure id="vinum-simple-vol">
- <title>A Simple <devicename>vinum</devicename>
+ <figure xml:id="vinum-simple-vol">
+ <title>A Simple <filename>vinum</filename>
Volume</title>
- <graphic fileref="vinum/vinum-simple-vol"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-simple-vol"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
<para>This figure, and the ones which follow, represent a
@@ -555,7 +577,7 @@
<para>In this example, it was not necessary to specify a
definition of drive <emphasis>a</emphasis> again, since
- <devicename>vinum</devicename> keeps track of all objects in
+ <filename>vinum</filename> keeps track of all objects in
its configuration database. After processing this definition,
the configuration looks like:</para>
@@ -583,11 +605,15 @@
structure graphically.</para>
<para>
- <figure id="vinum-mirrored-vol">
- <title>A Mirrored <devicename>vinum</devicename>
+ <figure xml:id="vinum-mirrored-vol">
+ <title>A Mirrored <filename>vinum</filename>
Volume</title>
- <graphic fileref="vinum/vinum-mirrored-vol"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-mirrored-vol"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
<para>In this example, each plex contains the full 512 MB
@@ -618,7 +644,7 @@
sd length 128m drive d</programlisting>
<para>As before, it is not necessary to define the drives which
- are already known to <devicename>vinum</devicename>. After
+ are already known to <filename>vinum</filename>. After
processing this definition, the configuration looks
like:</para>
@@ -651,11 +677,15 @@
S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB</programlisting>
<para>
- <figure id="vinum-striped-vol">
- <title>A Striped <devicename>vinum</devicename>
+ <figure xml:id="vinum-striped-vol">
+ <title>A Striped <filename>vinum</filename>
Volume</title>
- <graphic fileref="vinum/vinum-striped-vol"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-striped-vol"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
<para>This volume is represented in <xref
@@ -668,7 +698,7 @@
<sect2>
<title>Resilience and Performance</title>
- <para><anchor id="vinum-resilience"/>With sufficient hardware,
+ <para><anchor xml:id="vinum-resilience"/>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.</para>
<para>
- <figure id="vinum-raid10-vol">
- <title>A Mirrored, Striped <devicename>vinum</devicename>
+ <figure xml:id="vinum-raid10-vol">
+ <title>A Mirrored, Striped <filename>vinum</filename>
Volume</title>
- <graphic fileref="vinum/vinum-raid10-vol"/>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="vinum/vinum-raid10-vol"/>
+ </imageobject>
+ </mediaobject>
</figure></para>
</sect2>
</sect1>
- <sect1 id="vinum-object-naming">
+ <sect1 xml:id="vinum-object-naming">
<title>Object Naming</title>
- <para><devicename>vinum</devicename> assigns default names to
+ <para><filename>vinum</filename> 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.</para>
- <para><devicename>vinum</devicename> objects are assigned device
+ <para><filename>vinum</filename> objects are assigned device
nodes in the hierarchy <filename
class="directory">/dev/gvinum</filename>. The configuration
- shown above would cause <devicename>vinum</devicename> to create
+ shown above would cause <filename>vinum</filename> to create
the following device nodes:</para>
<itemizedlist>
<listitem>
<para>Device entries for each volume. These are the main
- devices used by <devicename>vinum</devicename>. The
+ devices used by <filename>vinum</filename>. The
configuration above would include the devices
<filename class="devicefile">/dev/gvinum/myvol</filename>,
<filename class="devicefile">/dev/gvinum/mirror</filename>,
@@ -790,7 +824,7 @@
<para>Although it is recommended that plexes and subdisks should
not be allocated specific names,
- <devicename>vinum</devicename> drives must be named. This makes
+ <filename>vinum</filename> 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.</para>
@@ -800,20 +834,20 @@
<para>Volumes appear to the system to be identical to disks,
with one exception. Unlike &unix; drives,
- <devicename>vinum</devicename> does not partition volumes,
+ <filename>vinum</filename> 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 <devicename>vinum</devicename> volume name as a
+ letter of a <filename>vinum</filename> volume name as a
partition identifier. For example, a disk drive may have a
name like <filename class="devicefile">/dev/ad0a</filename>
or <filename class="devicefile">/dev/da2h</filename>. These
names represent the first partition
- (<devicename>a</devicename>) on the first (0) IDE disk
- (<devicename>ad</devicename>) and the eighth partition
- (<devicename>h</devicename>) on the third (2) SCSI disk
- (<devicename>da</devicename>) respectively. By contrast, a
- <devicename>vinum</devicename> volume might be called
+ (<filename>a</filename>) on the first (0) IDE disk
+ (<filename>ad</filename>) and the eighth partition
+ (<filename>h</filename>) on the third (2) SCSI disk
+ (<filename>da</filename>) respectively. By contrast, a
+ <filename>vinum</filename> volume might be called
<filename class="devicefile">/dev/gvinum/concat</filename>,
which has no relationship with a partition name.</para>
@@ -824,14 +858,14 @@
</sect2>
</sect1>
- <sect1 id="vinum-config">
- <title>Configuring <devicename>vinum</devicename></title>
+ <sect1 xml:id="vinum-config">
+ <title>Configuring <filename>vinum</filename></title>
<para>The <filename>GENERIC</filename> kernel does not contain
- <devicename>vinum</devicename>. It is possible to build a
- custom kernel which includes <devicename>vinum</devicename>, but
+ <filename>vinum</filename>. It is possible to build a
+ custom kernel which includes <filename>vinum</filename>, but
this is not recommended. The standard way to start
- <devicename>vinum</devicename> is as a kernel module.
+ <filename>vinum</filename> 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.</para>
@@ -840,10 +874,10 @@
<sect2>
<title>Startup</title>
- <para><devicename>vinum</devicename> stores configuration
+ <para><filename>vinum</filename> stores configuration
information on the disk slices in essentially the same form as
in the configuration files. When reading from the
- configuration database, <devicename>vinum</devicename>
+ configuration database, <filename>vinum</filename>
recognizes a number of keywords which are not allowed in the
configuration files. For example, a disk configuration might
contain the following text:</para>
@@ -871,15 +905,15 @@ sd name bigraid.p0.s4 drive e plex bigra
<para>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.
- <devicename>vinum</devicename> does not store information
+ <filename>vinum</filename> does not store information
about drives in the configuration information. It finds the
drives by scanning the configured disk drives for partitions
- with a <devicename>vinum</devicename> label. This enables
- <devicename>vinum</devicename> to identify drives correctly
+ with a <filename>vinum</filename> label. This enables
+ <filename>vinum</filename> to identify drives correctly
even if they have been assigned different &unix; drive
IDs.</para>
- <sect3 id="vinum-rc-startup">
+ <sect3 xml:id="vinum-rc-startup">
<title>Automatic Startup</title>
<para><emphasis>Gvinum</emphasis> always features an
@@ -889,14 +923,14 @@ sd name bigraid.p0.s4 drive e plex bigra
<literal>geom_vinum_load="YES"</literal> to
<filename>/boot/loader.conf</filename>.</para>
- <para>When <devicename>vinum</devicename> is started with
+ <para>When <filename>vinum</filename> is started with
<command>gvinum start</command>,
- <devicename>vinum</devicename> reads the configuration
- database from one of the <devicename>vinum</devicename>
+ <filename>vinum</filename> reads the configuration
+ database from one of the <filename>vinum</filename>
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, <devicename>vinum</devicename> must determine
+ however, <filename>vinum</filename> 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
</sect2>
</sect1>
- <sect1 id="vinum-root">
- <title>Using <devicename>vinum</devicename> for the Root
+ <sect1 xml:id="vinum-root">
+ <title>Using <filename>vinum</filename> for the Root
File System</title>
<para>For a machine that has fully-mirrored file systems using
- <devicename>vinum</devicename>, it is desirable to also
+ <filename>vinum</filename>, 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:</para>
@@ -919,7 +953,7 @@ sd name bigraid.p0.s4 drive e plex bigra
<listitem>
<para>The root file system must be available very early
during the boot process, so the
- <devicename>vinum</devicename> infrastructure must
+ <filename>vinum</filename> infrastructure must
already be available at this time.</para>
</listitem>
<listitem>
@@ -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 <devicename>vinum</devicename>.</para>
+ of <filename>vinum</filename>.</para>
</listitem>
</itemizedlist>
<para>In the following sections, the term <quote>root
volume</quote> is generally used to describe the
- <devicename>vinum</devicename> volume that contains the root
+ <filename>vinum</filename> volume that contains the root
file system.</para>
<sect2>
- <title>Starting up <devicename>vinum</devicename> Early
+ <title>Starting up <filename>vinum</filename> Early
Enough for the Root File System</title>
- <para><devicename>vinum</devicename> must be available early
+ <para><filename>vinum</filename> 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
</sect2>
<sect2>
- <title>Making a <devicename>vinum</devicename>-based Root
+ <title>Making a <filename>vinum</filename>-based Root
Volume Accessible to the Bootstrap</title>
<para>The current &os; bootstrap is only 7.5 KB of code and
does not understand the internal
- <devicename>vinum</devicename> structures. This means that it
- cannot parse the <devicename>vinum</devicename> configuration
+ <filename>vinum</filename> structures. This means that it
+ cannot parse the <filename>vinum</filename> 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 <literal>a</literal> 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
- <devicename>vinum</devicename> volumes that way so the
+ <filename>vinum</filename> volumes that way so the
resulting mirrored devices are symmetric, to avoid
confusion.</para>
@@ -1005,7 +1039,7 @@ sd name bigraid.p0.s4 drive e plex bigra
<screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen>
- <para><devicename>vinum</devicename> offsets and sizes are
+ <para><filename>vinum</filename> 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
<command>bsdlabel</command>.</para>
@@ -1018,13 +1052,13 @@ sd name bigraid.p0.s4 drive e plex bigra
<screen>&prompt.root; <userinput>bsdlabel -e <replaceable>devname</replaceable></userinput></screen>
<para><replaceable>devname</replaceable> must be either the
- name of the disk, like <devicename>da0</devicename> for
+ name of the disk, like <filename>da0</filename> for
disks without a slice table, or the name of the
- slice, like <devicename>ad0s1</devicename>.</para>
+ slice, like <filename>ad0s1</filename>.</para>
<para>If there is already an <literal>a</literal>
partition on the device from a
- pre-<devicename>vinum</devicename> root file system, it
+ pre-<filename>vinum</filename> 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.</para>
- <para>The offset of the <devicename>vinum</devicename>
+ <para>The offset of the <filename>vinum</filename>
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
<para>That way, a new <literal>a</literal> partition will
be established that overlaps the
- <devicename>vinum</devicename> partition on this device.
+ <filename>vinum</filename> partition on this device.
<command>bsdlabel</command> will only allow for this
- overlap if the <devicename>vinum</devicename> partition
+ overlap if the <filename>vinum</filename> partition
has properly been marked using the
<literal>vinum</literal> fstype.</para>
</step>
@@ -1070,8 +1104,8 @@ sd name bigraid.p0.s4 drive e plex bigra
<para>It should be remembered that all files containing control
information must be relative to the root file system in the
- <devicename>vinum</devicename> volume which, when setting up
- a new <devicename>vinum</devicename> root volume, might not
+ <filename>vinum</filename> volume which, when setting up
+ a new <filename>vinum</filename> root volume, might not
match the root file system that is currently active. So in
particular, <filename>/etc/fstab</filename> and
<filename>/boot/loader.conf</filename> need to be taken care
@@ -1079,7 +1113,7 @@ sd name bigraid.p0.s4 drive e plex bigra
<para>At next reboot, the bootstrap should figure out the
appropriate control information from the new
- <devicename>vinum</devicename>-based root file system, and act
+ <filename>vinum</filename>-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:</para>
@@ -1088,10 +1122,10 @@ sd name bigraid.p0.s4 drive e plex bigra
</sect2>
<sect2>
- <title>Example of a <devicename>vinum</devicename>-based Root
+ <title>Example of a <filename>vinum</filename>-based Root
Setup</title>
- <para>After the <devicename>vinum</devicename> root volume has
+ <para>After the <filename>vinum</filename> root volume has
been set up, the output of <command>gvinum l -rv
root</command> could look like:</para>
@@ -1131,18 +1165,18 @@ Subdisk root.p1.s0:
parameter for the faked <literal>a</literal> partition
matches the value outlined above, while the
<literal>offset</literal> parameter is the sum of the offset
- within the <devicename>vinum</devicename> partition
+ within the <filename>vinum</filename> partition
<literal>h</literal>, 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 <xref
linkend="vinum-root-panic"/>. The entire
<literal>a</literal> partition is completely within the
<literal>h</literal> partition containing all the
- <devicename>vinum</devicename> data for this device.</para>
+ <filename>vinum</filename> data for this device.</para>
<para>In the above example, the entire device is dedicated to
- <devicename>vinum</devicename> and there is no leftover
- pre-<devicename>vinum</devicename> root partition.</para>
+ <filename>vinum</filename> and there is no leftover
+ pre-<filename>vinum</filename> root partition.</para>
</sect2>
<sect2>
@@ -1163,7 +1197,7 @@ Subdisk root.p1.s0:
using <command>set</command> or
<command>unset</command>.</para>
- <para>If the <devicename>vinum</devicename> kernel module was
+ <para>If the <filename>vinum</filename> kernel module was
not yet in the list of modules to load automatically, type
<command>load geom_vinum</command>.</para>
@@ -1185,15 +1219,15 @@ Subdisk root.p1.s0:
alternate choice would be something like
<literal>ufs:da0d</literal> which could be a
hypothetical partition containing the
- pre-<devicename>vinum</devicename> root file system. Care
+ pre-<filename>vinum</filename> root file system. Care
should be taken if one of the alias
<literal>a</literal> partitions is entered here, that it
actually references the subdisks of the
- <devicename>vinum</devicename> root device, because in a
+ <filename>vinum</filename> 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 <devicename>vinum</devicename> root volume
+ plex(es) of the <filename>vinum</filename> root volume
since these plexes would otherwise carry inconsistent
data.</para>
</sect3>
@@ -1207,45 +1241,45 @@ Subdisk root.p1.s0:
process starts), an attempt can be made to interrupt the
primary bootstrap by pressing
<keycap>space</keycap>. This will make the bootstrap stop
- in <link linkend="boot-boot1">stage two</link>. An attempt
+ in <link xlink:href="&url.books.handbook;/boot.html#boot-boot1">stage two</link>. 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 <literal>a</literal>.</para>
</sect3>
- <sect3 id="vinum-root-panic">
+ <sect3 xml:id="vinum-root-panic">
<title>Nothing Boots, the Bootstrap
Panics</title>
<para>This situation will happen if the bootstrap had been
- destroyed by the <devicename>vinum</devicename>
- installation. Unfortunately, <devicename>vinum</devicename>
+ destroyed by the <filename>vinum</filename>
+ installation. Unfortunately, <filename>vinum</filename>
accidentally leaves only 4 KB at the beginning of its
partition free before starting to write its
- <devicename>vinum</devicename> header information. However,
+ <filename>vinum</filename> header information. However,
the stage one and two bootstraps plus the bsdlabel require 8
- KB. So if a <devicename>vinum</devicename> partition was
+ KB. So if a <filename>vinum</filename> partition was
started at offset 0 within a slice or disk that was meant to
- be bootable, the <devicename>vinum</devicename> setup will
+ be bootable, the <filename>vinum</filename> setup will
trash the bootstrap.</para>
<para>Similarly, if the above situation has been recovered,
by booting from a <quote>Fixit</quote> media, and the
bootstrap has been re-installed using
- <command>bsdlabel -B</command> as described in <xref
- linkend="boot-boot1"/>, the bootstrap will trash the
- <devicename>vinum</devicename> header, and
- <devicename>vinum</devicename> will no longer find its
- disk(s). Though no actual <devicename>vinum</devicename>
- configuration data or data in <devicename>vinum</devicename>
+ <command>bsdlabel -B</command> as described in <link
+ xlink:href="&url.books.handbook;/boot.html#boot-boot1"/>, the bootstrap will trash the
+ <filename>vinum</filename> header, and
+ <filename>vinum</filename> will no longer find its
+ disk(s). Though no actual <filename>vinum</filename>
+ configuration data or data in <filename>vinum</filename>
volumes will be trashed, and it would be possible to recover
all the data by entering exactly the same
- <devicename>vinum</devicename> configuration data again, the
+ <filename>vinum</filename> configuration data again, the
situation is hard to fix. It is necessary to move the
- entire <devicename>vinum</devicename> partition by at least
- 4 KB, in order to have the <devicename>vinum</devicename>
+ entire <filename>vinum</filename> partition by at least
+ 4 KB, in order to have the <filename>vinum</filename>
header and the system bootstrap no longer collide.</para>
</sect3>
</sect2>
</sect1>
-</chapter>
+</article>
More information about the svn-doc-head
mailing list