path: root/static/freebsd/man1/recoverdisk.1

.\" Copyright (c) 2006 Ulrich Spoerlein <uspoerlein@gmail.com>
.\" All rights reserved.
.\"
.\" 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.
.\"
.Dd April 3, 2020
.Dt RECOVERDISK 1
.Os
.Sh NAME
.Nm recoverdisk
.Nd recover data from disk-like devices.
.Sh SYNOPSIS
.Nm
.Op Fl b Ar bigsize
.Op Fl i Ar interval
.Op Fl r Ar readlist
.Op Fl s Ar interval
.Op Fl u Ar pattern
.Op Fl v
.Op Fl w Ar writelist
.Ar source
.Op Ar destination
.Sh DESCRIPTION
The
.Nm
utility reads all data from the
.Ar source
and retries read operations until they succeed.
If
.Ar destination
is specified all data read be written there.
.Pp
The internal work-list can be saved and loaded so that
.Nm
sessions can be resumed, for instance when a marginal
source hard-disk shuts down.
.Pp
The work-list is initialized with a single item which covers the entire
.Ar source
and
.Nm
always chips away at the first item on the work-list.

When a read succeeds, that part of the current chunk is eliminated
from the work-list.

When a read fails, that part of the item is appended to the worklist
as a separate item, and will be retried in due order.
If
.Ar destination
is specified, the corresponding range is filled with '_UNREAD_'.
.Pp
The first pass attempts to read everything in "big-size" chunks,
the second pass reads in "medium-size" chunks and third and subsequent
passes read in "small-size" chunks.
This three stage process is an attempt to optimize the case where only
a few bad blocks exist on
.Ar source .
If too many read-errors are encountered,
.Nm
will fall back to smaller sizes sooner.
.Pp
The three sizes default to 128kB (or less if the sector size does
not divide 128kB cleanly, for instance audio CD media), and the
reported
.Dv DIOCGSTRIPESIZE
and
.Dv DIOCGSECTORSIZE
respectively.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl b Ar bigsize
The size of reads attempted in first pass.
.It Fl m Ar mediumsize
The size of reads attempted in second pass.
.It Fl s Ar smallsize
The size of reads attempted in third and subsequent passes.
.It Fl r Ar work-list-file
Read the work-list from a file.
.It Fl w Ar work-list-file
Write the work-list to a file when a read succeed, but at most once
every minute.
.It Fl l Ar log-file
Each successful read is logged with timestamp, offset and length.
.It Fl t Ar totalsize
How many bytes should be recovered.
The default is what
.Dv DIOCGMEDIASIZE
reports for character and block devices or
.Dv st_size
if
.Ar source
is a regular file.
.It Fl i Ar pause
.Xr sleep 3
this long between reads.  This reduces the load on the
.Ar source
device and the system in general.
.It Fl p Ar pause
.Xr sleep 3
this long whenever a read fails.
This makes the
.Ar source
device look less sick to the operating system.
.It Fl u Ar pattern
By default blocks which cannot be read are filled with the pattern
.Ql _UNREAD_
in the output file.
This option can be used to specify a different pattern.
If the pattern is the empty string, nothing is written.
.It Fl v
Produce a detailed progress report with ANSI escapes and UTF-8.
.El
.Pp
.Nm
can be aborted with
.Dv SIGINT ,
but with a sick
.Ar source
it may take up to several minutes before the current read operation
returns from the kernel.
.Pp
.Sh EXAMPLES
.Bd -literal
# check if all sectors can be read on a USB stick:
recoverdisk /dev/da0

# recover data from failing hard drive ada3
recoverdisk /dev/ada3 /data/disk.img

# clone a hard disk
recoverdisk /dev/ada3 /dev/ada4

# read an ISO image from a CD-ROM
recoverdisk /dev/cd0 /data/cd.iso

# continue reading from a broken CD and update the existing worklist
recoverdisk -r worklist -w worklist /dev/cd0 /data/cd.iso

# recover a single file from the unreadable media
recoverdisk /cdrom/file.avi file.avi

.Ed
.Sh PRACTICAL ADVICE
In Datamuseum.dk
.Nm
has been used to recover all sorts of data-media for two decades,
here are some things we have learned:
.Bl -bullet
.It
Interacting with failing hardware has a tendency to crash machines,
so it is always a good idea to use the
.Fl -w work-list-file
so that it is possible to continue.
.It
When attempting to recover hard to read data from failing hard disks,
it pays to pamper the drive as much as possible:
.It
It is generally best to keep the drive in it's usual physical orientation,
but it can also help to try other orientations.
.It
Insulate the drive from external vibrations.
.It
Keep the drive cool with a fan.
.It
If possible, power the drive from a laboratory power supply.
.It
Do not lose patience:  Let
.Nm
run as long as possible.
.It
(S)ATA controllers do not handle failing disks well, if this
is a problem, use a USB-(S)ATA adapter instead.
.It
The
.Nm
source code is deliberately written to be easily portable to
older versions of
.Fx
and to other operating systems.
.It
If you need to read ST-506, RLL or ESDI drives
.Fx 3.5.1
is a good compromise.
.It
Sometimes forcing the disk to step between reads helps.
Since
.Nm
process the work-list in the order it is read, this
can be accomplished by sorting the work-list with
something like:
.Dl % sort +0.5
.It
By default the
.Xr CAM
layer will retry failing read operations, but that
will get stuck on the bad sectors for long time
and delay recovering what actually can be read from
a rapidly failing drive.
In that situation, set the appropriate
.Dl kern.cam.*.retry_count
sysctl to zero.
.It
For floppies and un-zoned hard disks (ST-506 to
early IDE) set
.Fl b Ar bigsize
to the size of a track.
.El
.Sh SEE ALSO
.Xr dd 1 ,
.Xr ada 4 ,
.Xr cam 4 ,
.Xr cd 4 ,
.Xr da 4
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 7.0
because Somebody™ forgot to make a backup copy.
.Sh AUTHORS
.An -nosplit
The original implementation was done by
.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org
with minor improvements from
.An Ulrich Sp\(:orlein Aq Mt uqs@FreeBSD.org .
.Pp
This manual page was originally written by
.An Ulrich Sp\(:orlein .
.Sh BUGS
If a failing device causes the machine to crash, there is
a risk that a chunk might have been successfully read
and removed from the work-list, but not yet flushed to
the
.Ar destination .
.Pp
.Nm
calls
.Xr fdatasync 3
on the destination before writing the work-list to a
temporary file, and calls it again on the temporary
file before renaming it to the specified
.Fl w Ar work-file-list
filename.
But even then things dont always work out.
.Pp
.Nm
should have an option for reconstructing the work-list
from the
.Ar destination
by enumerating the
.Fl u Ar pattern
filled ranges.