| blob | 0fdd8585aba7be85417c26515da6d8f67abdc6d3 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2012 Joshua M. Clulow <josh@sysmgr.org>
4 .\" 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 .\" See the License for the specific language governing permissions and limitations under the License. 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
6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH FMDUMP 8 "Apr 14, 2009"
8 .SH NAME
9 fmdump \- fault management log viewer
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBfmdump\fR [\fB-efmvV\fR] [\fB-c\fR \fIclass\fR] [\fB-R\fR \fIdir\fR] [\fB-t\fR \fItime\fR] [\fB-T\fR \fItime\fR]
14 [\fB-u\fR \fIuuid\fR] [\fB-n\fR \fIname\fR[.\fIname\fR]*[=\fIvalue\fR]] [\fIfile\fR]
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBfmdump\fR utility can be used to display the contents of any of the log
21 files associated with the Fault Manager, \fBfmd\fR(8). The Fault
22 Manager runs in the background on each system. It receives telemetry
23 information relating to problems detected by the system software, diagnoses
24 these problems, and initiates proactive self-healing activities such as
25 disabling faulty components.
26 .sp
27 .LP
28 The Fault Manager maintains two sets of log files for use by administrators and
29 service personnel:
30 .sp
31 .ne 2
32 .na
33 \fBerror log\fR
34 .ad
35 .RS 13n
36 A log which records error telemetry, the symptoms of problems detected by the
37 system.
38 .RE
40 .sp
41 .ne 2
42 .na
43 \fBfault log\fR
44 .ad
45 .RS 13n
46 A log which records fault diagnosis information, the problems believed to
47 explain these symptoms.
48 .RE
50 .sp
51 .LP
52 By default, \fBfmdump\fR displays the contents of the fault log, which records
53 the result of each diagnosis made by the fault manager or one of its component
54 modules.
55 .sp
56 .LP
57 An example of a default \fBfmdump\fR display follows:
58 .sp
59 .in +2
60 .nf
61 # fmdump
62 TIME UUID SUNW-MSG-ID
63 Dec 28 13:01:27.3919 bf36f0ea-9e47-42b5-fc6f-c0d979c4c8f4 FMD-8000-11
64 Dec 28 13:01:49.3765 3a186292-3402-40ff-b5ae-810601be337d FMD-8000-11
65 Dec 28 13:02:59.4448 58107381-1985-48a4-b56f-91d8a617ad83 FMD-8000-OW
66 \&...
67 .fi
68 .in -2
69 .sp
71 .sp
72 .LP
73 Each problem recorded in the fault log is identified by:
74 .RS +4
75 .TP
76 .ie t \(bu
77 .el o
78 The time of its diagnosis
79 .RE
80 .RS +4
81 .TP
82 .ie t \(bu
83 .el o
84 A Universal Unique Identifier (UUID) that can be used to uniquely identify this
85 particular problem across any set of systems
86 .RE
87 .RS +4
88 .TP
89 .ie t \(bu
90 .el o
91 A message identifier that can be used to access a corresponding knowledge
92 article located on http://illumos.org/msg/
93 .RE
94 .sp
95 .LP
96 If a problem requires action by a human administrator or service technician or
97 affects system behavior, the Fault Manager also issues a human-readable message
98 to \fBsyslogd\fR(8). This message provides a summary of the problem and a
99 reference to the knowledge article on http://illumos.org/msg/.
100 .sp
101 .LP
102 You can use the \fB-v\fR and \fB-V\fR options to expand the display from a
103 single-line summary to increased levels of detail for each event recorded in
104 the log. The \fB-c\fR, \fB-t\fR, \fB-T\fR, and \fB-u\fR options can be used to
105 filter the output by selecting only those events that match the specified
106 \fIclass\fR, range of times, or \fIuuid\fR.
107 .sp
108 .LP
109 If more than one filter option is present on the command-line, the options
110 combine to display only those events that are selected by the logical \fBAND\fR
111 of the options. If more than one instance of the same filter option is present
112 on the command-line, the like options combine to display any events selected by
113 the logical \fBOR\fR of the options. For example, the command:
114 .sp
115 .in +2
116 .nf
117 # fmdump -u uuid1 -u uuid2 -t 02Dec03
118 .fi
119 .in -2
120 .sp
122 .sp
123 .LP
124 selects events whose attributes are \fB(uuid1 OR uuid2\fR) \fBAND\fR (time on
125 or after 02Dec03).
126 .SH OPTIONS
127 .sp
128 .LP
129 The following options are supported:
130 .sp
131 .ne 2
132 .na
133 \fB\fB-c\fR \fIclass\fR\fR
134 .ad
135 .sp .6
136 .RS 4n
137 Select events that match the specified class. The class argument can use the
138 glob pattern matching syntax described in \fBsh\fR(1). The class represents a
139 hierarchical classification string indicating the type of telemetry event.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fB-e\fR\fR
146 .ad
147 .sp .6
148 .RS 4n
149 Display events from the fault management error log instead of the fault log.
150 This option is shorthand for specifying the pathname of the error log file.
151 .sp
152 The error log file contains Private telemetry information. This information is
153 recorded to facilitate post-mortem analysis of problems and event replay, and
154 should not be parsed or relied upon for the development of scripts or other
155 tools.
156 .RE
158 .sp
159 .ne 2
160 .na
161 \fB\fB-f\fR\fR
162 .ad
163 .sp .6
164 .RS 4n
165 Follow the growth of the log file by waiting for additional data. \fBfmdump\fR
166 enters an infinite loop where it will sleep for a second, attempt to read and
167 format new data from the log file, and then go back to sleep. This loop can be
168 terminated at any time by sending an interrupt (\fBControl-C\fR).
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fB-m\fR\fR
175 .ad
176 .sp .6
177 .RS 4n
178 Print the localized diagnosis message associated with each entry in the fault
179 log.
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fB\fB-n\fR \fIname\fR[.\fIname\fR]*[=\fIvalue\fR]\fR
186 .ad
187 .sp .6
188 .RS 4n
189 Select fault log or error log events, depending on the \fB-e\fR option, that
190 have properties with a matching name (and optionally a matching value). For
191 string properties the value can be a regular expression match. Regular
192 expression syntax is described in the EXTENDED REGULAR EXPRESSIONS section of
193 the \fBregex\fR(5) manual page. Be careful when using the characters:
194 .sp
195 .in +2
196 .nf
197 $ * { ^ | ( ) \e
198 .fi
199 .in -2
200 .sp
202 \&...or a regular expression, because these are meaningful to the shell. It is
203 safest to enclose any of these in single quotes. For numeric properties, the
204 value can be octal, hex, or decimal.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fB-R\fR \fIdir\fR\fR
211 .ad
212 .sp .6
213 .RS 4n
214 Use the specified root directory for the log files accessed by \fBfmdump\fR,
215 instead of the default root (\fB/\fR).
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fB-t\fR \fItime\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 Select events that occurred at or after the specified time. The time can be
226 specified using any of the following forms:
227 .sp
228 .ne 2
229 .na
230 \fB\fB\fImm\fR/\fIdd\fR/\fIyy hh\fR:\fImm\fR:\fIss\fR\fR\fR
231 .ad
232 .sp .6
233 .RS 4n
234 Month, day, year, hour in 24-hour format, minute, and second. Any amount of
235 whitespace can separate the date and time. The argument should be quoted so
236 that the shell interprets the two strings as a single argument.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fB\fImm\fR/\fIdd\fR/\fIyy hh\fR:\fImm\fR\fR\fR
243 .ad
244 .sp .6
245 .RS 4n
246 Month, day, year, hour in 24-hour format, and minute. Any amount of whitespace
247 can separate the date and time. The argument should be quoted so that the shell
248 interprets the two strings as a single argument.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fB\fImm\fR/\fIdd\fR/\fIyy\fR\fR\fR
255 .ad
256 .sp .6
257 .RS 4n
258 12:00:00AM on the specified month, day, and year.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fB\fIddMonyy hh\fR:\fImm\fR:\fIss\fR\fR\fR
265 .ad
266 .sp .6
267 .RS 4n
268 Day, month name, year, hour in 24-hour format, minute, and second. Any amount
269 of whitespace can separate the date and time. The argument should be quoted so
270 that the shell interprets the two strings as a single argument.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fB\fIddMonyy hh\fR:\fImm\fR\fR\fR
277 .ad
278 .sp .6
279 .RS 4n
280 Day, month name, year, hour in 24-hour format, and minute. Any amount of
281 whitespace can separate the date and time. The argument should be quoted so
282 that the shell interprets the two strings as a single argument.
283 .RE
285 .sp
286 .ne 2
287 .na
288 \fB\fB\fIMon\fR \fIdd\fR \fIhh\fR:\fImm\fR:\fIss\fR\fR\fR
289 .ad
290 .sp .6
291 .RS 4n
292 Month, day, hour in 24-hour format, minute, and second of the current year.
293 .RE
295 .sp
296 .ne 2
297 .na
298 \fB\fB\fIyyyy\fR-\fImm\fR-\fIdd\fR [T \fIhh\fR:\fImm\fR[:\fIss\fR]]\fR\fR
299 .ad
300 .sp .6
301 .RS 4n
302 Year, month, day, and optional hour in 24-hour format, minute, and second. The
303 second, or hour, minute, and second, can be optionally omitted.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fB\fIddMonyy\fR\fR
310 .ad
311 .sp .6
312 .RS 4n
313 12:00:00AM on the specified day, month name, and year.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fB\fIhh\fR:\fImm\fR:\fIss\fR\fR\fR
320 .ad
321 .sp .6
322 .RS 4n
323 Hour in 24-hour format, minute, and second of the current day.
324 .RE
326 .sp
327 .ne 2
328 .na
329 \fB\fB\fIhh\fR:\fImm\fR\fR\fR
330 .ad
331 .sp .6
332 .RS 4n
333 Hour in 24-hour format and minute of the current day.
334 .RE
336 .sp
337 .ne 2
338 .na
339 \fB\fIT\fR\fBns\fR | \fIT\fR\fBnsec\fR\fR
340 .ad
341 .sp .6
342 .RS 4n
343 \fIT\fR nanoseconds ago where T is an integer value specified in base 10.
344 .RE
346 .sp
347 .ne 2
348 .na
349 \fB\fB\fIT\fRus |\fIT\fRusec\fR\fR
350 .ad
351 .sp .6
352 .RS 4n
353 \fIT\fR microseconds ago where T is an integer value specified in base 10.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fIT\fR\fBms\fR | \fIT\fR\fBmsec\fR\fR
360 .ad
361 .sp .6
362 .RS 4n
363 T milliseconds ago where T is an integer value specified in base 10.
364 .RE
366 .sp
367 .ne 2
368 .na
369 \fB\fB\fIT\fRs | \fIT\fRsec\fR\fR
370 .ad
371 .sp .6
372 .RS 4n
373 T seconds ago where \fIT\fR is an integer value specified in base 10.
374 .RE
376 .sp
377 .ne 2
378 .na
379 \fB\fB\fIT\fRm |\fIT\fRmin\fR\fR
380 .ad
381 .sp .6
382 .RS 4n
383 \fIT\fR minutes ago where \fIT\fR is an integer value specified in base 10.
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fB\fIT\fRh |\fIT\fRhour\fR\fR
390 .ad
391 .sp .6
392 .RS 4n
393 \fIT\fR hours ago where \fIT\fR is an integer value specified in base 10.
394 .RE
396 .sp
397 .ne 2
398 .na
399 \fB\fB\fIT\fRd |\fIT\fRday\fR\fR
400 .ad
401 .sp .6
402 .RS 4n
403 \fIT\fR days ago where \fIT\fR is an integer value specified in base 10.
404 .RE
406 You can append a decimal fraction of the form \fB\&.\fR\fIn\fR to any \fB-t\fR
407 option argument to indicate a fractional number of seconds beyond the specified
408 time.
409 .RE
411 .sp
412 .ne 2
413 .na
414 \fB\fB-T\fR \fItime\fR\fR
415 .ad
416 .sp .6
417 .RS 4n
418 Select events that occurred at or before the specified time. \fItime\fR can be
419 specified using any of the time formats described for the \fB-t\fR option.
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fB-u\fR \fIuuid\fR\fR
426 .ad
427 .sp .6
428 .RS 4n
429 Select fault diagnosis events that exactly match the specified \fIuuid\fR. Each
430 diagnosis is associated with a Universal Unique Identifier (UUID) for
431 identification purposes. The \fB-u\fR option can be combined with other options
432 such as \fB-v\fR to show all of the details associated with a particular
433 diagnosis.
434 .sp
435 If the \fB-e\fR option and \fB-u\fR option are both present, the error events
436 that are cross-referenced by the specified diagnosis are displayed.
437 .RE
439 .sp
440 .ne 2
441 .na
442 \fB\fB-v\fR\fR
443 .ad
444 .sp .6
445 .RS 4n
446 Display verbose event detail. The event display is enlarged to show additional
447 common members of the selected events.
448 .RE
450 .sp
451 .ne 2
452 .na
453 \fB\fB-V\fR\fR
454 .ad
455 .sp .6
456 .RS 4n
457 Display very verbose event detail. The event display is enlarged to show every
458 member of the name-value pair list associated with each event. In addition, for
459 fault logs, the event display includes a list of cross-references to the
460 corresponding errors that were associated with the diagnosis.
461 .RE
463 .SH OPERANDS
464 .sp
465 .LP
466 The following operands are supported:
467 .sp
468 .ne 2
469 .na
470 \fB\fIfile\fR\fR
471 .ad
472 .RS 8n
473 Specifies an alternate log file to display instead of the system fault log. The
474 \fBfmdump\fR utility determines the type of the specified log automatically and
475 produces appropriate output for the selected log.
476 .RE
478 .SH EXAMPLES
479 .LP
480 \fBExample 1 \fRRetrieving Given Class from \fBfmd\fR Log
481 .sp
482 .LP
483 Use any of the following commands to retrieve information about a specified
484 class from the \fBfmd\fR log. The complete class name is
485 \fBereport.io.ddi.context\fR.
487 .sp
488 .in +2
489 .nf
490 # \fBfmdump -Ve -c 'ereport.io.ddi.context'\fR
491 # \fBfmdump -Ve -c 'ereport.*.context'\fR
492 # \fBfmdump -Ve -n 'class=ereport.io.ddi.context'\fR
493 # \fBfmdump -Ve -n 'class=ereport.*.context'\fR
494 .fi
495 .in -2
496 .sp
498 .sp
499 .LP
500 Any of the preceding commands produces the following output:
502 .sp
503 .in +2
504 .nf
505 Oct 06 2007 11:53:20.975021712 ereport.io.ddi.context
506 nvlist version: 0
507 class = ereport.io.ddi.context
508 ena = 0x1b03a15ecf00001
509 detector = (embedded nvlist)
510 nvlist version: 0
511 version = 0x0
512 scheme = dev
513 device-path = /
514 (end detector)
516 __ttl = 0x1
517 __tod = 0x470706b0 0x3a1da690
518 .fi
519 .in -2
520 .sp
522 .LP
523 \fBExample 2 \fRRetrieving Specific Detector Device Path from \fBfmd\fR Log
524 .sp
525 .LP
526 The following command retrieves a detector device path from the \fBfmd\fR log.
528 .sp
529 .in +2
530 .nf
531 # \fBfmdump -Ve -n 'detector.device-path=.*/disk@1,0$'\fR
532 Oct 06 2007 12:04:28.065660760 ereport.io.scsi.disk.rqs
533 nvlist version: 0
534 class = ereport.io.scsi.disk.rqs
535 ena = 0x453ff3732400401
536 detector = (embedded nvlist)
537 nvlist version: 0
538 version = 0x0
539 scheme = dev
540 device-path = /pci@0,0/pci1000,3060@3/disk@1,0
541 (end detector)
543 __ttl = 0x1
544 __tod = 0x4707094c 0x3e9e758
545 .fi
546 .in -2
547 .sp
549 .SH EXIT STATUS
550 .sp
551 .LP
552 The following exit values are returned:
553 .sp
554 .ne 2
555 .na
556 \fB\fB0\fR\fR
557 .ad
558 .RS 5n
559 Successful completion. All records in the log file were examined successfully.
560 .RE
562 .sp
563 .ne 2
564 .na
565 \fB\fB1\fR\fR
566 .ad
567 .RS 5n
568 A fatal error occurred. This prevented any log file data from being examined,
569 such as failure to open the specified file.
570 .RE
572 .sp
573 .ne 2
574 .na
575 \fB\fB2\fR\fR
576 .ad
577 .RS 5n
578 Invalid command-line options were specified.
579 .RE
581 .sp
582 .ne 2
583 .na
584 \fB\fB3\fR\fR
585 .ad
586 .RS 5n
587 The log file was opened successfully, but one or more log file records were not
588 displayed, either due to an I/O error or because the records themselves were
589 malformed. \fBfmdump\fR issues a warning message for each record that could not
590 be displayed, and then continues on and attempts to display other records.
591 .RE
593 .SH FILES
594 .sp
595 .ne 2
596 .na
597 \fB\fB/var/fm/fmd\fR\fR
598 .ad
599 .RS 22n
600 Fault management log directory
601 .RE
603 .sp
604 .ne 2
605 .na
606 \fB\fB/var/fm/fmd/errlog\fR\fR
607 .ad
608 .RS 22n
609 Fault management error log
610 .RE
612 .sp
613 .ne 2
614 .na
615 \fB\fB/var/fm/fmd/fltlog\fR\fR
616 .ad
617 .RS 22n
618 Fault management fault log
619 .RE
621 .SH ATTRIBUTES
622 .sp
623 .LP
624 See \fBattributes\fR(5) for descriptions of the following attributes:
625 .sp
627 .sp
628 .TS
629 box;
630 c | c
631 l | l .
632 ATTRIBUTE TYPE ATTRIBUTE VALUE
633 _
634 Interface Stability See below.
635 .TE
637 .sp
638 .LP
639 The command-line options are Evolving. The human-readable error log output is
640 Private. The human-readable fault log output is Evolving.
641 .SH SEE ALSO
642 .sp
643 .LP
644 \fBsh\fR(1), \fBfmadm\fR(8), \fBfmd\fR(8), \fBfmstat\fR(8),
645 \fBsyslogd\fR(8), \fBlibexacct\fR(3LIB), \fBattributes\fR(5), \fBregex\fR(5)
646 .sp
647 .LP
648 \fI\fR
649 .sp
650 .LP
651 http://illumos.org/msg/
652 .SH NOTES
653 .sp
654 .LP
655 Fault logs contain references to records stored in error logs that can be
656 displayed using \fBfmdump\fR \fB-V\fR to understand the errors that were used
657 in the diagnosis of a particular fault. These links are preserved if an error
658 log is renamed as part of log rotation. They can be broken by removing an error
659 log file, or by moving it to another filesystem directory. \fBfmdump\fR can not
660 display error information for such broken links. It continues to display any
661 and all information present in the fault log.