smartctl.8

\# Copyright (C) 2002 Bruce Allen <smartmontools-support@lists.sourceforge.net>
\#
\# $Id: smartctl.8,v 1.27 2002/11/22 13:44:00 ballen4705 Exp $
\# 
\# This program is free software; you can redistribute it and/or modify it
\# under the terms of the GNU General Public License as published by the Free
\# Software Foundation; either version 2, or (at your option) any later
\# version.
\# 
\# You should have received a copy of the GNU General Public License (for
\# example COPYING); if not, write to the Free Software Foundation, Inc., 675
\# Mass Ave, Cambridge, MA 02139, USA.
\#
\# This code was originally developed as a Senior Thesis by Michael Cornwell
\# at the Concurrent Systems Laboratory (now part of the Storage Systems
\# Research Center), Jack Baskin School of Engineering, University of
\# California, Santa Cruz. http://ssrc.soe.ucsc.edu/
\#
.TH SMARTCTL 8  "$Date: 2002/11/22 13:44:00 $" "smartmontools-5.0"
.SH NAME
smartctl \- S.M.A.R.T. control and monitor utility 
.SH SYNOPSIS
.B smartctl \-[ViaqQnNPUWedtTfFcgvlLm[O|S|s|X|x|A]] device

.SH DESCRIPTION
.B smartctl
controls the Self-Monitoring, Analysis and Reporting Technology
(S.M.A.R.T.) system built into many ATA-3 and later ATA, IDE and
SCSI-3 hard drives. The purpose of S.M.A.R.T. is to monitor the
reliability of the hard drive and predict drive failures, and to carry
out different types of drive self-tests.  This version of smartctl is
compatible with ATA/ATAPI-5 and earlier standards (see REFERENCES
below)

.B smartctl
is a command line utility designed to perform S.M.A.R.T. tasks such as
printing the S.M.A.R.T. self-test and error logs, and enabling and
disabling S.M.A.R.T. automatic testing. Note: if the user issues a
S.M.A.R.T. command that is (apparently) not implemented by the device,
we print a warning message but issue the command anyway.  This should
not cause problems: unimplemented S.M.A.R.T. commands issued to a
drive are ignored and return an error.

.B smartctl
also provides limited TapeAlerts support for some SCSI tape drives and
changers.
.PP
.SH SYNTAX
.PP
.B smartctl 
takes two arguments, options and device. Examples are given below.

The first argument, options, begins with a '\-' followed by
letters. Multiple options must begin with a single '\-'.  The order of
the options does not matter.

The second argument is the device to be controlled or
interrogated. ATA devices use the form "/dev/hd*" and SCSI devices use
the form "/dev/sd*".  More general paths may also be specified.
.B Smartctl
will attempt to guess the device type.  If needed, use the '\-n' and '\-N'
options respectively for specifying ATA and SCSI device type.

SCSI devices only accept the options 
.B a, i, c, e, d, O, s, S, x, X, A, N 
and 
.B V. 
For SCSI Tape Drives and Changers with TapeAlerts support use
the devices "/dev/st*" and "/dev/sg*". TapeAlerts devices accept the
options 
.B a, i, c, e, d, N
and 
.B V.

The options are grouped below into several categories.
.B smartctl
will execute these in the order: INFORMATION, ENABLE/DISABLE, DISPLAY
DATA, RUN/ABORT TESTS.

