Date: Wed, 25 Feb 2015 19:22:05 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201502251922.t1PJM5dB081414@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201502251922.t1PJM5dB081414>