From 0572b0a8198650b9b13690119ad7a3d7163e221e Mon Sep 17 00:00:00 2001 From: Joerg Wunsch Date: Fri, 17 Mar 2006 23:42:17 +0000 Subject: [PATCH] Update the Vinum chapter to reflect the change to Gvinum while keeping references to Vinum classic for the sake of people running older systems. --- .../books/handbook/vinum/chapter.sgml | 171 ++++++++---------- 1 file changed, 71 insertions(+), 100 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml index 728160fb7f..0d08d1a521 100644 --- a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml @@ -55,6 +55,22 @@ models both individually and in combination. This chapter provides an overview of potential problems with traditional disk storage, and an introduction to the Vinum Volume Manager. + Starting with FreeBSD 5, Vinum has been rewritten in + order to fit into the GEOM architecture (), + retaining the original ideas, terminology, and on-disk metadata. + This rewrite is called gvinum (for + GEOM vinum). The following text usually refers to + Vinum as an abstract name, regardless of the + implementation variant. Any command invocations should now be + done using the gvinum command, and the name of + the kernel module has been changed from + vinum.ko to + geom_vinum.ko, and all device nodes reside + under /dev/gvinum instead of + /dev/vinum. As of FreeBSD 6, the old Vinum + implementation is no longer available in the code + base. + @@ -457,7 +473,7 @@ disk storage, and an introduction to the Vinum Volume Manager. database which describes the objects known to an individual system. Initially, the user creates the 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 Vinum calls a device) under its control. 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. - After processing this file, &man.vinum.8; produces the following + After processing this file, &man.gvinum.8; produces the following output: - &prompt.root; vinum -> create config1 + &prompt.root; gvinum -> create config1 Configuration summary Drives: 1 (4 configured) Volumes: 1 (4 configured) @@ -537,7 +553,7 @@ disk storage, and an introduction to the Vinum Volume Manager. S myvol.p0.s0 State: up PO: 0 B Size: 512 MB - This output shows the brief listing format of &man.vinum.8;. It + This output shows the brief listing format of &man.gvinum.8;. It is represented graphically in . @@ -745,65 +761,51 @@ disk storage, and an introduction to the Vinum Volume Manager. drives may be up to 32 characters long. Vinum objects are assigned device nodes in the hierarchy - /dev/vinum. The configuration shown above + /dev/gvinum. The configuration shown above would cause Vinum to create the following device nodes: + This only applies to the historic Vinum + implemenation. + The control devices /dev/vinum/control and /dev/vinum/controld, which are used - by &man.vinum.8; and the Vinum daemon respectively. + by &man.gvinum.8; and the Vinum daemon respectively. - Block and character device entries for each volume. - These are the main devices used by Vinum. The block device - names are the name of the volume, while the character device - names follow the BSD tradition of prepending the letter - r to the name. Thus the configuration - above would include the block devices - /dev/vinum/myvol, - /dev/vinum/mirror, - /dev/vinum/striped, - /dev/vinum/raid5 and - /dev/vinum/raid10, and the - character devices - /dev/vinum/rmyvol, - /dev/vinum/rmirror, - /dev/vinum/rstriped, - /dev/vinum/rraid5 and - /dev/vinum/rraid10. There is - obviously a problem here: it is possible to have two volumes - called r and rr, - but there will be a conflict creating the device node - /dev/vinum/rr: is it a character - device for volume r or a block device - for volume rr? Currently Vinum does - not address this conflict: the first-defined volume will get - the name. + Device entries for each volume. + These are the main devices used by Vinum. Thus the configuration + above would include the devices + /dev/gvinum/myvol, + /dev/gvinum/mirror, + /dev/gvinum/striped, + /dev/gvinum/raid5 and + /dev/gvinum/raid10. + This only applies to the historic Vinum + implemenation. + A directory /dev/vinum/drive with entries for each drive. These entries are in fact symbolic links to the corresponding disk nodes. - A directory /dev/vinum/volume with - entries for each volume. It contains subdirectories for - each plex, which in turn contain subdirectories for their - component subdisks. + All volumes get direct entries under + /dev/gvinum/. The directories - /dev/vinum/plex, - /dev/vinum/sd, and - /dev/vinum/rsd, which contain block - device nodes for each plex and block and character device - nodes respectively for each subdisk. + /dev/gvinum/plex, amd + /dev/gvinum/sd, which contain + device nodes for each plex and for each subdisk, + respectively. @@ -820,67 +822,24 @@ disk storage, and an introduction to the Vinum Volume Manager. sd length 100m drive drive3 sd length 100m drive drive4 - After processing this file, &man.vinum.8; creates the following - structure in /dev/vinum: + After processing this file, &man.gvinum.8; creates the following + structure in /dev/gvinum: - 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 - crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 rs64 - 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 + crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64 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 -> /dev/sd1h - lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive2 -> /dev/sd2h - lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive3 -> /dev/sd3h - lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive4 -> /dev/sd4h - /dev/vinum/plex: 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 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, 0x20200002 Apr 13 16:46 s64.p0.s2 - crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3 - - /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 + crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3 Although it is recommended that plexes and subdisks should not be allocated specific names, Vinum drives must be named. @@ -905,14 +864,14 @@ disk storage, and an introduction to the Vinum Volume Manager. eighth partition (h) on the third (2) SCSI disk (da) respectively. By contrast, a Vinum volume might be called - /dev/vinum/concat, a name which has + /dev/gvinum/concat, a name which has no relationship with a partition name. Normally, &man.newfs.8; interprets the name of the disk and complains if it cannot understand it. For example: - &prompt.root; newfs /dev/vinum/concat -newfs: /dev/vinum/concat: can't figure out file system partition + &prompt.root; newfs /dev/gvinum/concat +newfs: /dev/gvinum/concat: can't figure out file system partition The following is only valid for FreeBSD versions prior to 5.0: @@ -920,7 +879,7 @@ newfs: /dev/vinum/concat: can't figure out file system partition In order to create a file system on this volume, use the option to &man.newfs.8;: - &prompt.root; newfs -v /dev/vinum/concat + &prompt.root; newfs -v /dev/gvinum/concat @@ -933,7 +892,7 @@ newfs: /dev/vinum/concat: can't figure out file system partition Vinum, but this is not recommended. The standard way to start Vinum is as a kernel module (kld). You do 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. @@ -981,6 +940,11 @@ sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b dr Automatic Startup + This information only relates to the historic + Vinum implementation. Gvinum always + features an automatic startup once the kernel module is + loaded. + In order to start Vinum automatically when you boot the system, ensure that you have the following line in your /etc/rc.conf: @@ -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 accomplished by putting the line: - vinum_load="YES" + geom_vinum_load="YES" into the file /boot/loader.conf. + For Gvinum, 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. + Vinum must be initialized early since it needs to supply the volume for the root filesystem. By default, 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 volume need to be examined, using the command: - &prompt.root; vinum l -rv root + &prompt.root; gvinum l -rv root Note that Vinum offsets and sizes are measured in 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 message like: - Mounting root from ufs:/dev/vinum/root + Mounting root from ufs:/dev/gvinum/root Example of a Vinum-based Root Setup After the Vinum root volume has been set up, the output of - vinum l -rv root could look like: + gvinum l -rv root could look like: ... @@ -1316,7 +1287,7 @@ Subdisk root.p1.s0: If the only problem was that the Vinum kernel module was not yet in the list of modules to load automatically, a - simple load vinum will help. + simple load geom_vinum will help. When ready, the boot process can be continued with a boot -as. The options @@ -1332,7 +1303,7 @@ Subdisk root.p1.s0: device that contains a valid root filesystem can be entered. If /etc/fstab had been set up correctly, the default should be something like - ufs:/dev/vinum/root. A typical alternate + ufs:/dev/gvinum/root. A typical alternate choice would be something like ufs:da0d which could be a hypothetical partition that contains the pre-Vinum root