013ed768a3302e0748a4d59ac97137ae7f6a7547
[dragonfly.git] / share / man / man4 / vinum.4
1 .\"  Hey, Emacs, edit this file in -*- nroff-fill -*- mode
2 .\"-
3 .\" Copyright (c) 1997, 1998
4 .\"     Nan Yang Computer Services Limited.  All rights reserved.
5 .\"
6 .\"  This software is distributed under the so-called ``Berkeley
7 .\"  License'':
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
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
20 .\"      Services Limited.
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.
24 .\"
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.
36 .\"
37 .\" $FreeBSD: src/share/man/man4/vinum.4,v 1.22.2.9 2002/04/22 08:19:35 kuriyama Exp $
38 .\" $DragonFly: src/share/man/man4/vinum.4,v 1.13 2007/08/11 22:57:42 swildner Exp $
39 .\"
40 .Dd August 11, 2007
41 .Dt VINUM 4
42 .Os
43 .Sh NAME
44 .Nm vinum
45 .Nd Logical Volume Manager
46 .Sh SYNOPSIS
47 .Cd "pseudo-device vinum"
48 .Sh DESCRIPTION
49 .Nm
50 is a logical volume manager inspired by, but not derived from, the Veritas
51 Volume Manager.
52 It provides the following features:
53 .Bl -bullet
54 .It
55 It provides device-independent logical disks, called
56 .Em volumes .
57 Volumes are
58 not restricted to the size of any disk on the system.
59 .It
60 The volumes consist of one or more
61 .Em plexes ,
62 each of which contain the
63 entire address space of a volume.
64 This represents an implementation of RAID-1
65 (mirroring).
66 Multiple plexes can also be used for
67 .\" XXX What about sparse plexes?  Do we want them?
68 .Bl -bullet
69 .It
70 Increased read throughput.
71 .Nm
72 will read data from the least active disk, so if a volume has plexes on multiple
73 disks, more data can be read in parallel.
74 .Nm
75 reads data from only one plex, but it writes data to all plexes.
76 .It
77 Increased reliability.
78 By storing plexes on different disks, data will remain
79 available even if one of the plexes becomes unavailable.
80 In comparison with a
81 RAID-5 plex (see below), using multiple plexes requires more storage space, but
82 gives better performance, particularly in the case of a drive failure.
83 .It
84 Additional plexes can be used for on-line data reorganization.
85 By attaching an
86 additional plex and subsequently detaching one of the older plexes, data can be
87 moved on-line without compromising access.
88 .It
89 An additional plex can be used to obtain a consistent dump of a file system.
90 By
91 attaching an additional plex and detaching at a specific time, the detached plex
92 becomes an accurate snapshot of the file system at the time of detachment.
93 .\" Make sure to flush!
94 .El
95 .It
96 Each plex consists of one or more logical disk slices, called
97 .Em subdisks .
98 Subdisks are defined as a contiguous block of physical disk storage.
99 A plex may
100 consist of any reasonable number of subdisks (in other words, the real limit is
101 not the number, but other factors, such as memory and performance, associated
102 with maintaining a large number of subdisks).
103 .It
104 A number of mappings between subdisks and plexes are available:
105 .Bl -bullet
106 .It
107 .Em "Concatenated plexes"
108 consist of one or more subdisks, each of which
109 is mapped to a contiguous part of the plex address space.
110 .It
111 .Em "Striped plexes"
112 consist of two or more subdisks of equal size.
113 The file
114 address space is mapped in
115 .Em stripes ,
116 integral fractions of the subdisk
117 size.
118 Consecutive plex address space is mapped to stripes in each subdisk in
119 turn.
120 .if t \{\
121 .ig
122 .\" FIXME
123 .br
124 .ne 1.5i
125 .PS
126 move right 2i
127 down
128 SD0: box
129 SD1: box
130 SD2: box
131
132 "plex 0" at SD0.n+(0,.2)
133 "subdisk 0" rjust at SD0.w-(.2,0)
134 "subdisk 1" rjust at SD1.w-(.2,0)
135 "subdisk 2" rjust at SD2.w-(.2,0)
136 .PE
137 ..
138 .\}
139 The subdisks of a striped plex must all be the same size.
140 .It
141 .Em "RAID-5 plexes"
142 require at least three equal-sized subdisks.
143 They
144 resemble striped plexes, except that in each stripe, one subdisk stores parity
145 information.
146 This subdisk changes in each stripe: in the first stripe, it is the
147 first subdisk, in the second it is the second subdisk, etc.
148 In the event of a
149 single disk failure,
150 .Nm
151 will recover the data based on the information stored on the remaining subdisks.
152 This mapping is particularly suited to read-intensive access.
153 The subdisks of a
154 RAID-5 plex must all be the same size.
155 .\" Make sure to flush!
156 .El
157 .It
158 .Em Drives
159 are the lowest level of the storage hierarchy.
160 They represent disk special
161 devices.
162 .It
163 .Nm
164 offers automatic startup.
165 Unlike
166 .Ux
167 file systems,
168 .Nm
169 volumes contain all the configuration information needed to ensure that they are
170 started correctly when the subsystem is enabled.
171 This is also a significant
172 advantage over the Veritas\(tm File System.
173 This feature regards the presence
174 of the volumes.
175 It does not mean that the volumes will be mounted
176 automatically, since the standard startup procedures with
177 .Pa /etc/fstab
178 perform this function.
179 .El
180 .Sh KERNEL CONFIGURATION
181 .Nm
182 is currently supplied as a KLD module, and does not require
183 configuration.
184 As with other klds, it is absolutely necessary to match the kld
185 to the version of the operating system.
186 Failure to do so will cause
187 .Nm
188 to issue an error message and terminate.
189 .Pp
190 It is possible to configure
191 .Nm
192 in the kernel, but this is not recommended.
193 To do so, add this line to the
194 kernel configuration file:
195 .Pp
196 .D1 Cd "pseudo-device vinum"
197 .Ss Debug Options
198 The current version of
199 .Nm ,
200 both the kernel module and the user program
201 .Xr vinum 8 ,
202 include significant debugging support.
203 It is not recommended to remove
204 this support at the moment, but if you do you must remove it from both the
205 kernel and the user components.
206 To do this, edit the files
207 .Pa /usr/src/sbin/vinum/Makefile
208 and
209 .Pa /sys/dev/raid/vinum/Makefile
210 and edit the
211 .Va CFLAGS
212 variable to remove the
213 .Li -DVINUMDEBUG
214 option.
215 If you have
216 configured
217 .Nm
218 into the kernel, either specify the line
219 .Pp
220 .D1 Cd "options VINUMDEBUG"
221 .Pp
222 in the kernel configuration file or remove the
223 .Li -DVINUMDEBUG
224 option from
225 .Pa /usr/src/sbin/vinum/Makefile
226 as described above.
227 .Pp
228 If the
229 .Va VINUMDEBUG
230 variables do not match,
231 .Xr vinum 8
232 will fail with a message
233 explaining the problem and what to do to correct it.
234 .Pp
235 .Nm
236 was previously available in two versions: a freely available version which did
237 not contain RAID-5 functionality, and a full version including RAID-5
238 functionality, which was available only from Cybernet Systems Inc.
239 The present
240 version of
241 .Nm
242 includes the RAID-5 functionality.
243 .Sh RUNNING VINUM
244 .Nm
245 is part of the base
246 .Dx
247 system.
248 It does not require installation.
249 To start it, start the
250 .Xr vinum 8
251 program, which will load the kld if it is not already present.
252 Before using
253 .Nm ,
254 it must be configured.
255 See
256 .Xr vinum 8
257 for information on how to create a
258 .Nm
259 configuration.
260 .Pp
261 Normally, you start a configured version of
262 .Nm
263 at boot time.
264 Set the variable
265 .Va start_vinum
266 in
267 .Pa /etc/rc.conf
268 to
269 .Dq Li YES
270 to start
271 .Nm
272 at boot time.
273 (See
274 .Xr rc.conf 5
275 for more details.)
276 .Pp
277 If
278 .Nm
279 is loaded as a kld (the recommended way), the
280 .Nm Cm stop
281 command will unload it
282 (see
283 .Xr vinum 8 ) .
284 You can also do this with the
285 .Xr kldunload 8
286 command.
287 .Pp
288 The kld can only be unloaded when idle, in other words when no volumes are
289 mounted and no other instances of the
290 .Xr vinum 8
291 program are active.
292 Unloading the kld does not harm the data in the volumes.
293 .Ss Configuring and Starting Objects
294 Use the
295 .Xr vinum 8
296 utility to configure and start
297 .Nm
298 objects.
299 .Sh IOCTL CALLS
300 .Xr ioctl 2
301 calls are intended for the use of the
302 .Xr vinum 8
303 configuration program only.
304 They are described in the header file
305 .Pa /sys/dev/raid/vinum/vinumio.h .
306 .Ss Disk Labels
307 Conventional disk special devices have a
308 .Em "disk label"
309 in the second sector of the device.
310 See
311 .Xr disklabel 5
312 for more details.
313 This disk label describes the layout of the partitions within
314 the device.
315 .Nm
316 does not subdivide volumes, so volumes do not contain a physical disk label.
317 For convenience,
318 .Nm
319 implements the ioctl calls
320 .Dv DIOCGDINFO
321 (get disk label),
322 .Dv DIOCGPART
323 (get partition information),
324 .Dv DIOCWDINFO
325 (write partition information) and
326 .Dv DIOCSDINFO
327 (set partition information).
328 .Dv DIOCGDINFO
329 and
330 .Dv DIOCGPART
331 refer to an internal
332 representation of the disk label which is not present on the volume.
333 As a
334 result, the
335 .Fl r
336 option of
337 .Xr disklabel 8 ,
338 which reads the
339 .Dq "raw disk" ,
340 will fail.
341 .Pp
342 In general,
343 .Xr disklabel 8
344 serves no useful purpose on a
345 .Nm
346 volume.
347 .Pp
348 .Nm
349 ignores the
350 .Dv DIOCWDINFO
351 and
352 .Dv DIOCSDINFO ioctls, since there is nothing to change.
353 As a result, any attempt to modify the disk label will be silently ignored.
354 .Sh MAKING FILE SYSTEMS
355 Since
356 .Nm
357 volumes do not contain partitions, the names do not need to conform to the
358 standard rules for naming disk partitions.
359 For a physical disk partition, the
360 last letter of the device name specifies the partition identifier (a to p).
361 .Nm
362 volumes need not conform to this convention, but if they do not,
363 .Xr newfs 8
364 will complain that it cannot determine the partition.
365 To solve this problem,
366 use the
367 .Fl v
368 flag to
369 .Xr newfs 8 .
370 For example, if you have a volume
371 .Pa concat ,
372 use the following command to create a UFS file system on it:
373 .Pp
374 .Dl "newfs -v /dev/vinum/concat"
375 .Sh OBJECT NAMING
376 .Nm
377 assigns default names to plexes and subdisks, although they may be overridden.
378 We do not recommend overriding the default names.
379 Experience with the
380 Veritas\(tm
381 volume manager, which allows arbitrary naming of objects, has shown that this
382 flexibility does not bring a significant advantage, and it can cause confusion.
383 .Pp
384 Names may contain any non-blank character, but it is recommended to restrict
385 them to letters, digits and the underscore characters.
386 The names of volumes,
387 plexes and subdisks may be up to 64 characters long, and the names of drives may
388 up to 32 characters long.
389 When choosing volume and plex names, bear in mind
390 that automatically generated plex and subdisk names are longer than the name
391 from which they are derived.
392 .Bl -bullet
393 .It
394 When
395 .Nm
396 creates or deletes objects, it creates a directory
397 .Pa /dev/vinum ,
398 in which it makes device entries for each volume.
399 It also creates the
400 subdirectories,
401 .Pa /dev/vinum/plex
402 and
403 .Pa /dev/vinum/sd ,
404 in which it stores device entries for the plexes and subdisks.  In addition, it
405 creates two more directories,
406 .Pa /dev/vinum/vol
407 and
408 .Pa /dev/vinum/drive ,
409 in which it stores hierarchical information for volumes and drives.
410 .It
411 In addition,
412 .Nm
413 creates three super-devices,
414 .Pa /dev/vinum/control ,
415 .Pa /dev/vinum/Control
416 and
417 .Pa /dev/vinum/controld .
418 .Pa /dev/vinum/control
419 is used by
420 .Xr vinum 8
421 when it has been compiled without the
422 .Dv VINUMDEBUG
423 option,
424 .Pa /dev/vinum/Control
425 is used by
426 .Xr vinum 8
427 when it has been compiled with the
428 .Dv VINUMDEBUG
429 option, and
430 .Pa /dev/vinum/controld
431 is used by the
432 .Nm
433 daemon.
434 The two control devices for
435 .Xr vinum 8
436 are used to synchronize the debug status of kernel and user modules.
437 .It
438 Unlike
439 .Ux
440 drives,
441 .Nm
442 volumes are not subdivided into partitions, and thus do not contain a disk
443 label.
444 Unfortunately, this confuses a number of utilities, notably
445 .Xr newfs 8 ,
446 which normally tries to interpret the last letter of a
447 .Nm
448 volume name as a partition identifier.
449 If you use a volume name which does not
450 end in the letters
451 .Ql a
452 to
453 .Ql c ,
454 you must use the
455 .Fl v
456 flag to
457 .Xr newfs 8
458 in order to tell it to ignore this convention.
459 .\"
460 .It
461 Plexes do not need to be assigned explicit names.
462 By default, a plex name is
463 the name of the volume followed by the letters
464 .Pa .p
465 and the number of the
466 plex.
467 For example, the plexes of volume
468 .Pa vol3
469 are called
470 .Pa vol3.p0 , vol3.p1
471 and so on.
472 These names can be overridden, but it is not recommended.
473 .It
474 Like plexes, subdisks are assigned names automatically, and explicit naming is
475 discouraged.
476 A subdisk name is the name of the plex followed by the letters
477 .Pa .s
478 and a number identifying the subdisk.
479 For example, the subdisks of
480 plex
481 .Pa vol3.p0
482 are called
483 .Pa vol3.p0.s0 , vol3.p0.s1
484 and so on.
485 .It
486 By contrast,
487 .Em drives
488 must be named.
489 This makes it possible to move a drive to a different location
490 and still recognize it automatically.
491 Drive names may be up to 32 characters
492 long.
493 .El
494 .Ss Example
495 Assume the
496 .Nm
497 objects described in the section
498 .Sx "CONFIGURATION FILE"
499 in
500 .Xr vinum 8 .
501 The directory
502 .Pa /dev/vinum
503 looks like:
504 .Bd -literal -offset indent
505 # ls -lR /dev/vinum
506 total 5
507 crwxr-xr--  1 root  wheel   91,   2 Mar 30 16:08 concat
508 crwx------  1 root  wheel   91, 0x40000000 Mar 30 16:08 control
509 crwx------  1 root  wheel   91, 0x40000001 Mar 30 16:08 controld
510 drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 drive
511 drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 plex
512 drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 rvol
513 drwxrwxrwx  2 root  wheel       512 Mar 30 16:08 sd
514 crwxr-xr--  1 root  wheel   91,   3 Mar 30 16:08 strcon
515 crwxr-xr--  1 root  wheel   91,   1 Mar 30 16:08 stripe
516 crwxr-xr--  1 root  wheel   91,   0 Mar 30 16:08 tinyvol
517 drwxrwxrwx  7 root  wheel       512 Mar 30 16:08 vol
518 crwxr-xr--  1 root  wheel   91,   4 Mar 30 16:08 vol5
519
520 /dev/vinum/drive:
521 total 0
522 crw-r-----  1 root  operator    4,  15 Oct 21 16:51 drive2
523 crw-r-----  1 root  operator    4,  31 Oct 21 16:51 drive4
524
525 /dev/vinum/plex:
526 total 0
527 crwxr-xr--  1 root  wheel   91, 0x10000002 Mar 30 16:08 concat.p0
528 crwxr-xr--  1 root  wheel   91, 0x10010002 Mar 30 16:08 concat.p1
529 crwxr-xr--  1 root  wheel   91, 0x10000003 Mar 30 16:08 strcon.p0
530 crwxr-xr--  1 root  wheel   91, 0x10010003 Mar 30 16:08 strcon.p1
531 crwxr-xr--  1 root  wheel   91, 0x10000001 Mar 30 16:08 stripe.p0
532 crwxr-xr--  1 root  wheel   91, 0x10000000 Mar 30 16:08 tinyvol.p0
533 crwxr-xr--  1 root  wheel   91, 0x10000004 Mar 30 16:08 vol5.p0
534 crwxr-xr--  1 root  wheel   91, 0x10010004 Mar 30 16:08 vol5.p1
535
536 /dev/vinum/sd:
537 total 0
538 crwxr-xr--  1 root  wheel   91, 0x20000002 Mar 30 16:08 concat.p0.s0
539 crwxr-xr--  1 root  wheel   91, 0x20100002 Mar 30 16:08 concat.p0.s1
540 crwxr-xr--  1 root  wheel   91, 0x20010002 Mar 30 16:08 concat.p1.s0
541 crwxr-xr--  1 root  wheel   91, 0x20000003 Mar 30 16:08 strcon.p0.s0
542 crwxr-xr--  1 root  wheel   91, 0x20100003 Mar 30 16:08 strcon.p0.s1
543 crwxr-xr--  1 root  wheel   91, 0x20010003 Mar 30 16:08 strcon.p1.s0
544 crwxr-xr--  1 root  wheel   91, 0x20110003 Mar 30 16:08 strcon.p1.s1
545 crwxr-xr--  1 root  wheel   91, 0x20000001 Mar 30 16:08 stripe.p0.s0
546 crwxr-xr--  1 root  wheel   91, 0x20100001 Mar 30 16:08 stripe.p0.s1
547 crwxr-xr--  1 root  wheel   91, 0x20000000 Mar 30 16:08 tinyvol.p0.s0
548 crwxr-xr--  1 root  wheel   91, 0x20100000 Mar 30 16:08 tinyvol.p0.s1
549 crwxr-xr--  1 root  wheel   91, 0x20000004 Mar 30 16:08 vol5.p0.s0
550 crwxr-xr--  1 root  wheel   91, 0x20100004 Mar 30 16:08 vol5.p0.s1
551 crwxr-xr--  1 root  wheel   91, 0x20010004 Mar 30 16:08 vol5.p1.s0
552 crwxr-xr--  1 root  wheel   91, 0x20110004 Mar 30 16:08 vol5.p1.s1
553
554 /dev/vinum/vol:
555 total 5
556 crwxr-xr--  1 root  wheel   91,   2 Mar 30 16:08 concat
557 drwxr-xr-x  4 root  wheel       512 Mar 30 16:08 concat.plex
558 crwxr-xr--  1 root  wheel   91,   3 Mar 30 16:08 strcon
559 drwxr-xr-x  4 root  wheel       512 Mar 30 16:08 strcon.plex
560 crwxr-xr--  1 root  wheel   91,   1 Mar 30 16:08 stripe
561 drwxr-xr-x  3 root  wheel       512 Mar 30 16:08 stripe.plex
562 crwxr-xr--  1 root  wheel   91,   0 Mar 30 16:08 tinyvol
563 drwxr-xr-x  3 root  wheel       512 Mar 30 16:08 tinyvol.plex
564 crwxr-xr--  1 root  wheel   91,   4 Mar 30 16:08 vol5
565 drwxr-xr-x  4 root  wheel       512 Mar 30 16:08 vol5.plex
566
567 /dev/vinum/vol/concat.plex:
568 total 2
569 crwxr-xr--  1 root  wheel   91, 0x10000002 Mar 30 16:08 concat.p0
570 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 concat.p0.sd
571 crwxr-xr--  1 root  wheel   91, 0x10010002 Mar 30 16:08 concat.p1
572 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 concat.p1.sd
573
574 /dev/vinum/vol/concat.plex/concat.p0.sd:
575 total 0
576 crwxr-xr--  1 root  wheel   91, 0x20000002 Mar 30 16:08 concat.p0.s0
577 crwxr-xr--  1 root  wheel   91, 0x20100002 Mar 30 16:08 concat.p0.s1
578
579 /dev/vinum/vol/concat.plex/concat.p1.sd:
580 total 0
581 crwxr-xr--  1 root  wheel   91, 0x20010002 Mar 30 16:08 concat.p1.s0
582
583 /dev/vinum/vol/strcon.plex:
584 total 2
585 crwxr-xr--  1 root  wheel   91, 0x10000003 Mar 30 16:08 strcon.p0
586 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 strcon.p0.sd
587 crwxr-xr--  1 root  wheel   91, 0x10010003 Mar 30 16:08 strcon.p1
588 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 strcon.p1.sd
589
590 /dev/vinum/vol/strcon.plex/strcon.p0.sd:
591 total 0
592 crwxr-xr--  1 root  wheel   91, 0x20000003 Mar 30 16:08 strcon.p0.s0
593 crwxr-xr--  1 root  wheel   91, 0x20100003 Mar 30 16:08 strcon.p0.s1
594
595 /dev/vinum/vol/strcon.plex/strcon.p1.sd:
596 total 0
597 crwxr-xr--  1 root  wheel   91, 0x20010003 Mar 30 16:08 strcon.p1.s0
598 crwxr-xr--  1 root  wheel   91, 0x20110003 Mar 30 16:08 strcon.p1.s1
599
600 /dev/vinum/vol/stripe.plex:
601 total 1
602 crwxr-xr--  1 root  wheel   91, 0x10000001 Mar 30 16:08 stripe.p0
603 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 stripe.p0.sd
604
605 /dev/vinum/vol/stripe.plex/stripe.p0.sd:
606 total 0
607 crwxr-xr--  1 root  wheel   91, 0x20000001 Mar 30 16:08 stripe.p0.s0
608 crwxr-xr--  1 root  wheel   91, 0x20100001 Mar 30 16:08 stripe.p0.s1
609
610 /dev/vinum/vol/tinyvol.plex:
611 total 1
612 crwxr-xr--  1 root  wheel   91, 0x10000000 Mar 30 16:08 tinyvol.p0
613 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 tinyvol.p0.sd
614
615 /dev/vinum/vol/tinyvol.plex/tinyvol.p0.sd:
616 total 0
617 crwxr-xr--  1 root  wheel   91, 0x20000000 Mar 30 16:08 tinyvol.p0.s0
618 crwxr-xr--  1 root  wheel   91, 0x20100000 Mar 30 16:08 tinyvol.p0.s1
619
620 /dev/vinum/vol/vol5.plex:
621 total 2
622 crwxr-xr--  1 root  wheel   91, 0x10000004 Mar 30 16:08 vol5.p0
623 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 vol5.p0.sd
624 crwxr-xr--  1 root  wheel   91, 0x10010004 Mar 30 16:08 vol5.p1
625 drwxr-xr-x  2 root  wheel       512 Mar 30 16:08 vol5.p1.sd
626
627 /dev/vinum/vol/vol5.plex/vol5.p0.sd:
628 total 0
629 crwxr-xr--  1 root  wheel   91, 0x20000004 Mar 30 16:08 vol5.p0.s0
630 crwxr-xr--  1 root  wheel   91, 0x20100004 Mar 30 16:08 vol5.p0.s1
631
632 /dev/vinum/vol/vol5.plex/vol5.p1.sd:
633 total 0
634 crwxr-xr--  1 root  wheel   91, 0x20010004 Mar 30 16:08 vol5.p1.s0
635 crwxr-xr--  1 root  wheel   91, 0x20110004 Mar 30 16:08 vol5.p1.s1
636 .Ed
637 .Pp
638 In the case of unattached plexes and subdisks, the naming is reversed.
639 Subdisks
640 are named after the disk on which they are located, and plexes are named after
641 the subdisk.
642 .\" XXX
643 .Bf -symbolic
644 This mapping is still to be determined.
645 .Ef
646 .Ss Object States
647 Each
648 .Nm
649 object has a
650 .Em state
651 associated with it.
652 .Nm
653 uses this state to determine the handling of the object.
654 .Ss Volume States
655 Volumes may have the following states:
656 .Bl -hang -width 14n
657 .It Em down
658 The volume is completely inaccessible.
659 .It Em up
660 The volume is up and at least partially functional.
661 Not all plexes may be
662 available.
663 .El
664 .Ss "Plex States"
665 Plexes may have the following states:
666 .Bl -hang -width 14n
667 .It Em referenced
668 A plex entry which has been referenced as part of a volume, but which is
669 currently not known.
670 .It Em faulty
671 A plex which has gone completely down because of I/O errors.
672 .It Em down
673 A plex which has been taken down by the administrator.
674 .It Em initializing
675 A plex which is being initialized.
676 .El
677 .Pp
678 The remaining states represent plexes which are at least partially up.
679 .Bl -hang -width 14n
680 .It Em corrupt
681 A plex entry which is at least partially up.
682 Not all subdisks are available,
683 and an inconsistency has occurred.
684 If no other plex is uncorrupted, the volume
685 is no longer consistent.
686 .It Em degraded
687 A RAID-5 plex entry which is accessible, but one subdisk is down, requiring
688 recovery for many I/O requests.
689 .It Em flaky
690 A plex which is really up, but which has a reborn subdisk which we do not
691 completely trust, and which we do not want to read if we can avoid it.
692 .It Em up
693 A plex entry which is completely up.
694 All subdisks are up.
695 .El
696 .Ss "Subdisk States"
697 Subdisks can have the following states:
698 .Bl -hang -width 14n
699 .It Em empty
700 A subdisk entry which has been created completely.
701 All fields are correct, and
702 the disk has been updated, but the on the disk is not valid.
703 .It Em referenced
704 A subdisk entry which has been referenced as part of a plex, but which is
705 currently not known.
706 .It Em initializing
707 A subdisk entry which has been created completely and which is currently being
708 initialized.
709 .El
710 .Pp
711 The following states represent invalid data.
712 .Bl -hang -width 14n
713 .It Em obsolete
714 A subdisk entry which has been created completely.
715 All fields are correct, the
716 config on disk has been updated, and the data was valid, but since then the
717 drive has been taken down, and as a result updates have been missed.
718 .It Em stale
719 A subdisk entry which has been created completely.
720 All fields are correct, the
721 disk has been updated, and the data was valid, but since then the drive has been
722 crashed and updates have been lost.
723 .El
724 .Pp
725 The following states represent valid, inaccessible data.
726 .Bl -hang -width 14n
727 .It Em crashed
728 A subdisk entry which has been created completely.
729 All fields are correct, the
730 disk has been updated, and the data was valid, but since then the drive has gone
731 down.
732 No attempt has been made to write to the subdisk since the crash, so the
733 data is valid.
734 .It Em down
735 A subdisk entry which was up, which contained valid data, and which was taken
736 down by the administrator.
737 The data is valid.
738 .It Em reviving
739 The subdisk is currently in the process of being revived.
740 We can write but not
741 read.
742 .El
743 .Pp
744 The following states represent accessible subdisks with valid data.
745 .Bl -hang -width 14n
746 .It Em reborn
747 A subdisk entry which has been created completely.
748 All fields are correct, the
749 disk has been updated, and the data was valid, but since then the drive has gone
750 down and up again.
751 No updates were lost, but it is possible that the subdisk
752 has been damaged.
753 We won't read from this subdisk if we have a choice.
754 If this
755 is the only subdisk which covers this address space in the plex, we set its
756 state to up under these circumstances, so this status implies that there is
757 another subdisk to fulfil the request.
758 .It Em up
759 A subdisk entry which has been created completely.
760 All fields are correct, the
761 disk has been updated, and the data is valid.
762 .El
763 .Ss "Drive States"
764 Drives can have the following states:
765 .Bl -hang -width 14n
766 .It Em referenced
767 At least one subdisk refers to the drive, but it is not currently accessible to
768 the system.
769 No device name is known.
770 .It Em down
771 The drive is not accessible.
772 .It Em up
773 The drive is up and running.
774 .El
775 .Sh DEBUGGING PROBLEMS WITH VINUM
776 Solving problems with
777 .Nm
778 can be a difficult affair.
779 This section suggests some approaches.
780 .Ss Configuration problems
781 It is relatively easy (too easy) to run into problems with the
782 .Nm
783 configuration.
784 If you do, the first thing you should do is stop configuration
785 updates:
786 .Pp
787 .Dl "vinum setdaemon 4"
788 .Pp
789 This will stop updates and any further corruption of the on-disk configuration.
790 .Pp
791 Next, look at the on-disk configuration with the
792 .Nm Cm dumpconfig
793 command, for example:
794 .if t .ps -3
795 .if t .vs -3
796 .Bd -literal
797 # \fBvinum dumpconfig\fP
798 Drive 4:        Device /dev/da3s0h
799                 Created on crash.lemis.com at Sat May 20 16:32:44 2000
800                 Config last updated Sat May 20 16:32:56 2000
801                 Size:        601052160 bytes (573 MB)
802 volume obj state up
803 volume src state up
804 volume raid state down
805 volume r state down
806 volume foo state up
807 plex name obj.p0 state corrupt org concat vol obj
808 plex name obj.p1 state corrupt org striped 128b vol obj
809 plex name src.p0 state corrupt org striped 128b vol src
810 plex name src.p1 state up org concat vol src
811 plex name raid.p0 state faulty org disorg vol raid
812 plex name r.p0 state faulty org disorg vol r
813 plex name foo.p0 state up org concat vol foo
814 plex name foo.p1 state faulty org concat vol foo
815 sd name obj.p0.s0 drive drive2 plex obj.p0 state reborn len 409600b driveoffset 265b plexoffset 0b
816 sd name obj.p0.s1 drive drive4 plex obj.p0 state up len 409600b driveoffset 265b plexoffset 409600b
817 sd name obj.p1.s0 drive drive1 plex obj.p1 state up len 204800b driveoffset 265b plexoffset 0b
818 sd name obj.p1.s1 drive drive2 plex obj.p1 state reborn len 204800b driveoffset 409865b plexoffset 128b
819 sd name obj.p1.s2 drive drive3 plex obj.p1 state up len 204800b driveoffset 265b plexoffset 256b
820 sd name obj.p1.s3 drive drive4 plex obj.p1 state up len 204800b driveoffset 409865b plexoffset 384b
821 .Ed
822 .if t .vs +3
823 .if t .ps +3
824 .Pp
825 The configuration on all disks should be the same.
826 If this is not the case,
827 please save the output to a file and report the problem.
828 There is probably
829 little that can be done to recover the on-disk configuration, but if you keep a
830 copy of the files used to create the objects, you should be able to re-create
831 them.
832 The
833 .Cm create
834 command does not change the subdisk data, so this will not cause data
835 corruption.
836 You may need to use the
837 .Cm resetconfig
838 command if you have this kind of trouble.
839 .Ss Kernel Panics
840 In order to analyse a panic which you suspect comes from
841 .Nm
842 you will need to build a debug kernel.
843 See the online handbook at
844 .Pa /usr/share/doc/en/books/developers-handbook/kerneldebug.html
845 (if installed) or
846 .Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-\%handbook/kerneldebug.html
847 for more details of how to do this.
848 .Pp
849 Perform the following steps to analyse a
850 .Nm
851 problem:
852 .Bl -enum
853 .It
854 Copy the following files to the directory in which you will be
855 performing the analysis, typically
856 .Pa /var/crash :
857 .Pp
858 .Bl -bullet -compact
859 .It
860 .Pa /sys/dev/raid/vinum/.gdbinit.crash ,
861 .It
862 .Pa /sys/dev/raid/vinum/.gdbinit.kernel ,
863 .It
864 .Pa /sys/dev/raid/vinum/.gdbinit.serial ,
865 .It
866 .Pa /sys/dev/raid/vinum/.gdbinit.vinum
867 and
868 .It
869 .Pa /sys/dev/raid/vinum/.gdbinit.vinum.paths
870 .El
871 .It
872 Make sure that you build the
873 .Nm
874 module with debugging information.
875 The standard
876 .Pa Makefile
877 builds a module with debugging symbols by default.
878 If the version of
879 .Nm
880 in
881 .Pa /modules
882 does not contain symbols, you will not get an error message, but the stack trace
883 will not show the symbols.
884 Check the module before starting
885 .Xr kgdb 1 :
886 .Bd -literal
887 $ file /modules/vinum.ko
888 /modules/vinum.ko: ELF 32-bit LSB shared object, Intel 80386,
889   version 1 (FreeBSD), not stripped
890 .Ed
891 .Pp
892 If the output shows that
893 .Pa /modules/vinum.ko
894 is stripped, you will have to find a version which is not.
895 Usually this will be
896 either in
897 .Pa /usr/obj/usr/src/sys/SYSTEM_NAME/usr/src/sys/dev/raid/vinum/vinum.ko
898 (if you have built
899 .Nm
900 with a
901 .Dq Li "make world" )
902 or
903 .Pa /sys/dev/raid/vinum/vinum.ko
904 (if you have built
905 .Nm
906 in this directory).
907 Modify the file
908 .Pa .gdbinit.vinum.paths
909 accordingly.
910 .It
911 Either take a dump or use remote serial
912 .Xr gdb 1
913 to analyse the problem.
914 To analyse a dump, say
915 .Pa /var/crash/vmcore.5 ,
916 link
917 .Pa /var/crash/.gdbinit.crash
918 to
919 .Pa /var/crash/.gdbinit
920 and enter:
921 .Bd -literal -offset indent
922 cd /var/crash
923 kgdb kernel.debug vmcore.5
924 .Ed
925 .Pp
926 This example assumes that you have installed the correct debug kernel at
927 .Pa /var/crash/kernel.debug .
928 If not, substitute the correct name of the debug kernel.
929 .Pp
930 To perform remote serial debugging,
931 link
932 .Pa /var/crash/.gdbinit.serial
933 to
934 .Pa /var/crash/.gdbinit
935 and enter
936 .Bd -literal -offset indent
937 cd /var/crash
938 kgdb kernel.debug
939 .Ed
940 .Pp
941 In this case, the
942 .Pa .gdbinit
943 file performs the functions necessary to establish connection.
944 The remote
945 machine must already be in debug mode: enter the kernel debugger and select
946 .Ic gdb
947 (see
948 .Xr ddb 4
949 for more details.)
950 The serial
951 .Pa .gdbinit
952 file expects the serial connection to run at 38400 bits per second; if you run
953 at a different speed, edit the file accordingly (look for the
954 .Va remotebaud
955 specification).
956 .Pp
957 The following example shows a remote debugging session using the
958 .Ic debug
959 command of
960 .Xr vinum 8 :
961 .Bd -literal
962 .if t .ps -3
963 .if t .vs -3
964 GDB 4.16 (i386-unknown-dragonfly), Copyright 1996 Free Software Foundation, Inc.
965 Debugger (msg=0xf1093174 "vinum debug") at ../../i386/i386/db_interface.c:318
966 318                 in_Debugger = 0;
967 #1  0xf108d9bc in vinumioctl (dev=0x40001900, cmd=0xc008464b, data=0xf6dedee0 "",
968     flag=0x3, p=0xf68b7940) at
969     /usr/src/sys/dev/raid/vinum/vinumioctl.c:102
970 102             Debugger ("vinum debug");
971 (kgdb) bt
972 #0  Debugger (msg=0xf0f661ac "vinum debug") at ../../i386/i386/db_interface.c:318
973 #1  0xf0f60a7c in vinumioctl (dev=0x40001900, cmd=0xc008464b, data=0xf6923ed0 "",
974       flag=0x3, p=0xf688e6c0) at
975       /usr/src/sys/dev/raid/vinum/vinumioctl.c:109
976 #2  0xf01833b7 in spec_ioctl (ap=0xf6923e0c) at ../../miscfs/specfs/spec_vnops.c:424
977 #3  0xf0182cc9 in spec_vnoperate (ap=0xf6923e0c) at ../../miscfs/specfs/spec_vnops.c:129
978 #4  0xf01eb3c1 in ufs_vnoperatespec (ap=0xf6923e0c) at ../../ufs/ufs/ufs_vnops.c:2312
979 #5  0xf017dbb1 in vn_ioctl (fp=0xf1007ec0, com=0xc008464b, data=0xf6923ed0 "",
980       p=0xf688e6c0) at vnode_if.h:395
981 #6  0xf015dce0 in ioctl (p=0xf688e6c0, uap=0xf6923f84) at ../../kern/sys_generic.c:473
982 #7  0xf0214c0b in syscall (frame={tf_es = 0x27, tf_ds = 0x27, tf_edi = 0xefbfcff8,
983       tf_esi = 0x1, tf_ebp = 0xefbfcf90, tf_isp = 0xf6923fd4, tf_ebx = 0x2,
984       tf_edx = 0x804b614, tf_ecx = 0x8085d10, tf_eax = 0x36, tf_trapno = 0x7,
985       tf_err = 0x2, tf_eip = 0x8060a34, tf_cs = 0x1f, tf_eflags = 0x286,
986       tf_esp = 0xefbfcf78, tf_ss = 0x27}) at ../../i386/i386/trap.c:1100
987 #8  0xf020a1fc in Xint0x80_syscall ()
988 #9  0x804832d in ?? ()
989 #10 0x80482ad in ?? ()
990 #11 0x80480e9 in ?? ()
991 .if t .vs
992 .if t .ps
993 .Ed
994 .Pp
995 When entering from the debugger, it is important that the source of frame 1
996 (listed by the
997 .Pa .gdbinit
998 file at the top of the example) contains the text
999 .Dq Li "Debugger (\*[q]vinum debug\*[q]);" .
1000 .Pp
1001 This is an indication that the address specifications are correct.
1002 If you get
1003 some other output, your symbols and the kernel module are out of sync, and the
1004 trace will be meaningless.
1005 .El
1006 .Pp
1007 For an initial investigation, the most important information is the output of
1008 the
1009 .Ic bt
1010 (backtrace) command above.
1011 .Ss Reporting Problems with Vinum
1012 If you find any bugs in
1013 .Nm ,
1014 please report them to
1015 .An Greg Lehey Aq grog@lemis.com .
1016 Supply the following
1017 information:
1018 .Bl -bullet
1019 .It
1020 The output of the
1021 .Nm Cm list
1022 command
1023 (see
1024 .Xr vinum 8 ) .
1025 .It
1026 Any messages printed in
1027 .Pa /var/log/messages .
1028 All such messages will be identified by the text
1029 .Dq Li vinum
1030 at the beginning.
1031 .It
1032 If you have a panic, a stack trace as described above.
1033 .El
1034 .Sh SEE ALSO
1035 .Xr disklabel 5 ,
1036 .Xr disklabel 8 ,
1037 .Xr newfs 8 ,
1038 .Xr vinum 8
1039 .Sh HISTORY
1040 .Nm
1041 first appeared in
1042 .Fx 3.0 .
1043 The RAID-5 component of
1044 .Nm
1045 was developed by Cybernet Inc.\&
1046 .Pq Pa http://www.cybernet.com/ ,
1047 for its NetMAX product.
1048 .Sh AUTHORS
1049 .An Greg Lehey Aq grog@lemis.com .
1050 .Sh BUGS
1051 .Nm
1052 is a new product.
1053 Bugs can be expected.
1054 The configuration mechanism is not yet
1055 fully functional.
1056 If you have difficulties, please look at the section
1057 .Sx "DEBUGGING PROBLEMS WITH VINUM"
1058 before reporting problems.
1059 .Pp
1060 Kernels with the
1061 .Nm
1062 pseudo-device appear to work, but are not supported.
1063 If you have trouble with
1064 this configuration, please first replace the kernel with a
1065 .No non- Ns Nm
1066 kernel and test with the kld module.
1067 .Pp
1068 Detection of differences between the version of the kernel and the kld is not
1069 yet implemented.
1070 .Pp
1071 The RAID-5 functionality is new in
1072 .Fx 3.3 .
1073 Some problems have been
1074 reported with
1075 .Nm
1076 in combination with soft updates, but these are not reproducible on all
1077 systems.
1078 If you are planning to use
1079 .Nm
1080 in a production environment, please test carefully.