307 lines
10 KiB
Groff
307 lines
10 KiB
Groff
.\" $NetBSD: atactl.8,v 1.32 2022/05/24 06:27:59 andvar Exp $
|
|
.\"
|
|
.\" Copyright (c) 1998, 2019 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Ken Hornstein and Matthew R. Green.
|
|
.\"
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd March 2, 2019
|
|
.Dt ATACTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm atactl
|
|
.Nd a program to manipulate ATA (IDE) devices and busses
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar device
|
|
.Ar command
|
|
.Oo
|
|
.Ar arg Oo ...
|
|
.Oc
|
|
.Oc
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
allows a user or system administrator to issue commands to and otherwise
|
|
control devices which reside on standard IDE and ATA controllers, or
|
|
the ATA bus itself.
|
|
It is used by specifying a device or bus to manipulate,
|
|
the command to perform, and any arguments the command may require.
|
|
.Pp
|
|
You may also control devices which are inside a SCSI enclosure, this
|
|
includes many USB disks.
|
|
In this case ATA commands are passed through
|
|
the SCSI layer using SATL commands.
|
|
.Sh DEVICE COMMANDS
|
|
The following commands may be used on IDE and ATA devices.
|
|
Note that not all devices support all commands.
|
|
.Bl -tag -width setidleXX
|
|
.It Cm identify
|
|
Identify the specified device, displaying the device's vendor, product,
|
|
revision strings, and the device's capabilities.
|
|
.It Cm idle
|
|
Place the specified device into Idle mode.
|
|
This mode may consume less power than Active mode.
|
|
.It Cm standby
|
|
Place the specified device into Standby mode.
|
|
This mode will consume less power than Idle mode.
|
|
.It Cm sleep
|
|
Place the specified device into Sleep mode.
|
|
This mode will consume less power than Standby mode,
|
|
but requires a device reset to resume operation.
|
|
Typically the
|
|
.Xr wd 4
|
|
driver performs this reset automatically,
|
|
but this should still be used with caution.
|
|
.It Cm setidle Ar idle-timer
|
|
Places the specified device into Idle mode,
|
|
and sets the Idle timer to
|
|
.Ar idle-timer
|
|
seconds.
|
|
A value of 0 will disable the Idle timer.
|
|
.It Cm setstandby Ar standby-timer
|
|
Places the specified device into Standby mode,
|
|
and sets the Standby timer to
|
|
.Ar standby-timer
|
|
seconds.
|
|
A value of 0 will disable the Standby timer.
|
|
.It Cm checkpower
|
|
Will print out if the device is in Active, Idle, or Standby power
|
|
management mode.
|
|
.It Cm apm Oo Ar disable | set # Oc
|
|
Controls the Advanced Power Management feature of the specified device.
|
|
Advanced Power Management is an optional feature used to specify a power
|
|
management level to balance between device performance and power consumption.
|
|
.Bl -tag -width selftestXlogXX
|
|
.It Ar disable
|
|
Disable the Advanced Power Management.
|
|
.It Ar set #
|
|
Enable the Advanced Power Management feature and set its level to the value #,
|
|
where # is an integer within the scale 0-253; being 0 the mode with the
|
|
lowest power consumption (and thus the worse performance) and 253 the mode
|
|
which provides the better performance at a cost of more power consumption.
|
|
.Pp
|
|
It should be noted that the effect of the value need not be continuous.
|
|
For example, a device might provide only two modes: one from 0 to 126
|
|
and other from 127 to 253.
|
|
Per the specification, values of 127 and higher do not permit the device
|
|
to spin down to save power.
|
|
.El
|
|
.It Cm smart Oo Ar enable | disable | status Oo vendor Oc | offline # | error-log | selftest-log Oc
|
|
Controls SMART feature set of the specified device.
|
|
SMART stands for Self-Monitoring, Analysis, and Reporting Technology.
|
|
It provides an early warning system by comparing subtle operation
|
|
characteristics to those determined in vendor testing
|
|
to precede device failures.
|
|
.Bl -tag -width selftestXlogXX
|
|
.It Ar enable
|
|
Enables access to SMART capabilities within the device.
|
|
Prior to being enabled, a SMART capable device neither
|
|
monitors nor saves SMART attribute values.
|
|
The state of SMART, either enabled or disabled, will
|
|
be preserved by the device across power cycles.
|
|
.It Ar disable
|
|
Disables access to SMART capabilities within the device.
|
|
Attribute values will be saved, and will no longer be monitored.
|
|
.It Ar status Op Ar vendor
|
|
Reports whether SMART is supported by the device, and whether SMART is
|
|
enabled on the device (can only be determined on ATA6 or better devices).
|
|
If SMART is enabled, then a table of attribute information is printed.
|
|
Attributes are the specific performance or calibration parameters that
|
|
are used in analyzing the status of the device.
|
|
The specific set of attributes being used and the identity of
|
|
these attributes is vendor specific and proprietary.
|
|
.Pp
|
|
Attribute values are used to represent the relative reliability of
|
|
individual performance or calibration parameters.
|
|
The valid range of attribute values is from 1 to 253 decimal.
|
|
Lower values indicate that the analysis algorithms being used by the device
|
|
are predicting a higher probability of a degrading or faulty condition.
|
|
.Pp
|
|
Each attribute value has a corresponding threshold limit which is used for
|
|
direct comparison to the attribute value to indicate the existence of a
|
|
degrading or faulty condition.
|
|
The numerical value of the attribute thresholds are determined by the
|
|
device manufacturer through design and reliability testing and analysis.
|
|
Each attribute threshold represents the lowest limit to which its
|
|
corresponding attribute value can equal while still retaining a
|
|
positive reliability status.
|
|
.Pp
|
|
If the crit field is
|
|
.Dq yes
|
|
then negative reliability of this attribute
|
|
predicts imminent data loss.
|
|
Otherwise it merely indicates that the intended design life period
|
|
of usage or age has been exceeded.
|
|
The collect field indicates whether this attribute is updated while the
|
|
device is online.
|
|
The reliability field indicates whether the attribute
|
|
value is within the acceptable threshold.
|
|
.Pp
|
|
If the
|
|
.Ar vendor
|
|
argument is supplied, a vendor-specific table will be used for SMART
|
|
information if known to
|
|
.Nm .
|
|
Currently, only
|
|
.Dq micron
|
|
has a vendor-specific table.
|
|
If the vendor is not supplied, it may be guessed from devices' model
|
|
or other data available.
|
|
.It Ar offline #
|
|
Runs the numbered offline self-test on the drive.
|
|
.It Ar error-log
|
|
Prints the error log.
|
|
.It Ar selftest-log
|
|
Prints the self-test log.
|
|
.El
|
|
.It Cm security Oo Ar status | freeze | setpass | unlock | disable | erase Oc
|
|
Controls
|
|
.Dq security
|
|
(password protection) features of modern ATA drives.
|
|
The security commands are intended to be issued by low-level
|
|
software (firmware / BIOS) only.
|
|
Generally, the security status should be
|
|
.Dq frozen
|
|
before the operating system is started so that misbehaving or malicious
|
|
software cannot set or change a password.
|
|
Older and buggy BIOSes neglect to do so; in these cases it might make
|
|
sense to issue the
|
|
.Dq freeze
|
|
command early in the boot process.
|
|
.Bl -tag -width freezeXX
|
|
.It Ar status
|
|
displays the drive's security status
|
|
.It Ar freeze
|
|
freezes the drive's security status
|
|
.It Ar setpass Oo user | master Oc
|
|
sets the drive's user or master password
|
|
.It Ar unlock Oo user | master Oc
|
|
unlocks a password-protected drive
|
|
.It Ar disable Oo user | master Oc
|
|
disables password protection
|
|
.It Ar erase Oo user | master Oc
|
|
erases the device and clears security state, using enhanced erasure if
|
|
the drive supports it; may take a long time to run
|
|
.El
|
|
.Pp
|
|
Note that to erase a drive, it must have a password set and be
|
|
unfrozen.
|
|
If you can't persuade your firmware to leave the drive unfrozen on
|
|
boot, but it is a SATA drive, say
|
|
.Pa wd2
|
|
at
|
|
.Pa atabus3 ,
|
|
that you can safely physically disconnect and reconnect, then you may
|
|
be able to use SATA hot-plug to work around this: first run
|
|
.Bd -literal -offset indent
|
|
# drvctl -d wd2
|
|
.Ed
|
|
.Pp
|
|
Then physically disconnect and reconnect the drive, and run
|
|
.Bd -literal -offset indent
|
|
# drvctl -r -a ata_hl atabus3
|
|
.Ed
|
|
.Pp
|
|
After this, check that the security status does not list
|
|
.Dq frozen :
|
|
.Bd -literal -offset indent
|
|
# atactl wd2 security status
|
|
supported
|
|
#
|
|
.Ed
|
|
.El
|
|
.Sh BUS COMMANDS
|
|
The following commands may be used on IDE and ATA busses.
|
|
Note that not all devices support all commands.
|
|
.Bl -tag -width resetXX
|
|
.It Cm reset
|
|
Reset the bus.
|
|
This will reset all ATA devices present on the bus.
|
|
Any ATAPI device with pending commands will also be reset.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To erase
|
|
.Pa wd2
|
|
which is currently unfrozen and has no password set:
|
|
.Bd -literal -offset indent
|
|
# atactl wd2 security status
|
|
supported
|
|
# atactl wd2 security setpass user
|
|
Password:
|
|
Confirm password:
|
|
# atactl wd2 security status
|
|
supported
|
|
enabled
|
|
# atactl wd2 security erase user
|
|
Password:
|
|
Erasing may take up to 0h 2m 0s...
|
|
#
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr ioctl 2 ,
|
|
.Xr wd 4 ,
|
|
.Xr dkctl 8 ,
|
|
.Xr drvctl 8 ,
|
|
.Xr scsictl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command first appeared in
|
|
.Nx 1.4 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
command was written by
|
|
.An Ken Hornstein .
|
|
It was based heavily on the
|
|
.Xr scsictl 8
|
|
command written by
|
|
.An Jason R. Thorpe .
|
|
.An Matthew R. Green
|
|
significantly enhanced the
|
|
.Cm smart status
|
|
support.
|
|
.An Michael van Elst
|
|
added support for SATL.
|
|
.Sh BUGS
|
|
The output from the
|
|
.Cm identify
|
|
command is rather ugly.
|
|
.Pp
|
|
Support for master passwords is not implemented.
|
|
.Pp
|
|
The
|
|
.Nx
|
|
kernel behaves poorly with drives that have passwords set and are
|
|
locked.
|
|
.Pp
|
|
The
|
|
.Cm smart status
|
|
command currently guesses the vendor attribute name table to use,
|
|
and may be wrong or miss supported devices.
|
|
.Pp
|
|
SATL bus commands don't work yet.
|