xref: /freebsd/contrib/smart/smart.8 (revision 7419d6e463fee40f0f52cd5bc46a93cbb7ac6114)

.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2021-2026 Chuck Tuffli
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd February 14, 2026
.Dt SMART 8
.Os
.Sh NAME
.Nm smart ,
.Nm diskhealth
.Nd monitor disk health from a storage device via SMART
.Sh SYNOPSIS
.Nm
.Op Fl dhitvx
.Oo Fl a Ar page:attribute Ns Oo , Ns Ar page:attribute Oc Ns ... Oc
.Op Fl Fl debug
.Ar device
.Nm diskhealth
.Op Fl Dhitvx
.Oo Fl a Ar page:attribute Ns Oo , Ns Ar page:attribute Oc Ns ... Oc
.Op Fl Fl debug
.Ar device
.Sh DESCRIPTION
The
.Nm
command allows the user to monitor the various information reported
by Self-Monitoring, Analysis and Reporting Technology (SMART) present
on most ATA, SCSI, and NVMe storage media.
Because the structure of this information varies across protocols,
.Nm
normalizes entries using the format:
.Bd -literal
	<Page ID>    <Attribute ID>    <Value>    <Thresholds>
.Ed
.Pp
Fields are tab-delimited by default, but the command can output
data in any format supported by
.Xr libxo 3 .
.Pp
Because ATA does not have log pages,
.Nm
uses the Command Feature field value in place of the log page ID.
For SMART READ DATA, this value is 208 / 0xd0.
Note that devices choose which attribute ID values they support, their
descriptions, and the format of the data.
The three values displayed with the
.Fl Fl threshold
option are:
.Pp
.Bl -dash -compact -offset indent
.It
Status flags (byte offset 1, 2 bytes)
.It
Nominal attribute value (byte offset 3, 1 byte)
.It
Worst Ever attribute value (byte offset 4, 1 byte)
.El
.Pp
Additionally,
.Nm
reports the value of the SMART STATUS command (Command Feature field
value 218 / 0xda).
As this command does not return any data,
the command represents this entry with a synthetic attribute
ID of 0, and it uses the command status (0 or 1) as the attribute
value.
.Pp
NVMe devices support the SMART/Health log page (Page ID 2 / 0x2).
The data returned in this log page is not structured as attribute IDs.
Instead,
.Nm
uses the byte offset of each field as the attribute ID.
For example,
byte 3 is the Available Spare.
Thus, for NVMe, attribute ID 3 is
Available Spare.
Note that NVMe health data does not include threshold
values, and as a result, the command will ignore the
.Fl Fl threshold
option.
.Pp
SCSI devices can support a number of log pages which report drive
health.
The command will report the following pages:
.Pp
.Bl -dash -compact -offset indent
.It
Write Errors (Page ID 2 / 0x2)
.It
Read Errors (Page ID 3 / 0x3)
.It
Verify Errors (Page ID 5 / 0x5)
.It
Non-medium Errors (Page ID 6 / 0x6)
.It
Last N Errors (Page ID 7 / 0x7)
.It
Temperature (Page ID 13 / 0xd)
.It
Start-stop Cycles (Page ID 14 / 0xe)
.It
Informational Exceptions (Page ID 47 / 0x2f)
.El
.Pp
Note that all log pages are optional, and a particular drive
may not support all these pages.
For SCSI devices, the Attribute ID
maps to the SCSI parameter code defined by the command.
Parameter
codes are integer values from 0 to N, and, by themselves, are ambiguous
outside the context of a particular log page.
Note that SCSI health data
does not include threshold values, and as a result, the command will
ignore the
.Fl Fl threshold
option.
.Pp
The following options are available:
.Bl -tag -width "-d argument"
.It Fl a Ar page:attribute , Fl Fl attribute= Ns Ar page:attribute
A comma-separated list of attributes to display.
If page is missing, display the matching attribute from any page.
.It Fl d , Fl Fl decode
Decode the attribute ID values.
This is the default when invoked as
.Nm diskhealth .
.It Fl D , Fl Fl no-decode
Do not decode the attribute ID values.
This is the default when invoked as
.Nm .
.It Fl h , Fl Fl help
Prints a usage message and exits.
.It Fl i , Fl Fl info
Print general device information.
.It Fl t , Fl Fl threshold
Also print the threshold values.
.It Fl v , Fl Fl version
Print the version and copyright.
.It Fl x , Fl Fl hex
Print the values in hexadecimal.
.It Ar device
An explicit device path
.Pq Pa /dev/ada0
or GEOM provider
.Pq Pa ada0
.
.El
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Print all SMART READ DATA and SMART STATUS including the
threshold values for ATA drive ada0.
.Pp
.Dl # smart -t ada0
.Pp
Print only attribute ID 5 ("Reallocated Sectors Count") for
ATA drive ada0.
.Pp
.Dl # smart -a 5 ada0
.Pp
Print attribute IDs 5 ("Reallocated Sectors Count") and 171
("SSD Program Fail") for ATA drive ada0.
.Pp
.Dl # smart -a 5,171 ada0
.Pp
Print all health pages supported by SCSI device da0 including:
.Bl -dash -compact -offset indent
.It
Write Errors
.It
Read Errors
.It
Verify Errors
.It
Non-medium Errors
.It
Last N Errors
.It
Temperature
.It
Start-stop Cycles
.It
Informational Exceptions
.El
.Pp
.Dl # smart da0
.Pp
Print all Health log page entries in hexadecimal for NVMe
device nda0.
.Pp
.Dl # smart -x nda0
.Sh DIAGNOSTICS
The command may fail for one of the following reasons:
.Bl -diag
.It "No output displayed"
The device does not support health data.
.It "CAMGETPASSTHRU ioctl failed"
.Nm
relies on
.Xr cam 4
to retrieve data from devices and will display this message if the
device does not have a passthrough driver.
This can happen, for
example, if the system uses the
.Xr nvd 4
NVMe driver instead of the
.Xr nda 4
driver.
.El
.Sh SEE ALSO
.Xr libxo 3 ,
.Xr cam 4 ,
.Xr nda 4 ,
.Xr nvd 4
.Sh AUTHORS
This
utility was written by
.An Chuck Tuffli Aq Mt chuck@FreeBSD.org .
.Sh BUGS
Probably.