os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update the Vinum chapter to reflect the change to Gvinum while keeping

Browse source 
references to Vinum classic for the sake of people running older
systems.
This commit is contained in:
Joerg Wunsch 2006-03-17 23:42:17 +00:00
parent a7258cf2cd
commit 0572b0a819
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=27365
1 changed files with 71 additions and 100 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

171
en_US.ISO8859-1/books/handbook/vinum/chapter.sgml
View file

@ -55,6 +55,22 @@ models both individually and in combination.</para>
<para>This chapter provides an overview of potential problems with traditional <para>This chapter provides an overview of potential problems with traditional
disk storage, and an introduction to the Vinum Volume Manager.</para> disk storage, and an introduction to the Vinum Volume Manager.</para>
<note><para>Starting with FreeBSD 5, Vinum has been rewritten in
order to fit into the GEOM architecture (<xref linkend="GEOM">),
retaining the original ideas, terminology, and on-disk metadata.
This rewrite is called <emphasis>gvinum</emphasis> (for <emphasis>
GEOM vinum</emphasis>). The following text usually refers to
<emphasis>Vinum</emphasis> as an abstract name, regardless of the
implementation variant. Any command invocations should now be
done using the <command>gvinum</command> command, and the name of
the kernel module has been changed from
<filename>vinum.ko</filename> to
<filename>geom_vinum.ko</filename>, and all device nodes reside
under <filename>/dev/gvinum</filename> instead of
<filename>/dev/vinum</filename>. As of FreeBSD 6, the old Vinum
implementation is no longer available in the code
base.</para></note>
</sect1> </sect1>
<sect1 id="vinum-intro"> <sect1 id="vinum-intro">
@ -457,7 +473,7 @@ disk storage, and an introduction to the Vinum Volume Manager.</para>
database</emphasis> which describes the objects known to an database</emphasis> which describes the objects known to an
individual system. Initially, the user creates the individual system. Initially, the user creates the
configuration database from one or more configuration files with configuration database from one or more configuration files with
the aid of the &man.vinum.8; utility program. Vinum stores a the aid of the &man.gvinum.8; utility program. Vinum stores a
copy of its configuration database on each disk slice (which copy of its configuration database on each disk slice (which
Vinum calls a <emphasis>device</emphasis>) under its control. Vinum calls a <emphasis>device</emphasis>) under its control.
This database is updated on each state change, so that a restart This database is updated on each state change, so that a restart
@ -518,11 +534,11 @@ disk storage, and an introduction to the Vinum Volume Manager.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>After processing this file, &man.vinum.8; produces the following <para>After processing this file, &man.gvinum.8; produces the following
output:</para> output:</para>
<programlisting width="97"> <programlisting width="97">
&prompt.root; vinum -&gt; <userinput>create config1</userinput> &prompt.root; gvinum -&gt; <userinput>create config1</userinput>
Configuration summary Configuration summary
Drives: 1 (4 configured) Drives: 1 (4 configured)
Volumes: 1 (4 configured) Volumes: 1 (4 configured)
@ -537,7 +553,7 @@ disk storage, and an introduction to the Vinum Volume Manager.</para>
S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting> S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting>
<para>This output shows the brief listing format of &man.vinum.8;. It <para>This output shows the brief listing format of &man.gvinum.8;. It
is represented graphically in <xref linkend="vinum-simple-vol">.</para> is represented graphically in <xref linkend="vinum-simple-vol">.</para>
<para> <para>
@ -745,65 +761,51 @@ disk storage, and an introduction to the Vinum Volume Manager.</para>
drives may be up to 32 characters long.</para> drives may be up to 32 characters long.</para>
<para>Vinum objects are assigned device nodes in the hierarchy <para>Vinum objects are assigned device nodes in the hierarchy
<filename>/dev/vinum</filename>. The configuration shown above <filename>/dev/gvinum</filename>. The configuration shown above
would cause Vinum to create the following device nodes:</para> would cause Vinum to create the following device nodes:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<note><para>This only applies to the historic Vinum
implemenation.</para></note>
<para>The control devices <para>The control devices
<filename>/dev/vinum/control</filename> and <filename>/dev/vinum/control</filename> and
<filename>/dev/vinum/controld</filename>, which are used <filename>/dev/vinum/controld</filename>, which are used
by &man.vinum.8; and the Vinum daemon respectively.</para> by &man.gvinum.8; and the Vinum daemon respectively.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Block and character device entries for each volume. <para>Device entries for each volume.
These are the main devices used by Vinum. The block device These are the main devices used by Vinum. Thus the configuration
names are the name of the volume, while the character device above would include the devices
names follow the BSD tradition of prepending the letter <filename>/dev/gvinum/myvol</filename>,
<emphasis>r</emphasis> to the name. Thus the configuration <filename>/dev/gvinum/mirror</filename>,
above would include the block devices <filename>/dev/gvinum/striped</filename>,
<filename>/dev/vinum/myvol</filename>, <filename>/dev/gvinum/raid5</filename> and
<filename>/dev/vinum/mirror</filename>, <filename>/dev/gvinum/raid10</filename>.</para>
<filename>/dev/vinum/striped</filename>,
<filename>/dev/vinum/raid5</filename> and
<filename>/dev/vinum/raid10</filename>, and the
character devices
<filename>/dev/vinum/rmyvol</filename>,
<filename>/dev/vinum/rmirror</filename>,
<filename>/dev/vinum/rstriped</filename>,
<filename>/dev/vinum/rraid5</filename> and
<filename>/dev/vinum/rraid10</filename>. There is
obviously a problem here: it is possible to have two volumes
called <emphasis>r</emphasis> and <emphasis>rr</emphasis>,
but there will be a conflict creating the device node
<filename>/dev/vinum/rr</filename>: is it a character
device for volume <emphasis>r</emphasis> or a block device
for volume <emphasis>rr</emphasis>? Currently Vinum does
not address this conflict: the first-defined volume will get
the name.</para>
</listitem> </listitem>
<listitem> <listitem>
<note><para>This only applies to the historic Vinum
implemenation.</para></note>
<para>A directory <filename>/dev/vinum/drive</filename> <para>A directory <filename>/dev/vinum/drive</filename>
with entries for each drive. These entries are in fact with entries for each drive. These entries are in fact
symbolic links to the corresponding disk nodes.</para> symbolic links to the corresponding disk nodes.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>A directory <filename>/dev/vinum/volume</filename> with <para>All volumes get direct entries under
entries for each volume. It contains subdirectories for <filename>/dev/gvinum/</filename>.</para>
each plex, which in turn contain subdirectories for their
component subdisks.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The directories <para>The directories
<filename>/dev/vinum/plex</filename>, <filename>/dev/gvinum/plex</filename>, amd
<filename>/dev/vinum/sd</filename>, and <filename>/dev/gvinum/sd</filename>, which contain
<filename>/dev/vinum/rsd</filename>, which contain block device nodes for each plex and for each subdisk,
device nodes for each plex and block and character device respectively.</para>
nodes respectively for each subdisk.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -820,67 +822,24 @@ disk storage, and an introduction to the Vinum Volume Manager.</para>
sd length 100m drive drive3 sd length 100m drive drive3
sd length 100m drive drive4</programlisting> sd length 100m drive drive4</programlisting>
<para>After processing this file, &man.vinum.8; creates the following <para>After processing this file, &man.gvinum.8; creates the following
structure in <filename>/dev/vinum</filename>:</para> structure in <filename>/dev/gvinum</filename>:</para>
<programlisting> <programlisting>
brwx------ 1 root wheel 25, 0x40000001 Apr 13 16:46 Control
brwx------ 1 root wheel 25, 0x40000002 Apr 13 16:46 control
brwx------ 1 root wheel 25, 0x40000000 Apr 13 16:46 controld
drwxr-xr-x 2 root wheel 512 Apr 13 16:46 drive
drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex
crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 rs64 crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64
drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rsd
drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rvol
brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64
drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd
drwxr-xr-x 3 root wheel 512 Apr 13 16:46 vol
/dev/vinum/drive:
total 0
lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive1 -&gt; /dev/sd1h
lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive2 -&gt; /dev/sd2h
lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive3 -&gt; /dev/sd3h
lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive4 -&gt; /dev/sd4h
/dev/vinum/plex: /dev/vinum/plex:
total 0 total 0
brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
/dev/vinum/rsd: /dev/vinum/sd:
total 0 total 0
crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0 crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0
crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1 crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1
crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2 crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2
crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3 crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting>
/dev/vinum/rvol:
total 0
crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64
/dev/vinum/sd:
total 0
brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0
brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1
brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2
brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3
/dev/vinum/vol:
total 1
brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64
drwxr-xr-x 3 root wheel 512 Apr 13 16:46 s64.plex
/dev/vinum/vol/s64.plex:
total 1
brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
drwxr-xr-x 2 root wheel 512 Apr 13 16:46 s64.p0.sd
/dev/vinum/vol/s64.plex/s64.p0.sd:
total 0
brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0
brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1
brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2
brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting>
<para>Although it is recommended that plexes and subdisks should <para>Although it is recommended that plexes and subdisks should
not be allocated specific names, Vinum drives must be named. not be allocated specific names, Vinum drives must be named.
@ -905,14 +864,14 @@ disk storage, and an introduction to the Vinum Volume Manager.</para>
eighth partition (<devicename>h</devicename>) on the third eighth partition (<devicename>h</devicename>) on the third
(2) SCSI disk (<devicename>da</devicename>) respectively. (2) SCSI disk (<devicename>da</devicename>) respectively.
By contrast, a Vinum volume might be called By contrast, a Vinum volume might be called
<filename>/dev/vinum/concat</filename>, a name which has <filename>/dev/gvinum/concat</filename>, a name which has
no relationship with a partition name.</para> no relationship with a partition name.</para>
<para>Normally, &man.newfs.8; interprets the name of the disk and <para>Normally, &man.newfs.8; interprets the name of the disk and
complains if it cannot understand it. For example:</para> complains if it cannot understand it. For example:</para>
<screen>&prompt.root; <userinput>newfs /dev/vinum/concat</userinput> <screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput>
newfs: /dev/vinum/concat: can't figure out file system partition</screen> newfs: /dev/gvinum/concat: can't figure out file system partition</screen>
<note><para>The following is only valid for FreeBSD versions <note><para>The following is only valid for FreeBSD versions
prior to 5.0:</para></note> prior to 5.0:</para></note>
@ -920,7 +879,7 @@ newfs: /dev/vinum/concat: can't figure out file system partition</screen>
<para>In order to create a file system on this volume, use the <para>In order to create a file system on this volume, use the
<option>-v</option> option to &man.newfs.8;:</para> <option>-v</option> option to &man.newfs.8;:</para>
<screen>&prompt.root; <userinput>newfs -v /dev/vinum/concat</userinput></screen> <screen>&prompt.root; <userinput>newfs -v /dev/gvinum/concat</userinput></screen>
</sect2> </sect2>
</sect1> </sect1>
@ -933,7 +892,7 @@ newfs: /dev/vinum/concat: can't figure out file system partition</screen>
Vinum, but this is not recommended. The standard way to start Vinum, but this is not recommended. The standard way to start
Vinum is as a kernel module (<acronym>kld</acronym>). You do Vinum is as a kernel module (<acronym>kld</acronym>). You do
not even need to use &man.kldload.8; for Vinum: when you start not even need to use &man.kldload.8; for Vinum: when you start
&man.vinum.8;, it checks whether the module has been loaded, and &man.gvinum.8;, it checks whether the module has been loaded, and
if it is not, it loads it automatically.</para> if it is not, it loads it automatically.</para>
@ -981,6 +940,11 @@ sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b dr
<sect3 id="vinum-rc-startup"> <sect3 id="vinum-rc-startup">
<title>Automatic Startup</title> <title>Automatic Startup</title>
<note><para>This information only relates to the historic
Vinum implementation. <emphasis>Gvinum</emphasis> always
features an automatic startup once the kernel module is
loaded.</para></note>
<para>In order to start Vinum automatically when you boot the <para>In order to start Vinum automatically when you boot the
system, ensure that you have the following line in your system, ensure that you have the following line in your
<filename>/etc/rc.conf</filename>:</para> <filename>/etc/rc.conf</filename>:</para>
@ -1063,13 +1027,20 @@ sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b dr
early, before starting the kernel. This can be early, before starting the kernel. This can be
accomplished by putting the line:</para> accomplished by putting the line:</para>
<programlisting>vinum_load="YES"</programlisting> <programlisting>geom_vinum_load="YES"</programlisting>
<para>into the file <para>into the file
<filename>/boot/loader.conf</filename>.</para> <filename>/boot/loader.conf</filename>.</para>
</listitem> </listitem>
<listitem> <listitem>
<note><para>For <emphasis>Gvinum</emphasis>, all startup
is done automatically once the kernel module has been
loaded, so the procedure described above is all that is
needed. The following text documents the behaviour of
the historic Vinum system, for the sake of older
setups.</para></note>
<para>Vinum must be initialized early since it needs to <para>Vinum must be initialized early since it needs to
supply the volume for the root filesystem. By default, supply the volume for the root filesystem. By default,
the Vinum kernel part is not looking for drives that might the Vinum kernel part is not looking for drives that might
@ -1155,7 +1126,7 @@ sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b dr
and size of this device's subdisk that is part of the root and size of this device's subdisk that is part of the root
volume need to be examined, using the command:</para> volume need to be examined, using the command:</para>
<screen>&prompt.root; <userinput>vinum l -rv root</userinput></screen> <screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen>
<para>Note that Vinum offsets and sizes are measured in <para>Note that Vinum offsets and sizes are measured in
bytes. They must be divided by 512 in order to obtain the bytes. They must be divided by 512 in order to obtain the
@ -1234,14 +1205,14 @@ sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b dr
the prominent notice that shows the success of this setup is a the prominent notice that shows the success of this setup is a
message like:</para> message like:</para>
<screen>Mounting root from ufs:/dev/vinum/root</screen> <screen>Mounting root from ufs:/dev/gvinum/root</screen>
</sect2> </sect2>
<sect2> <sect2>
<title>Example of a Vinum-based Root Setup</title> <title>Example of a Vinum-based Root Setup</title>
<para>After the Vinum root volume has been set up, the output of <para>After the Vinum root volume has been set up, the output of
<command>vinum l -rv root</command> could look like:</para> <command>gvinum l -rv root</command> could look like:</para>
<screen> <screen>
... ...
@ -1316,7 +1287,7 @@ Subdisk root.p1.s0:
<para>If the only problem was that the Vinum kernel module was <para>If the only problem was that the Vinum kernel module was
not yet in the list of modules to load automatically, a not yet in the list of modules to load automatically, a
simple <command>load vinum</command> will help.</para> simple <command>load geom_vinum</command> will help.</para>
<para>When ready, the boot process can be continued with a <para>When ready, the boot process can be continued with a
<command>boot -as</command>. The options <command>boot -as</command>. The options
@ -1332,7 +1303,7 @@ Subdisk root.p1.s0:
device that contains a valid root filesystem can be entered. device that contains a valid root filesystem can be entered.
If <filename>/etc/fstab</filename> had been set up If <filename>/etc/fstab</filename> had been set up
correctly, the default should be something like correctly, the default should be something like
<literal>ufs:/dev/vinum/root</literal>. A typical alternate <literal>ufs:/dev/gvinum/root</literal>. A typical alternate
choice would be something like choice would be something like
<literal>ufs:da0d</literal> which could be a <literal>ufs:da0d</literal> which could be a
hypothetical partition that contains the pre-Vinum root hypothetical partition that contains the pre-Vinum root