usr/src/man/man1m/fmdump.1m

   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 1M "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 \fIuid\fR] [\fB-n\fR \fIname\fR[.\fIname\fR]*[=\fIvalue\fR]] [\fIfile\fR]
  15 .fi
  16
  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(1M). 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
  39
  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
  49
  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
  70
  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(1M). 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
 121
 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
 141
 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
 157
 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
 170
 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
 181
 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
 201
 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
 206
 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
 217
 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
 238
 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
 250
 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
 260
 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
 272
 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
 284
 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
 294
 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
 305
 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
 315
 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
 325
 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
 335
 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
 345
 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
 355
 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
 365
 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
 375
 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
 385
 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
 395
 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
 405
 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
 410
 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
 421
 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
 438
 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
 449
 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
 462
 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
 477
 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.
 486
 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
 497
 498 .sp
 499 .LP
 500 Any of the preceding commands produces the following output:
 501
 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)
 515
 516                 __ttl = 0x1
 517                 __tod = 0x470706b0 0x3a1da690
 518 .fi
 519 .in -2
 520 .sp
 521
 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.
 527
 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)
 542
 543                 __ttl = 0x1
 544                 __tod = 0x4707094c 0x3e9e758
 545 .fi
 546 .in -2
 547 .sp
 548
 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
 561
 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
 571
 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
 580
 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
 592
 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
 602
 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
 611
 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
 620
 621 .SH ATTRIBUTES
 622 .sp
 623 .LP
 624 See \fBattributes\fR(5) for descriptions of the following attributes:
 625 .sp
 626
 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
 636
 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(1M), \fBfmd\fR(1M), \fBfmstat\fR(1M),
 645 \fBsyslogd\fR(1M), \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.