.PP
.SH OPTIONS
.TP
.B SHOW INFORMATION:
.TP
.B V
Version: Prints version, Copyright, License, home page and CVS-id
information for your copy of
.B smartctl.
Please include this information if you are reporting
bugs or problems.
.TP
.B i
Information: Prints the disk model number, serial number,
firmware version, and ATA Standard version/revision information.
Says if the device supports S.M.A.R.T., and if so, whether
S.M.A.R.T. support is currently enabled or disabled.
.TP
.B a
All: Prints all parameters for c,i,g,v,t,l,L (for SCSI c,i).  This prints all
S.M.A.R.T. information about the disk.
.TP
.B RUN-TIME BEHAVIOR:
.TP
.B q
Quiet mode: Only print: For the '\-l' option, if nonzero, the number
of errors recorded in the SMART error log and the power-on time when
they occured; For the '\-L' option, errors recorded in the device
self-test log; For the '\-c' SMART "disk failing" status or device
attributes (pre-failure or usage) which failed either now or in the
past; For the '\-v' option device attributes (pre-failure or usage)
which failed either now or in the past.
.TP
.B Q
Very Quiet mode: Print no ouput.  The only way to learn about what was
found is to use the exit status of
.B smartctl
(see RETURN VALUES below).
.TP
.B n
NotSCSI: Device is an ATA device.
.TP
.B N
NotATA: Device is a SCSI device. If neither this nor the previous
option are specified, then
.B smartctl
will attempt to guess the device type from the device name.  You can
use this option or the previous option to force the type.
.TP
.B P
Permissive: If a mandatory S.M.A.R.T. command to the
disk fails, do
.I not
exit, but carry on in spite of it. Normally (without this option
enabled)
.B smartctl
would exit with an error if a mandatory command failed.  Here 'mandatory'
means "Required by the ATA/ATAPI-5 Specification if the
device implements the S.M.A.R.T. command set."  The 'mandatory'
S.M.A.R.T. commands are: (1) Enable/Disable Attribute Autosave, (2)
Enable/Disable S.M.A.R.T., and (3) S.M.A.R.T. Return Status.
.TP
.B U
Ultraconservative: Exit
.B smartctl
immediately if an optional S.M.A.R.T. command to the disk fails.
Normally (without this option enabled)
.B smartctl
would just carry on if an optional command fails.  Here "optional"
means "Not required by the ATA/ATAPI-5 Specification even if the
device implements the S.M.A.R.T. command set."
.TP
.B W
Warning: Exit
.B smartctl
immediately if a checksum error is detected in the: (1) Device
Identity Structure, (2) S.M.A.R.T. Self-Test Log Structure, (3)
S.M.A.R.T. Attribute Value Structure, (4) S.M.A.R.T. Attribute
Threshold Structure, or (5) ATA Error Log Structure.  Normally
(without this option enabled)
.B smartctl
will report the incorrect checksum but will carry on in spite of it.
.TP
.B S.M.A.R.T. FEATURE ENABLE/DISABLE COMMANDS:
.IP
.B Note: 
if multiple options are used to both enable and disable a
feature, then 
.B both
the enable and disable commands will be issued.  The enable command
will always be issued
.B before
the correponding disable command.
.TP
.B e 
Enable: Enables S.M.A.R.T. on device.  Note that this command (perhaps
used with with the '\-t' and '\-f' options) should be placed in a
start-up script for your machine, for example in rc.local or
rc.sysinit. In princple the S.M.A.R.T. feature settings are preserved
over power-cycling, but it doesn't hurt to be sure.
.TP
.B d
Disable: Disables S.M.A.R.T. on device.  This turns off all
S.M.A.R.T. functionality. [I can't imagine why you would want to do
this. Or do you cover up the oil-pressure warning light on your car?]
.TP
.B t
Test: Enables S.M.A.R.T. automatic offline test which scans the drive
every four hours for disk defects. This command can be given during normal
system operation.

