/share/man/man4/vinum.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 1171 lines · 1153 code · 18 blank · 0 comment · 34 complexity · 4d2a4ee9a66e5ab826fd34772577466b MD5 · raw file

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