| blob | c5f96e517f4d6fdb899b5e3f91f1339232d3a7ba |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH METADB 1M "Mar 26, 2006"
7 .SH NAME
8 metadb \- create and delete replicas of the metadevice state database
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/sbin/metadb\fR \fB-h\fR
13 .fi
15 .LP
16 .nf
17 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR]
18 .fi
20 .LP
21 .nf
22 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR] \fB-a\fR [\fB-f\fR] [\fB-k\fR \fIsystem-file\fR] mddb\fInn\fR
23 .fi
25 .LP
26 .nf
27 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR] \fB-a\fR [\fB-f\fR] [\fB-k\fR \fIsystem-file\fR]
28 [\fB-c\fR \fInumber\fR] [\fB-l\fR \fIlength\fR] \fIslice...\fR
29 .fi
31 .LP
32 .nf
33 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR] \fB-d\fR [\fB-f\fR] [\fB-k\fR \fIsystem-file\fR] mddb\fInn\fR
34 .fi
36 .LP
37 .nf
38 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR] \fB-d\fR [\fB-f\fR] [\fB-k\fR \fIsystem-file\fR] \fIslice...\fR
39 .fi
41 .LP
42 .nf
43 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR] \fB-i\fR
44 .fi
46 .LP
47 .nf
48 \fB/sbin/metadb\fR [\fB-s\fR \fIsetname\fR] \fB-p\fR [\fB-k\fR \fIsystem-file\fR]
49 [\fImddb.cf-file\fR]
50 .fi
52 .SH DESCRIPTION
53 .sp
54 .LP
55 The \fBmetadb\fR command creates and deletes replicas of the metadevice state
56 database. State database replicas can be created on dedicated slices, or on
57 slices that will later become part of a simple metadevice (concatenation or
58 stripe) or RAID5 metadevice. Do not place state database replicas on
59 fabric-attached storage, SANs, or other storage that is not directly attached
60 to the system and available at the same point in the boot process as
61 traditional SCSI or IDE drives. See \fBNOTES\fR.
62 .sp
63 .LP
64 The metadevice state database contains the configuration of all metadevices and
65 hot spare pools in the system. Additionally, the metadevice state database
66 keeps track of the current state of metadevices and hot spare pools, and their
67 components. Solaris Volume Manager automatically updates the metadevice state
68 database when a configuration or state change occurs. A submirror failure is an
69 example of a state change. Creating a new metadevice is an example of a
70 configuration change.
71 .sp
72 .LP
73 The metadevice state database is actually a collection of multiple, replicated
74 database copies. Each copy, referred to as a replica, is subject to strict
75 consistency checking to ensure correctness.
76 .sp
77 .LP
78 Replicated databases have an inherent problem in determining which database has
79 valid and correct data. To solve this problem, Volume Manager uses a
80 \fImajority consensus algorithm\fR. This algorithm requires that a majority of
81 the database replicas be available before any of them are declared valid. This
82 algorithm strongly encourages the presence of at least three initial replicas,
83 which you create. A consensus can then be reached as long as at least two of
84 the three replicas are available. If there is only one replica and the system
85 crashes, it is possible that all metadevice configuration data can be lost.
86 .sp
87 .LP
88 The majority consensus algorithm is conservative in the sense that it will fail
89 if a majority consensus cannot be reached, even if one replica actually does
90 contain the most up-to-date data. This approach guarantees that stale data will
91 not be accidentally used, regardless of the failure scenario. The majority
92 consensus algorithm accounts for the following: the system will stay running
93 with exactly half or more replicas; the system will panic when less than half
94 the replicas are available; the system will not reboot without one more than
95 half the total replicas.
96 .sp
97 .LP
98 When used with no options, the \fBmetadb\fR command gives a short form of the
99 status of the metadevice state database. Use \fBmetadb\fR \fB-i\fR for an
100 explanation of the flags field in the output.
101 .sp
102 .LP
103 The initial state database is created using the \fBmetadb\fR command with both
104 the \fB-a\fR and \fB-f\fR options, followed by the slice where the replica is
105 to reside. The \fB-a\fR option specifies that a replica (in this case, the
106 initial) state database should be created. The \fB-f\fR option forces the
107 creation to occur, even though a state database does not exist. (The \fB-a\fR
108 and \fB-f\fR options should be used together only when no state databases
109 exist.)
110 .sp
111 .LP
112 Additional replicas beyond those initially created can be added to the system.
113 They contain the same information as the existing replicas, and help to prevent
114 the loss of the configuration information. Loss of the configuration makes
115 operation of the metadevices impossible. To create additional replicas, use the
116 \fBmetadb\fR \fB-a\fR command, followed by the name of the new slice(s) where
117 the replicas will reside. All replicas that are located on the same slice must
118 be created at the same time.
119 .sp
120 .LP
121 To delete all replicas that are located on the same slice, the \fBmetadb\fR
122 \fB-d\fR command is used, followed by the slice name.
123 .sp
124 .LP
125 When used with the \fB-i\fR option, \fBmetadb\fR displays the status of the
126 metadevice state databases. The status can change if a hardware failure occurs
127 or when state databases have been added or deleted.
128 .sp
129 .LP
130 To fix a replica in an error state, delete the replica and add it back again.
131 .sp
132 .LP
133 The metadevice state database (\fBmddb\fR) also contains a list of the replica
134 locations for this set (local or shared diskset).
135 .sp
136 .LP
137 The local set \fBmddb\fR can also contain host and drive information for each
138 of the shared disksets of which this node is a member. Other than the diskset
139 host and drive information stored in the local set \fBmddb\fR, the local and
140 shared diskset \fBmddb\fRs are functionality identical.
141 .sp
142 .LP
143 The \fBmddb\fRs are written to during the resync of a mirror or during a
144 component failure or configuration change. A configuration change or failure
145 can also occur on a single replica (removal of a \fBmddb\fR or a failed disk)
146 and this causes the other replicas to be updated with this failure information.
147 .SH OPTIONS
148 .sp
149 .LP
150 Root privileges are required for all of the following options except \fB-h\fR
151 and \fB-i\fR.
152 .sp
153 .LP
154 The following options can be used with the \fBmetadb\fR command. Not all the
155 options are compatible on the same command line. Refer to the \fBSYNOPSIS\fR to
156 see the supported use of the options.
157 .sp
158 .ne 2
159 .na
160 \fB\fB-a\fR\fR
161 .ad
162 .RS 18n
163 Attach a new database device. The \fB/kernel/drv/md.conf\fR file is
164 automatically updated with the new information and the \fB/etc/lvm/mddb.cf\fR
165 file is updated as well. An alternate way to create replicas is by defining
166 them in the \fB/etc/lvm/md.tab\fR file and specifying the assigned name at the
167 command line in the form, \fBmddb\fInn\fR\fR, where \fInn\fR is a two-digit
168 number given to the replica definitions. Refer to the \fBmd.tab\fR(4) man page
169 for instructions on setting up replicas in that file.
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fB-c\fR \fInumber\fR\fR
176 .ad
177 .RS 18n
178 Specifies the number of replicas to be placed on each device. The default
179 number of replicas is 1.
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fB\fB-d\fR\fR
186 .ad
187 .RS 18n
188 Deletes all replicas that are located on the specified \fIslice\fR. The
189 \fB/kernel/drv/md.conf\fR file is automatically updated with the new
190 information and the \fB/etc/lvm/mddb.cf\fR file is updated as well.
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fB\fB-f\fR\fR
197 .ad
198 .RS 18n
199 The \fB-f\fR option is used to create the initial state database. It is also
200 used to force the deletion of replicas below the minimum of one. (The \fB-a\fR
201 and \fB-f\fR options should be used together only when no state databases
202 exist.)
203 .RE
205 .sp
206 .ne 2
207 .na
208 \fB\fB-h\fR\fR
209 .ad
210 .RS 18n
211 Displays a usage message.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fB-i\fR\fR
218 .ad
219 .RS 18n
220 Inquire about the status of the replicas. The output of the \fB-i\fR option
221 includes characters in front of the device name that represent the status of
222 the state database. Explanations of the characters are displayed following the
223 replica status and are as follows:
224 .sp
225 .ne 2
226 .na
227 \fB\fBd\fR\fR
228 .ad
229 .RS 5n
230 replica does not have an associated device ID.
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fBo\fR\fR
237 .ad
238 .RS 5n
239 replica active prior to last \fBmddb\fR configuration change
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fB\fBu\fR\fR
246 .ad
247 .RS 5n
248 replica is up to date
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fBl\fR\fR
255 .ad
256 .RS 5n
257 locator for this replica was read successfully
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fBc\fR\fR
264 .ad
265 .RS 5n
266 replica's location was in \fB/etc/lvm/mddb.cf\fR
267 .RE
269 .sp
270 .ne 2
271 .na
272 \fB\fBp\fR\fR
273 .ad
274 .RS 5n
275 replica's location was patched in kernel
276 .RE
278 .sp
279 .ne 2
280 .na
281 \fB\fBm\fR\fR
282 .ad
283 .RS 5n
284 replica is master, this is replica selected as input
285 .RE
287 .sp
288 .ne 2
289 .na
290 \fB\fBr\fR\fR
291 .ad
292 .RS 5n
293 replica does not have device relocation information
294 .RE
296 .sp
297 .ne 2
298 .na
299 \fB\fBt\fR\fR
300 .ad
301 .RS 5n
302 tagged data is associated with the replica
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fBW\fR\fR
309 .ad
310 .RS 5n
311 replica has device write errors
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBa\fR\fR
318 .ad
319 .RS 5n
320 replica is active, commits are occurring to this
321 .RE
323 .sp
324 .ne 2
325 .na
326 \fB\fBM\fR\fR
327 .ad
328 .RS 5n
329 replica had problem with master blocks
330 .RE
332 .sp
333 .ne 2
334 .na
335 \fB\fBD\fR\fR
336 .ad
337 .RS 5n
338 replica had problem with data blocks
339 .RE
341 .sp
342 .ne 2
343 .na
344 \fB\fBF\fR\fR
345 .ad
346 .RS 5n
347 replica had format problems
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fBS\fR\fR
354 .ad
355 .RS 5n
356 replica is too small to hold current database
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBR\fR\fR
363 .ad
364 .RS 5n
365 replica had device read errors
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBB\fR\fR
372 .ad
373 .RS 5n
374 tagged data associated with the replica is not valid
375 .RE
377 .RE
379 .sp
380 .ne 2
381 .na
382 \fB\fB-k\fR \fIsystem-file\fR\fR
383 .ad
384 .RS 18n
385 Specifies the name of the kernel file where the replica information should be
386 written. The default \fIsystem-file\fR is \fB/kernel/drv/md.conf\fR. This
387 option is for use with the local diskset only.
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fB\fB-l\fR \fIlength\fR\fR
394 .ad
395 .RS 18n
396 Specifies the size of each replica. The default \fIlength\fR is 8192 blocks,
397 which should be appropriate for most configurations. "Replica" sizes of less
398 than 128 blocks are not recommended.
399 .RE
401 .sp
402 .ne 2
403 .na
404 \fB\fB-p\fR\fR
405 .ad
406 .RS 18n
407 Specifies updating the system file (\fB/kernel/drv/md.conf\fR) with entries
408 from the \fB/etc/lvm/mddb.cf\fR file. This option is normally used to update a
409 newly built system before it is booted for the first time. If the system has
410 been built on a system other than the one where it will run, the location of
411 the \fBmddb.cf\fR on the local machine can be passed as an argument. The system
412 file to be updated can be changed using the \fB-k\fR option. This option is for
413 use with the local diskset only.
414 .RE
416 .sp
417 .ne 2
418 .na
419 \fB\fB-s\fR \fIsetname\fR\fR
420 .ad
421 .RS 18n
422 Specifies the name of the diskset on which the \fBmetadb\fR command will work.
423 Using the \fB-s\fR option will cause the command to perform its administrative
424 function within the specified diskset. Without this option, the command will
425 perform its function on local database replicas.
426 .RE
428 .sp
429 .ne 2
430 .na
431 \fB\fIslice\fR\fR
432 .ad
433 .RS 18n
434 Specifies the logical name of the physical slice (partition), such as
435 \fB/dev/dsk/c0t0d0s3\fR.
436 .RE
438 .SH EXAMPLES
439 .LP
440 \fBExample 1 \fRCreating Initial State Database Replicas
441 .sp
442 .LP
443 The following example creates the initial state database replicas on a new
444 system.
446 .sp
447 .in +2
448 .nf
449 # metadb -a -f c0t0d0s7 c0t1d0s3 c1t0d0s7 c1t1d0s3
450 .fi
451 .in -2
452 .sp
454 .sp
455 .LP
456 The \fB-a\fR and \fB-f\fR options force the creation of the initial database
457 and replicas. You could then create metadevices with these same slices, making
458 efficient use of the system.
460 .LP
461 \fBExample 2 \fRAdding Two Replicas on Two New Disks
462 .sp
463 .LP
464 This example shows how to add two replicas on two new disks that have been
465 connected to a system currently running Volume Manager.
467 .sp
468 .in +2
469 .nf
470 # metadb -a c0t2d0s3 c1t1d0s3
471 .fi
472 .in -2
473 .sp
475 .LP
476 \fBExample 3 \fRDeleting Two Replicas
477 .sp
478 .LP
479 This example shows how to delete two replicas from the system. Assume that
480 replicas have been set up on \fB/dev/dsk/c0t2d0s3\fR and
481 \fB/dev/dsk/c1t1d0s3\fR.
483 .sp
484 .in +2
485 .nf
486 # metadb -d c0t2d0s3 c1t1d0s3
487 .fi
488 .in -2
489 .sp
491 .sp
492 .LP
493 Although you can delete all replicas, you should never do so while metadevices
494 still exist. Removing all replicas causes existing metadevices to become
495 inoperable.
497 .SH FILES
498 .sp
499 .ne 2
500 .na
501 \fB\fB/etc/lvm/mddb.cf\fR\fR
502 .ad
503 .RS 23n
504 Contains the location of each copy of the metadevice state database.
505 .RE
507 .sp
508 .ne 2
509 .na
510 \fB\fB/etc/lvm/md.tab\fR\fR
511 .ad
512 .RS 23n
513 Workspace file for metadevice database configuration.
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fB/kernel/drv/md.conf\fR\fR
520 .ad
521 .RS 23n
522 Contains database replica information for all metadevices on a system. Also
523 contains Solaris Volume Manager configuration information.
524 .RE
526 .SH EXIT STATUS
527 .sp
528 .LP
529 The following exit values are returned:
530 .sp
531 .ne 2
532 .na
533 \fB\fB0\fR\fR
534 .ad
535 .RS 6n
536 successful completion
537 .RE
539 .sp
540 .ne 2
541 .na
542 \fB\fB>0\fR\fR
543 .ad
544 .RS 6n
545 an error occurred
546 .RE
548 .SH ATTRIBUTES
549 .sp
550 .LP
551 See \fBattributes\fR(5) for descriptions of the following attributes:
552 .sp
554 .sp
555 .TS
556 box;
557 c | c
558 l | l .
559 ATTRIBUTE TYPE ATTRIBUTE VALUE
560 _
561 Interface Stability Stable
562 .TE
564 .SH SEE ALSO
565 .sp
566 .LP
567 \fBmdmonitord\fR(1M), \fBmetaclear\fR(1M), \fBmetadetach\fR(1M),
568 \fBmetahs\fR(1M), \fBmetainit\fR(1M), \fBmetaoffline\fR(1M),
569 \fBmetaonline\fR(1M), \fBmetaparam\fR(1M), \fBmetarecover\fR(1M),
570 \fBmetarename\fR(1M), \fBmetareplace\fR(1M), \fBmetaroot\fR(1M),
571 \fBmetaset\fR(1M), \fBmetassist\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M),
572 \fBmetattach\fR(1M), \fBmd.tab\fR(4), \fBmd.cf\fR(4), \fBmddb.cf\fR(4),
573 \fBmd.tab\fR(4), \fBattributes\fR(5), \fBmd\fR(7D)
574 .sp
575 .LP
576 \fI\fR
577 .SH NOTES
578 .sp
579 .LP
580 Replicas cannot be stored on fabric-attached storage, SANs, or other storage
581 that is not directly attached to the system. Replicas must be on storage that
582 is available at the same point in the boot process as traditional SCSI or IDE
583 drives. A replica can be stored on a:
584 .RS +4
585 .TP
586 .ie t \(bu
587 .el o
588 Dedicated local disk partition
589 .RE
590 .RS +4
591 .TP
592 .ie t \(bu
593 .el o
594 Local partition that will be part of a volume
595 .RE
596 .RS +4
597 .TP
598 .ie t \(bu
599 .el o
600 Local partition that will be part of a UFS logging device
601 .RE