Note that the S.M.A.R.T. automatic offline test command is listed as 'Obsolete'
in every version of the ATA and ATA/ATAPI Specifications
that I can find.  However it is implemented and used by some
vendors. [Good documentation can be found in IBM's Official
Published Disk Specifications.  For example the IBM Travelstar 40GNX
Hard Disk Drive Specifications (Revision 1.1, 22 April 2002,
Publication # 1541, Document S07N-7715-02) page 164.]

S.M.A.R.T. provides three basic categories of testing.  The first
category, called 'online' testing, has no effect on the performance of
the device.  It is turned on by the '\-e' option.

The second category of testing is called 'offline' testing. This type
of test can, in principle, degrade the device performance.  The '\-t'
option causes this offline testing to be carried out, automatically,
on a regular scheduled basis.  Normally, the disk will suspend any
offline testing while disk accesses are taking place, then
automatically resume them when the disk would otherwise be idle, so in
practice it has little effect.  Note that a one-time offline test can
also be carried out immediately upon receipt of a user command.  See
the '\-O' option below, which causes a one-time offline test to be
carried out immediately.

Any errors detected in automatic or immediate offline testing will be
shown in the S.M.A.R.T. error log, and will be reflected in the values
of the S.M.A.R.T. attributes.  These are visible with the '\-l' and '\-v' options.

The third class of testing is the 'self' testing.  This third type of
test is only performed (immediately) when a command to run it is
issued.  The '\-S', '\-s', '\-X', '\-x', and '\-A' options below can
be used to carry out (and abort) such self-tests; please see below for further
details.

Any errors detected in the self testign will be shown in the
S.M.A.R.T. self-test log, which can be examined using the '\-L'
option.

.TP
.B T 
unTest: Disables S.M.A.R.T. automatic offline test timer. 
.TP
.B f
File: Enables S.M.A.R.T. autosave of device vendor-specific
attributes. Note that this feature is preserved across disk power
cycles, so you should only need to issue it once.
.TP
.B F
unFile: Disables S.M.A.R.T. autosave of device vendor-specific
attributes.  Note that this feature is preserved across disk power
cycles, so you should only need to issue it once.
.TP
.B S.M.A.R.T. READ AND DISPLAY DATA OPTIONS:
.TP
.B c
Check: Ask the device to report its S.M.A.R.T. health status.  It does
this using information that it has gathered from online and offline
tests, which were used to determine/update its
S.M.A.R.T. vendor-specific attribute values.

If the device reports failing health status, this means
.B either
that the device has already failed, 
.B or 
that it is predicting its own failure within the next 24 hours.  If
this happens, use the '\-a' option to get more information, and
.B get your data off the disk and someplace safe as soon as you can.
.TP
.B g
Generic: Prints only the generic S.M.A.R.T. attributes.  This shows
the S.M.A.R.T.  capabilities of the device (can it log errors, does it
support offline surface scanning, and so on).  If the device can carry
out self-tests, it also lists the estimated time required to run those
tests.  See REFERENCES below for further information about their
meaning.
.TP
.B v
Vendor: Prints only the vendor specific S.M.A.R.T. attributes.  The
attributes are numbered from 1 to 253 and have specific names. For
example attribute 12 is 'power cycle count': how many times has the
disk been powered up.  Each attribute has a 'Raw' value, printed under
the heading 'Raw Value', and a 'Normalized' value printed under the
heading 'Value'.  Each vendor uses their own magic to convert the Raw
value to a Normalized value.  If the Normalized value is
.B less than or equal to
the value given under the 'Threshold' column, then disk failure
is imminent.  The column labeled 'Worst' shows the lowest (closest to
failure) value that the disk has recorded at any time during its
lifetime when S.M.A.R.T.  was enabled.

Note that the conversion from 'Raw' value to physical units is not
specified by the S.M.A.R.T. standard. In most cases, the values printed by
.B smartctl
are sensible.  However in some cases a vendor uses unusual
conventions.  For example the Hitachi disk on my laptop reports its
power-on hours in minutes, not hours. Some IBM disks track three
temperatures rather than one, in their raw values.  And so on.

The table printed out by this option also shows the 'Type' of the
attribute.  Pre-failure attributes are ones which, if less than or
equal to their threshold values, indicate pending disk failure.  Old
age, or usage attributes, are ones which indicate end-of-product life
from old-age or normal aging and wearout, if the attribute value is
less than or equal to the threshold.

If the attribute's current value is <= threshold, then the 'Ever
failed' column will display 'FAILED NOW!'.  If not, but the worst
recorded value is <= threshold, then this column will display 'In the
past'.

Note that starting with ATA/ATAPI-4, revision 4, the meaning of these
attribute fields has been made entirely vendor-specific.  However most
ATA/ATAPI-5 disks seem to respect their meaning, so we have retained
this option.
.TP
.B l
Log: Prints only the S.M.A.R.T. error log.  S.M.A.R.T. disks maintain
a log of the most recent five non-trivial errors.  For each of these
errors, the disk power-on lifetime at which the error occurred is
recorded, as is the device status (idle, standby, etc) at the time of
the error.  Finally, up to the last five commands that preceded the
error are also recorded, along with a timestamp measured in seconds
from when the disk was powered up during the session where the error
took place.  [Note: this time stamp wraps after 2^32 milliseconds, or
49 days 17 hours 2 minutes and 47.296 seconds.]
The key ATA disk registers are also recorded in the log.
.TP
.B L
Log: Prints only the S.M.A.R.T. self-test log.  The disk maintains a
log showing the results of the self tests, which can be run using
the '\-S', '\-s', '\-X', and '\-x' options described below.  The log will
show, for each of the most recent twenty-one self-tests, the type of
test (short or extended, off-line or captive) and the final status of
the test.  If the test did not complete successfully, the percentage
of the test remaining is show.  The time at which the test took place,
measured in hours of disk lifetime, is shown.  If any errors were
detected, the Logical Block Address (LBA) of the first error is printed
in hexidecimal notation.
.TP
.B a
All: Prints all parameters for c,i,g,v,t,l,L (for SCSI c,i).  This prints all
S.M.A.R.T. information about the disk.
.TP
.B Vendor-specific Attribute Display Options:
.TP
.B m
Minutes: The disk stores Raw Attribute number 9 (power on time) in
minutes, rather than hours.  Divide by 60 before displaying it as "power
on hours" when using '\-v' or other options that display Raw values.
.TP
.B S.M.A.R.T. RUN/ABORT OFFLINE TEST AND SELF-TEST OPTIONS:
.IP
.B Note:
only a single one of these tests can be run at a time, so no more than one
of the following options should be given on the command line. 
.TP
.B O
Offline: Runs S.M.A.R.T. Immediate offline Test.  This immediately
starts the test describe above.  This command can be given during
normal system operation.  The effects of this test are visible only in
that it updates the S.M.A.R.T. attribute values, and if errors are
found they will appear in the S.M.A.R.T. error log, visible with the '\-l' option.
.TP
.B S 
Selftest: Runs S.M.A.R.T. Short Self Test (usually under ten minutes).
This command can be given during normal system operation.  This is a
test in a different category than the immediate or automatic offline
tests.  The 'Self' tests check the electrical and mechanical
performance as well as the read performance of the disk.  Their
results are reported in the Self Test Error Log, readable with
the '\-L' option.  Note that on some disks the progress of the test can be
monitored by watching this log during the test; with other disks use
the '\-g option to monitor progress.
.TP
.B s
Selftest: Runs the S.M.A.R.T. Short Self Test just described, in Captive Mode.
.B WARNING: This test may busy out the drive for the length of the test. 
.B Only run this on drives without any mounted partitions.
.TP
.B X
eXtended: Runs S.M.A.R.T. Extended Self Test (tens of minutes).  This is a
longer and more thorough version of the Short Self Test described
under the '\-S' option.  Note that this command can be given during normal
system operation.
.TP
.B x
eXtended: Runs the S.M.A.R.T. Extended Self Test just described, in Captive Mode.
.B WARNING: This test may busy out the drive for the length of the test.
.B Only run this on drives without any mounted partitions.
.TP
.B A
Abort: Aborts Non-Captive S.M.A.R.T. Self Tests.
.PP
.SH EXAMPLES
.nf
.B smartctl -a /dev/hda
.fi
Print all S.M.A.R.T. information for drive /dev/hda (Primary Master).
.PP
.nf
.B smartctl -d /dev/hdd
.fi
Disable S.M.A.R.T. on drive /dev/hdd (Secondary Slave).
.PP
.nf
.B smartctl -etf /dev/hda
.fi
Enable S.M.A.R.T. on drive /dev/hda, enable automatic offline
testing every four hours, and enable autosaving of
S.M.A.R.T. attributes.  This is a good start-up line for your system's
init files.  You can issue this command on a running system.
.PP
.nf
.B smartctl -X /dev/hdc
.fi
Begin an extended self-test of drive /dev/hdc.  You can issue this
command on a running system.  The results can be seen in the self-test
log visible with the '\-L' option after it has completed.
.PP
.nf
.B smartctl -eO /dev/hda
.fi
Enable S.M.A.R.T. on the disk, and begin an immediate offline test of
drive /dev/hda.  You can issue this command on a running system.  The
results uare only used to update the S.M.A.R.T. attributes, visible
with the '\-v' option.  If any device errors occur, they are logged
the S.M.A.R.T. error log., which can be seen with the '\-l' option.
.PP
.nf
.B smartctl -vm /dev/hda
.fi
Shows the vendor attributes, when the disk stores its power-on time
internally in minutes rather than hours.
.PP
.nf
.B smartctl -qcL /dev/hda
.fi
Produces output only if the device returns failing S.M.A.R.T. status,
or if some of the logged self-tests ended with errors.
.PP
.nf
.B smartctl -Qa /dev/hda
.fi
Examine all S.M.A.R.T. data for device /dev/hda, but produce no
printed output.  You must use the exit status (the
.B $?
shell variable) to learn if any attributes are out of bound, if the
S.M.A.R.T. status is failing, if there are errors recorded in the
self-test log, or if there are errors recorded in the disk error log.

.PP
.SH RETURN VALUES
The return values of smartctl are defined by a bitmask.  For the
moment this only works on ATA disks.  The different bits in the return
value are as follows:
.TP
.B Bit 0: 
Command line did not parse.
.TP
.B Bit 1:
Device open failed, or device did not return an IDENTIFY DEVICE structure. 
.TP
.B Bit 2:
Some SMART command to the disk failed, or there was a checksum error
in a SMART data structure (see '\-W' option above).
.TP
.B Bit 3:
SMART status check returned "DISK FAILING".
.TP
.B Bit 4:
SMART status check returned "DISK OK" but we found prefail attributes <= threshold.
.TP
.B Bit 5:
SMART status check returned "DISK OK" but we found that some (usage
or prefail) attributes have been <= threshold at some time in the
past. 
.TP
.B Bit 6:
The device error log contains records of errors.
.TP
.B Bit 7:
The device self-test log contains records of errors.

To test within the shell for whether or not the different bits are
turned on or off, you can use the following type of construction (this
is bash syntax):
.nf
.B smartstat=$(($? & 8))
.fi
This looks at only at bit 3 of the exit status
.B $?
(since 8=2^3).  The shell variable
$smartstat will be nonzero if SMART status check returned 'disk
failing' and zero otherwise.

.PP
.SH AUTHOR
Bruce Allen
.B smartmontools-support@lists.sourceforge.net
.fi
University of Wisconsin - Milwaukee Physics Department

.PP
.SH CREDITS
.fi
This code was derived from the smartsuite package, written by Michael
Cornwell, and from the previous ucsc smartsuite package.  It extends
these to cover ATA-5 disks.  This code was originally developed as a
Senior Thesis by Michael Cornwell at the Concurrent Systems Laboratory
(now part of the Storage Systems Research Center), Jack Baskin School
of Engineering, University of California, Santa
Cruz. http://ssrc.soe.ucsc.edu/.
.SH
HOME PAGE FOR SMARTMONTOOLS: 
.fi
Please see the following web site for updates, further documentation, bug
reports and patches:
.nf
.B
http://smartmontools.sourceforge.net/

.SH
SEE ALSO:
.B
smartd (8)
.SH
REFERENCES FOR S.M.A.R.T.
.fi
If you would like to understand better how S.M.A.R.T. works, and what
it does, a good place to start is  Section 8.41 of the 'AT
Attachment with Packet Interface-5' (ATA/ATAPI-5) specification.  This
documents the S.M.A.R.T. functionality which the smartmontools
utilities provide access to.  You can find Revision 1 of this document
at:
.nf
.B
http://www.t13.org/project/d1321r1c.pdf
.fi
Future versions of the specifications (ATA/ATAPI-6 and ATA/ATAPI-7),
and later revisions (2, 3) of the ATA/ATAPI-5 specification are
available from:
.nf
.B
http://www.t13.org/#FTP_site

.fi
The functioning of S.M.A.R.T. is also described by the SFF-8035i
revision 2 specification.  This is a publication of the Small Form
Factors (SFF) Committee, and can be obtained from:
.TP
\ 
SFF Committee
.nf
14426 Black Walnut Ct.
.nf
Saratoga, CA 95070, USA
.nf
SFF FaxAccess: +01 408-741-1600
.nf
Ph: +01 408-867-6630
.nf
Fax: +01 408-867-2115
.nf
E-Mail: 250-1752@mcimail.com.
.PP
Please let us know if there is an on\-line source for this document.

.SH
CVS ID OF THIS PAGE:
$Id: smartctl.8,v 1.27 2002/11/22 13:44:00 ballen4705 Exp $