1 .\" Hey, Emacs, edit this file in -*- nroff-fill -*- mode
3 .\" Copyright (c) 1997, 1998, 2003
4 .\" Nan Yang Computer Services Limited. All rights reserved.
6 .\" This software is distributed under the so-called ``Berkeley
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by Nan Yang Computer
21 .\" 4. Neither the name of the Company nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
25 .\" This software is provided ``as is'', and any express or implied
26 .\" warranties, including, but not limited to, the implied warranties of
27 .\" merchantability and fitness for a particular purpose are disclaimed.
28 .\" In no event shall the company or contributors be liable for any
29 .\" direct, indirect, incidental, special, exemplary, or consequential
30 .\" damages (including, but not limited to, procurement of substitute
31 .\" goods or services; loss of use, data, or profits; or business
32 .\" interruption) however caused and on any theory of liability, whether
33 .\" in contract, strict liability, or tort (including negligence or
34 .\" otherwise) arising in any way out of the use of this software, even if
35 .\" advised of the possibility of such damage.
44 .Nd Logical Volume Manager
49 is a logical volume manager inspired by, but not derived from, the Veritas
51 It provides the following features:
54 It provides device-independent logical disks, called
57 not restricted to the size of any disk on the system.
59 The volumes consist of one or more
61 each of which contain the
62 entire address space of a volume.
63 This represents an implementation of RAID-1
65 Multiple plexes can also be used for:
66 .\" XXX What about sparse plexes? Do we want them?
69 Increased read throughput.
71 will read data from the least active disk, so if a volume has plexes on multiple
72 disks, more data can be read in parallel.
74 reads data from only one plex, but it writes data to all plexes.
76 Increased reliability.
77 By storing plexes on different disks, data will remain
78 available even if one of the plexes becomes unavailable.
80 RAID-5 plex (see below), using multiple plexes requires more storage space, but
81 gives better performance, particularly in the case of a drive failure.
83 Additional plexes can be used for on-line data reorganization.
85 additional plex and subsequently detaching one of the older plexes, data can be
86 moved on-line without compromising access.
88 An additional plex can be used to obtain a consistent dump of a file system.
90 attaching an additional plex and detaching at a specific time, the detached plex
91 becomes an accurate snapshot of the file system at the time of detachment.
92 .\" Make sure to flush!
95 Each plex consists of one or more logical disk slices, called
97 Subdisks are defined as a contiguous block of physical disk storage.
99 consist of any reasonable number of subdisks (in other words, the real limit is
100 not the number, but other factors, such as memory and performance, associated
101 with maintaining a large number of subdisks).
103 A number of mappings between subdisks and plexes are available:
106 .Em "Concatenated plexes"
107 consist of one or more subdisks, each of which
108 is mapped to a contiguous part of the plex address space.
111 consist of two or more subdisks of equal size.
113 address space is mapped in
115 integral fractions of the subdisk
117 Consecutive plex address space is mapped to stripes in each subdisk in
131 "plex 0" at SD0.n+(0,.2)
132 "subdisk 0" rjust at SD0.w-(.2,0)
133 "subdisk 1" rjust at SD1.w-(.2,0)
134 "subdisk 2" rjust at SD2.w-(.2,0)
138 The subdisks of a striped plex must all be the same size.
141 require at least three equal-sized subdisks.
143 resemble striped plexes, except that in each stripe, one subdisk stores parity
145 This subdisk changes in each stripe: in the first stripe, it is the
146 first subdisk, in the second it is the second subdisk, etc.
150 will recover the data based on the information stored on the remaining subdisks.
151 This mapping is particularly suited to read-intensive access.
153 RAID-5 plex must all be the same size.
154 .\" Make sure to flush!
158 are the lowest level of the storage hierarchy.
159 They represent disk special
163 offers automatic startup.
168 volumes contain all the configuration information needed to ensure that they are
169 started correctly when the subsystem is enabled.
170 This is also a significant
171 advantage over the Veritas\(tm File System.
172 This feature regards the presence
174 It does not mean that the volumes will be mounted
175 automatically, since the standard startup procedures with
177 perform this function.
179 .Sh KERNEL CONFIGURATION
181 is currently supplied as a KLD module, and does not require
183 As with other KLDs, it is absolutely necessary to match the KLD
184 to the version of the operating system.
185 Failure to do so will cause
187 to issue an error message and terminate.
189 It is possible to configure
191 in the kernel, but this is not recommended.
192 To do so, add this line to the
193 kernel configuration file:
195 .D1 Cd "device vinum"
197 The current version of
199 both the kernel module and the user program
201 include significant debugging support.
202 It is not recommended to remove
203 this support at the moment, but if you do you must remove it from both the
204 kernel and the user components.
205 To do this, edit the files
206 .Pa /usr/src/sbin/vinum/Makefile
208 .Pa /usr/src/sys/modules/vinum/Makefile
211 variable to remove the
217 into the kernel, either specify the line
219 .D1 Cd "options VINUMDEBUG"
221 in the kernel configuration file or remove the
224 .Pa /usr/src/sbin/vinum/Makefile
229 variables do not match,
231 will fail with a message
232 explaining the problem and what to do to correct it.
234 .Cd "options VINUM_AUTOSTART"
238 automatically scan all available disks at attach time.
239 This is a deprecated way that is primarily intended for environments
240 that do not want to rely on kernel environment variables set by
244 was previously available in two versions: a freely available version which did
245 not contain RAID-5 functionality, and a full version including RAID-5
246 functionality, which was available only from Cybernet Systems Inc.
250 includes the RAID-5 functionality.
256 It does not require installation.
257 To start it, start the
259 program, which will load the KLD if it is not already present.
262 it must be configured.
265 for information on how to create a
269 Normally, you start a configured version of
287 is loaded as a KLD (the recommended way), the
289 command will unload it
292 You can also do this with the
296 The KLD can only be unloaded when idle, in other words when no volumes are
297 mounted and no other instances of the
300 Unloading the KLD does not harm the data in the volumes.
301 .Ss Configuring and Starting Objects
304 utility to configure and start
307 .Sh AUTOMATIC STARTUP
310 subsystem can be automatically started at attach time.
311 There are two kernel environment variables that can be set in
314 .Bl -tag -width ".Va vinum.autostart" -offset indent
315 .It Va vinum.autostart
316 If this variable is set (to any value), the attach function will attempt
317 to scan all available disks for valid
319 configuration records.
320 This is the preferred way if automatic startup is desired.
323 .Dl vinum.autostart="YES"
325 Alternatively, this variable can enumerate a list of disk devices
326 to scan for configuration records.
329 device names need to be given, since
331 will automatically scan all possible slices and partitions.
334 .Dl vinum.drives="da0 da1"
337 If automatic startup is used, it is not necessary to set the
343 is to supply to the volume for the root file system, it is necessary
344 to start the subsystem early.
345 This can be achieved by specifying
353 calls are intended for the use of the
355 configuration program only.
356 They are described in the header file
357 .Pa /sys/dev/vinum/vinumio.h .
359 Conventional disk special devices have a
361 in the second sector of the device.
362 This disk label describes the layout of the partitions within
365 does not subdivide volumes, so volumes do not contain a physical disk label.
368 implements the ioctl calls
372 (get partition information),
374 (write partition information) and
376 (set partition information).
381 representation of the disk label which is not present on the volume.
393 serves no useful purpose on a
396 If you run it, it will show you
402 all the same except for the
407 # size offset fstype [fsize bsize bps/cpg]
408 a: 2048 0 4.2BSD 1024 8192 0 # (Cyl. 0 - 0)
409 b: 2048 0 swap # (Cyl. 0 - 0)
410 c: 2048 0 unused 0 0 # (Cyl. 0 - 0)
418 ioctls, since there is nothing to change.
419 As a result, any attempt to modify the disk label will be silently ignored.
420 .Sh MAKING FILE SYSTEMS
423 volumes do not contain partitions, the names do not need to conform to the
424 standard rules for naming disk partitions.
425 For a physical disk partition, the
426 last letter of the device name specifies the partition identifier (a to h).
428 volumes need not conform to this convention, but if they do not,
430 will complain that it cannot determine the partition.
431 To solve this problem,
436 For example, if you have a volume
438 use the following command to create a UFS file system on it:
440 .Dl "newfs -v /dev/vinum/concat"
443 assigns default names to plexes and subdisks, although they may be overridden.
444 We do not recommend overriding the default names.
447 volume manager, which allows arbitrary naming of objects, has shown that this
448 flexibility does not bring a significant advantage, and it can cause confusion.
450 Names may contain any non-blank character, but it is recommended to restrict
451 them to letters, digits and the underscore characters.
452 The names of volumes,
453 plexes and subdisks may be up to 64 characters long, and the names of drives may
454 up to 32 characters long.
455 When choosing volume and plex names, bear in mind
456 that automatically generated plex and subdisk names are longer than the name
457 from which they are derived.
462 creates or deletes objects, it creates a directory
464 in which it makes device entries for each volume it finds.
470 in which it stores device entries for plexes and subdisks.
471 In addition, it creates two more directories,
474 .Pa /dev/vinum/drive ,
475 in which it stores hierarchical information for volumes and drives.
479 creates three super-devices,
480 .Pa /dev/vinum/control ,
481 .Pa /dev/vinum/Control
483 .Pa /dev/vinum/controld .
484 .Pa /dev/vinum/control
487 when it has been compiled without the
490 .Pa /dev/vinum/Control
493 when it has been compiled with the
496 .Pa /dev/vinum/controld
500 The two control devices for
502 are used to synchronize the debug status of kernel and user modules.
508 volumes are not subdivided into partitions, and thus do not contain a disk
510 Unfortunately, this confuses a number of utilities, notably
512 which normally tries to interpret the last letter of a
514 volume name as a partition identifier.
515 If you use a volume name which does not
524 in order to tell it to ignore this convention.
527 Plexes do not need to be assigned explicit names.
528 By default, a plex name is
529 the name of the volume followed by the letters
531 and the number of the
533 For example, the plexes of volume
536 .Pa vol3.p0 , vol3.p1
538 These names can be overridden, but it is not recommended.
540 Like plexes, subdisks are assigned names automatically, and explicit naming is
542 A subdisk name is the name of the plex followed by the letters
544 and a number identifying the subdisk.
545 For example, the subdisks of
549 .Pa vol3.p0.s0 , vol3.p0.s1
555 This makes it possible to move a drive to a different location
556 and still recognize it automatically.
557 Drive names may be up to 32 characters
563 objects described in the section
564 .Sx "CONFIGURATION FILE"
570 .Bd -literal -offset indent
573 brwxr-xr-- 1 root wheel 25, 2 Mar 30 16:08 concat
574 brwx------ 1 root wheel 25, 0x40000000 Mar 30 16:08 control
575 brwx------ 1 root wheel 25, 0x40000001 Mar 30 16:08 controld
576 drwxrwxrwx 2 root wheel 512 Mar 30 16:08 drive
577 drwxrwxrwx 2 root wheel 512 Mar 30 16:08 plex
578 drwxrwxrwx 2 root wheel 512 Mar 30 16:08 rvol
579 drwxrwxrwx 2 root wheel 512 Mar 30 16:08 sd
580 brwxr-xr-- 1 root wheel 25, 3 Mar 30 16:08 strcon
581 brwxr-xr-- 1 root wheel 25, 1 Mar 30 16:08 stripe
582 brwxr-xr-- 1 root wheel 25, 0 Mar 30 16:08 tinyvol
583 drwxrwxrwx 7 root wheel 512 Mar 30 16:08 vol
584 brwxr-xr-- 1 root wheel 25, 4 Mar 30 16:08 vol5
588 brw-r----- 1 root operator 4, 15 Oct 21 16:51 drive2
589 brw-r----- 1 root operator 4, 31 Oct 21 16:51 drive4
593 brwxr-xr-- 1 root wheel 25, 0x10000002 Mar 30 16:08 concat.p0
594 brwxr-xr-- 1 root wheel 25, 0x10010002 Mar 30 16:08 concat.p1
595 brwxr-xr-- 1 root wheel 25, 0x10000003 Mar 30 16:08 strcon.p0
596 brwxr-xr-- 1 root wheel 25, 0x10010003 Mar 30 16:08 strcon.p1
597 brwxr-xr-- 1 root wheel 25, 0x10000001 Mar 30 16:08 stripe.p0
598 brwxr-xr-- 1 root wheel 25, 0x10000000 Mar 30 16:08 tinyvol.p0
599 brwxr-xr-- 1 root wheel 25, 0x10000004 Mar 30 16:08 vol5.p0
600 brwxr-xr-- 1 root wheel 25, 0x10010004 Mar 30 16:08 vol5.p1
604 brwxr-xr-- 1 root wheel 25, 0x20000002 Mar 30 16:08 concat.p0.s0
605 brwxr-xr-- 1 root wheel 25, 0x20100002 Mar 30 16:08 concat.p0.s1
606 brwxr-xr-- 1 root wheel 25, 0x20010002 Mar 30 16:08 concat.p1.s0
607 brwxr-xr-- 1 root wheel 25, 0x20000003 Mar 30 16:08 strcon.p0.s0
608 brwxr-xr-- 1 root wheel 25, 0x20100003 Mar 30 16:08 strcon.p0.s1
609 brwxr-xr-- 1 root wheel 25, 0x20010003 Mar 30 16:08 strcon.p1.s0
610 brwxr-xr-- 1 root wheel 25, 0x20110003 Mar 30 16:08 strcon.p1.s1
611 brwxr-xr-- 1 root wheel 25, 0x20000001 Mar 30 16:08 stripe.p0.s0
612 brwxr-xr-- 1 root wheel 25, 0x20100001 Mar 30 16:08 stripe.p0.s1
613 brwxr-xr-- 1 root wheel 25, 0x20000000 Mar 30 16:08 tinyvol.p0.s0
614 brwxr-xr-- 1 root wheel 25, 0x20100000 Mar 30 16:08 tinyvol.p0.s1
615 brwxr-xr-- 1 root wheel 25, 0x20000004 Mar 30 16:08 vol5.p0.s0
616 brwxr-xr-- 1 root wheel 25, 0x20100004 Mar 30 16:08 vol5.p0.s1
617 brwxr-xr-- 1 root wheel 25, 0x20010004 Mar 30 16:08 vol5.p1.s0
618 brwxr-xr-- 1 root wheel 25, 0x20110004 Mar 30 16:08 vol5.p1.s1
622 brwxr-xr-- 1 root wheel 25, 2 Mar 30 16:08 concat
623 drwxr-xr-x 4 root wheel 512 Mar 30 16:08 concat.plex
624 brwxr-xr-- 1 root wheel 25, 3 Mar 30 16:08 strcon
625 drwxr-xr-x 4 root wheel 512 Mar 30 16:08 strcon.plex
626 brwxr-xr-- 1 root wheel 25, 1 Mar 30 16:08 stripe
627 drwxr-xr-x 3 root wheel 512 Mar 30 16:08 stripe.plex
628 brwxr-xr-- 1 root wheel 25, 0 Mar 30 16:08 tinyvol
629 drwxr-xr-x 3 root wheel 512 Mar 30 16:08 tinyvol.plex
630 brwxr-xr-- 1 root wheel 25, 4 Mar 30 16:08 vol5
631 drwxr-xr-x 4 root wheel 512 Mar 30 16:08 vol5.plex
633 /dev/vinum/vol/concat.plex:
635 brwxr-xr-- 1 root wheel 25, 0x10000002 Mar 30 16:08 concat.p0
636 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 concat.p0.sd
637 brwxr-xr-- 1 root wheel 25, 0x10010002 Mar 30 16:08 concat.p1
638 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 concat.p1.sd
640 /dev/vinum/vol/concat.plex/concat.p0.sd:
642 brwxr-xr-- 1 root wheel 25, 0x20000002 Mar 30 16:08 concat.p0.s0
643 brwxr-xr-- 1 root wheel 25, 0x20100002 Mar 30 16:08 concat.p0.s1
645 /dev/vinum/vol/concat.plex/concat.p1.sd:
647 brwxr-xr-- 1 root wheel 25, 0x20010002 Mar 30 16:08 concat.p1.s0
649 /dev/vinum/vol/strcon.plex:
651 brwxr-xr-- 1 root wheel 25, 0x10000003 Mar 30 16:08 strcon.p0
652 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 strcon.p0.sd
653 brwxr-xr-- 1 root wheel 25, 0x10010003 Mar 30 16:08 strcon.p1
654 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 strcon.p1.sd
656 /dev/vinum/vol/strcon.plex/strcon.p0.sd:
658 brwxr-xr-- 1 root wheel 25, 0x20000003 Mar 30 16:08 strcon.p0.s0
659 brwxr-xr-- 1 root wheel 25, 0x20100003 Mar 30 16:08 strcon.p0.s1
661 /dev/vinum/vol/strcon.plex/strcon.p1.sd:
663 brwxr-xr-- 1 root wheel 25, 0x20010003 Mar 30 16:08 strcon.p1.s0
664 brwxr-xr-- 1 root wheel 25, 0x20110003 Mar 30 16:08 strcon.p1.s1
666 /dev/vinum/vol/stripe.plex:
668 brwxr-xr-- 1 root wheel 25, 0x10000001 Mar 30 16:08 stripe.p0
669 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 stripe.p0.sd
671 /dev/vinum/vol/stripe.plex/stripe.p0.sd:
673 brwxr-xr-- 1 root wheel 25, 0x20000001 Mar 30 16:08 stripe.p0.s0
674 brwxr-xr-- 1 root wheel 25, 0x20100001 Mar 30 16:08 stripe.p0.s1
676 /dev/vinum/vol/tinyvol.plex:
678 brwxr-xr-- 1 root wheel 25, 0x10000000 Mar 30 16:08 tinyvol.p0
679 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 tinyvol.p0.sd
681 /dev/vinum/vol/tinyvol.plex/tinyvol.p0.sd:
683 brwxr-xr-- 1 root wheel 25, 0x20000000 Mar 30 16:08 tinyvol.p0.s0
684 brwxr-xr-- 1 root wheel 25, 0x20100000 Mar 30 16:08 tinyvol.p0.s1
686 /dev/vinum/vol/vol5.plex:
688 brwxr-xr-- 1 root wheel 25, 0x10000004 Mar 30 16:08 vol5.p0
689 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 vol5.p0.sd
690 brwxr-xr-- 1 root wheel 25, 0x10010004 Mar 30 16:08 vol5.p1
691 drwxr-xr-x 2 root wheel 512 Mar 30 16:08 vol5.p1.sd
693 /dev/vinum/vol/vol5.plex/vol5.p0.sd:
695 brwxr-xr-- 1 root wheel 25, 0x20000004 Mar 30 16:08 vol5.p0.s0
696 brwxr-xr-- 1 root wheel 25, 0x20100004 Mar 30 16:08 vol5.p0.s1
698 /dev/vinum/vol/vol5.plex/vol5.p1.sd:
700 brwxr-xr-- 1 root wheel 25, 0x20010004 Mar 30 16:08 vol5.p1.s0
701 brwxr-xr-- 1 root wheel 25, 0x20110004 Mar 30 16:08 vol5.p1.s1
704 In the case of unattached plexes and subdisks, the naming is reversed.
706 are named after the disk on which they are located, and plexes are named after
710 This mapping is still to be determined.
719 uses this state to determine the handling of the object.
721 Volumes may have the following states:
724 The volume is completely inaccessible.
726 The volume is up and at least partially functional.
727 Not all plexes may be
731 Plexes may have the following states:
734 A plex entry which has been referenced as part of a volume, but which is
737 A plex which has gone completely down because of I/O errors.
739 A plex which has been taken down by the administrator.
741 A plex which is being initialized.
744 The remaining states represent plexes which are at least partially up.
747 A plex entry which is at least partially up.
748 Not all subdisks are available,
749 and an inconsistency has occurred.
750 If no other plex is uncorrupted, the volume
751 is no longer consistent.
753 A RAID-5 plex entry which is accessible, but one subdisk is down, requiring
754 recovery for many I/O requests.
756 A plex which is really up, but which has a reborn subdisk which we do not
757 completely trust, and which we do not want to read if we can avoid it.
759 A plex entry which is completely up.
763 Subdisks can have the following states:
766 A subdisk entry which has been created completely.
767 All fields are correct, and
768 the disk has been updated, but the on the disk is not valid.
770 A subdisk entry which has been referenced as part of a plex, but which is
773 A subdisk entry which has been created completely and which is currently being
777 The following states represent invalid data.
780 A subdisk entry which has been created completely.
781 All fields are correct, the
782 config on disk has been updated, and the data was valid, but since then the
783 drive has been taken down, and as a result updates have been missed.
785 A subdisk entry which has been created completely.
786 All fields are correct, the
787 disk has been updated, and the data was valid, but since then the drive has been
788 crashed and updates have been lost.
791 The following states represent valid, inaccessible data.
794 A subdisk entry which has been created completely.
795 All fields are correct, the
796 disk has been updated, and the data was valid, but since then the drive has gone
798 No attempt has been made to write to the subdisk since the crash, so the
801 A subdisk entry which was up, which contained valid data, and which was taken
802 down by the administrator.
805 The subdisk is currently in the process of being revived.
810 The following states represent accessible subdisks with valid data.
813 A subdisk entry which has been created completely.
814 All fields are correct, the
815 disk has been updated, and the data was valid, but since then the drive has gone
817 No updates were lost, but it is possible that the subdisk
819 We will not read from this subdisk if we have a choice.
821 is the only subdisk which covers this address space in the plex, we set its
822 state to up under these circumstances, so this status implies that there is
823 another subdisk to fulfill the request.
825 A subdisk entry which has been created completely.
826 All fields are correct, the
827 disk has been updated, and the data is valid.
830 Drives can have the following states:
833 At least one subdisk refers to the drive, but it is not currently accessible to
835 No device name is known.
837 The drive is not accessible.
839 The drive is up and running.
851 The RAID-5 component of
853 was developed by Cybernet Inc.\&
854 .Pq Pa http://www.cybernet.com/ ,
855 for its NetMAX product.
857 .An Greg Lehey Aq grog@lemis.com .
861 Bugs can be expected.
862 The configuration mechanism is not yet
864 If you have difficulties, please look at the section
865 .Sx "DEBUGGING PROBLEMS WITH VINUM"
866 before reporting problems.
870 device appear to work, but are not supported.
871 If you have trouble with
872 this configuration, please first replace the kernel with a
874 kernel and test with the KLD module.
876 Detection of differences between the version of the kernel and the KLD is not
879 The RAID-5 functionality is new in
881 Some problems have been
884 in combination with soft updates, but these are not reproducible on all
886 If you are planning to use
888 in a production environment, please test carefully.
889 .Sh DEBUGGING PROBLEMS WITH VINUM
890 Solving problems with
892 can be a difficult affair.
893 This section suggests some approaches.
894 .Ss Configuration problems
895 It is relatively easy (too easy) to run into problems with the
898 If you do, the first thing you should do is stop configuration
901 .Dl "vinum setdaemon 4"
903 This will stop updates and any further corruption of the on-disk configuration.
905 Next, look at the on-disk configuration, using a Bourne-style shell:
908 for i in /dev/da0s1h /dev/da1s1h /dev/da2s1h /dev/da3s1h; do
909 (dd if=$i skip=8 count=6|tr -d '\e000-\e011\e200-\e377'; echo) >> log
913 The names of the devices are the names of all
918 should then contain something like this:
922 IN VINOpanic.lemis.comdrive1}6E7~^K6T^Yfoovolume obj state up
924 volume raid state down
927 plex name obj.p0 state corrupt org concat vol obj
928 plex name obj.p1 state corrupt org striped 128b vol obj
929 plex name src.p0 state corrupt org striped 128b vol src
930 plex name src.p1 state up org concat vol src
931 plex name raid.p0 state faulty org disorg vol raid
932 plex name r.p0 state faulty org disorg vol r
933 plex name foo.p0 state up org concat vol foo
934 plex name foo.p1 state faulty org concat vol foo
935 sd name obj.p0.s0 drive drive2 plex obj.p0 state reborn len 409600b driveoffset 265b plexoffset 0b
936 sd name obj.p0.s1 drive drive4 plex obj.p0 state up len 409600b driveoffset 265b plexoffset 409600b
937 sd name obj.p1.s0 drive drive1 plex obj.p1 state up len 204800b driveoffset 265b plexoffset 0b
938 sd name obj.p1.s1 drive drive2 plex obj.p1 state reborn len 204800b driveoffset 409865b plexoffset 128b
939 sd name obj.p1.s2 drive drive3 plex obj.p1 state up len 204800b driveoffset 265b plexoffset 256b
940 sd name obj.p1.s3 drive drive4 plex obj.p1 state up len 204800b driveoffset 409865b plexoffset 384b
945 The first line contains the
947 label and must start with the text
949 It also contains the name of the system.
950 The exact definition is contained in
951 .Pa /usr/src/sys/dev/vinum/vinumvar.h .
952 The saved configuration starts in the middle of the line with the text
953 .Dq Li "volume obj state up"
954 and starts in sector 9 of the disk.
955 The rest of the output shows the remainder of the on-disk configuration.
957 may be necessary to increase the
961 in order to see the complete configuration.
963 The configuration on all disks should be the same.
964 If this is not the case,
965 please report the problem with the exact contents of the file
967 There is probably little that can be done to recover the on-disk configuration,
968 but if you keep a copy of the files used to create the objects, you should be
969 able to re-create them.
972 command does not change the subdisk data, so this will not cause data
974 You may need to use the
976 command if you have this kind of trouble.
978 In order to analyse a panic which you suspect comes from
980 you will need to build a debug kernel.
981 See the online handbook at
982 .Pa /usr/share/doc/en/books/developers-handbook/kerneldebug.html
984 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-\%handbook/kerneldebug.html
985 for more details of how to do this.
987 Perform the following steps to analyse a
992 Copy the following files to the directory in which you will be
993 performing the analysis, typically
998 .Pa /usr/src/sys/modules/vinum/.gdbinit.crash ,
1000 .Pa /usr/src/sys/modules/vinum/.gdbinit.kernel ,
1002 .Pa /usr/src/sys/modules/vinum/.gdbinit.serial ,
1004 .Pa /usr/src/sys/modules/vinum/.gdbinit.vinum
1007 .Pa /usr/src/sys/modules/vinum/.gdbinit.vinum.paths
1010 Make sure that you build the
1012 module with debugging information.
1015 builds a module with debugging symbols by default.
1020 does not contain symbols, you will not get an error message, but the stack trace
1021 will not show the symbols.
1022 Check the module before starting
1025 $ file /boot/kernel/vinum.ko
1026 /boot/kernel/vinum.ko: ELF 32-bit LSB shared object, Intel 80386,
1027 version 1 (FreeBSD), not stripped
1030 If the output shows that
1031 .Pa /boot/kernel/vinum.ko
1032 is stripped, you will have to find a version which is not.
1033 Usually this will be
1035 .Pa /usr/obj/sys/modules/vinum/vinum.ko
1039 .Dq Li "make world" )
1041 .Pa /usr/src/sys/modules/vinum/vinum.ko
1046 .Pa .gdbinit.vinum.paths
1049 Either take a dump or use remote serial
1051 to analyse the problem.
1052 To analyse a dump, say
1053 .Pa /var/crash/vmcore.5 ,
1055 .Pa /var/crash/.gdbinit.crash
1057 .Pa /var/crash/.gdbinit
1059 .Bd -literal -offset indent
1061 gdb -k kernel.debug vmcore.5
1064 This example assumes that you have installed the correct debug kernel at
1065 .Pa /var/crash/kernel.debug .
1066 If not, substitute the correct name of the debug kernel.
1068 To perform remote serial debugging,
1070 .Pa /var/crash/.gdbinit.serial
1072 .Pa /var/crash/.gdbinit
1074 .Bd -literal -offset indent
1081 file performs the functions necessary to establish connection.
1083 machine must already be in debug mode: enter the kernel debugger and select
1090 file expects the serial connection to run at 38400 bits per second; if you run
1091 at a different speed, edit the file accordingly (look for the
1095 The following example shows a remote debugging session using the
1102 GDB 4.16 (i386-unknown-freebsd), Copyright 1996 Free Software Foundation, Inc.
1103 Debugger (msg=0xf1093174 "vinum debug") at ../../i386/i386/db_interface.c:318
1104 318 in_Debugger = 0;
1105 #1 0xf108d9bc in vinumioctl (dev=0x40001900, cmd=0xc008464b, data=0xf6dedee0 "",
1106 flag=0x3, p=0xf68b7940) at
1107 /usr/src/sys/modules/Vinum/../../dev/Vinum/vinumioctl.c:102
1108 102 Debugger ("vinum debug");
1110 #0 Debugger (msg=0xf0f661ac "vinum debug") at ../../i386/i386/db_interface.c:318
1111 #1 0xf0f60a7c in vinumioctl (dev=0x40001900, cmd=0xc008464b, data=0xf6923ed0 "",
1112 flag=0x3, p=0xf688e6c0) at
1113 /usr/src/sys/modules/vinum/../../dev/vinum/vinumioctl.c:109
1114 #2 0xf01833b7 in spec_ioctl (ap=0xf6923e0c) at ../../miscfs/specfs/spec_vnops.c:424
1115 #3 0xf0182cc9 in spec_vnoperate (ap=0xf6923e0c) at ../../miscfs/specfs/spec_vnops.c:129
1116 #4 0xf01eb3c1 in ufs_vnoperatespec (ap=0xf6923e0c) at ../../ufs/ufs/ufs_vnops.c:2312
1117 #5 0xf017dbb1 in vn_ioctl (fp=0xf1007ec0, com=0xc008464b, data=0xf6923ed0 "",
1118 p=0xf688e6c0) at vnode_if.h:395
1119 #6 0xf015dce0 in ioctl (p=0xf688e6c0, uap=0xf6923f84) at ../../kern/sys_generic.c:473
1120 #7 0xf0214c0b in syscall (frame={tf_es = 0x27, tf_ds = 0x27, tf_edi = 0xefbfcff8,
1121 tf_esi = 0x1, tf_ebp = 0xefbfcf90, tf_isp = 0xf6923fd4, tf_ebx = 0x2,
1122 tf_edx = 0x804b614, tf_ecx = 0x8085d10, tf_eax = 0x36, tf_trapno = 0x7,
1123 tf_err = 0x2, tf_eip = 0x8060a34, tf_cs = 0x1f, tf_eflags = 0x286,
1124 tf_esp = 0xefbfcf78, tf_ss = 0x27}) at ../../i386/i386/trap.c:1100
1125 #8 0xf020a1fc in Xint0x80_syscall ()
1126 #9 0x804832d in ?? ()
1127 #10 0x80482ad in ?? ()
1128 #11 0x80480e9 in ?? ()
1133 When entering from the debugger, it is important that the source of frame 1
1136 file at the top of the example) contains the text
1137 .Dq Li "Debugger (\*[q]vinum debug\*[q]);" .
1139 This is an indication that the address specifications are correct.
1141 some other output, your symbols and the kernel module are out of sync, and the
1142 trace will be meaningless.
1145 For an initial investigation, the most important information is the output of
1148 (backtrace) command above.
1149 .Ss Reporting Problems with Vinum
1150 If you find any bugs in
1152 please report them to
1153 .An Greg Lehey Aq grog@lemis.com .
1154 Supply the following
1164 Any messages printed in
1165 .Pa /var/log/messages .
1166 All such messages will be identified by the text
1170 If you have a panic, a stack trace as described above.