path: root/usr/src/man/man1m/ntfsclone.1m

'\" te
.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright (c) 2002-2006 Szabolcs Szakacsits
.\" Copyright (c) 2002-2005 Anton Altaparmakov
.\" Copyright (c) 2002-2003 Richard Russon
.\" Copyright (c) 2007 Yura Pakhuchiy
.\" 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 of the License, or (at your option) any later version.  This program is distributed
.\" in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.  You should have received a copy of the GNU General Public License along with this program
.\" (in the main directory of the Linux-NTFS distribution in the file COPYING);  if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 11-1307 USA
.TH NTFSCLONE 1M "May 14, 2009"
.SH NAME
ntfsclone \- clone, image, restore, or rescue an NTFS
.SH SYNOPSIS
.LP
.nf
\fBntfsclone\fR [\fIoptions\fR] \fIsource\fR
.fi

.LP
.nf
\fBntfsclone\fR \fB--save-image\fR [\fIoptions\fR] \fIsource\fR
.fi

.LP
.nf
\fBntfsclone\fR \fB--resotore-image\fR [\fIoptions\fR] \fIsource\fR
.fi

.LP
.nf
\fBntfsclone\fR \fB--metadata\fR [\fIoptions\fR] \fIsource\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBntfsclone\fR utility efficiently clones (which includes copy, save,
backup, and restore operations) or rescues an NTFS filesystem to a sparse file,
an image, a device (partition), or to standard output. It works at disk sector
level and copies only the written data (that is, not empty space). Unused disk
space becomes zero (cloning to sparse file), encoded with control codes (saving
in special image format), left unchanged (cloning to a disk/partition) or
filled with zeros (cloning to standard output).
.sp
.LP
\fBntfsclone\fR can be useful in making backups\(emtaking an exact snapshot of
an NTFS filesystem\(emand restoring it later on. It also can be used to test
NTFS read/write functionality and allows you to troubleshoot users' issues
using the clone, without the risk of destroying the original file system.
.sp
.LP
If not using the special image format (see section of the same name below), the
clone is an exact copy of the original NTFS file system, from sector to sector.
Thus, it can also be mounted just like the original NTFS filesystem. For
example, if you clone to a file and the kernel has a loopback device and NTFS
support, then the file can be mounted using:
.sp
.in +2
.nf
# \fBmount -t ntfs -o loop ntfsclone.img\fR
.fi
.in -2
.sp

.SS "Windows Cloning"
.sp
.LP
You must exercise great care to copy, move or restore a system or boot
partition  to  another computer, or to a different disk or partition (for
example, \fB/dev/dsk/c0d0p1\fR to \fB/dev/dsk/c0d0p2\fR, \fB/dev/dsk/c0d0p1\fR
to \fB/dev/dsk/c0d1p1\fR or to a different disk sector offset).
.sp
.LP
Under most circumstances, to enable Windows to boot you must copy, move, or
restore NTFS to the same partition that has the following characteristics as
the original partition and disk:
.RS +4
.TP
.ie t \(bu
.el o
starts at the same sector
.RE
.RS +4
.TP
.ie t \(bu
.el o
on the same type of disk
.RE
.RS +4
.TP
.ie t \(bu
.el o
having the same BIOS legacy cylinder setting
.RE
.sp
.LP
The \fBntfsclone\fR utility guarantees an exact copy of NTFS but does not deal
with booting issues. This is by design: \fBntfsclone\fR is a file system, not a
system, utility. Its goal is only NTFS cloning, not Windows cloning. Because of
this, \fBntfsclone\fR can be used as a very fast and reliable building block
for Windows cloning, but is not a complete answer. You can find useful tips on
NTFS cloning at the NTFS web site, http://wiki.linux-ntfs.org\&.
.SS "Sparse Files"
.sp
.LP
A file containing unallocated blocks (holes) is referred to as a "sparse file".
The reported size of such files is always higher than the disk space consumed
by them. The \fBdu\fR(1) command reports the real disk space used by a sparse
file. The holes are always read as zeros. All major Linux file systems, such
as, \fBext2\fR, \fBext3\fR, \fBreiserfs\fR, \fBReiser4\fR, JFS, and XFS support
sparse files. However, the ISO 9600 CD-ROM file system, as one example, does
not.
.SS "Special Image Format"
.sp
.LP
It is recommended that you save an NTFS filesystem to a special image format.
Instead of representing unallocated blocks as holes, they are encoded using
control codes. Thus, the image saves space without requiring sparse file
support. The image format is ideal for streaming file system images over the
network. The disadvantage of the special image format is that you cannot mount
the image directly; you must first restore it.
.sp
.LP
To save an image using the special image format, use the  \fB-s\fR or  the
\fB--save-image\fR option. To restore an image, use the \fB-r\fR or the
\fB--restore-image\fR option. Note that you can restore images from  standard
input by using a hyphen (\fB-\fR) as the source file.
.SS "Metadata-only Cloning"
.sp
.LP
Using the \fB-m\fR or \fB--metadata\fR option, \fBntfsclone\fR can save only
the NTFS metadata and the clone still will be mountable. In this usage, all
non-metadata file content is lost; reading back the data results in all zeros.
.sp
.LP
The metadata-only image can be compressed very well, usually to a size in the
range of 1 to 8 MB. It is convenient to transfer such an image for
investigation and troubleshooting.
.sp
.LP
In metadata-only mode, \fBntfsclone\fR saves none of the user's data, which
includes the resident user's data embedded into metadata. All is filled with
zeros. Moreover, all the file timestamps, and deleted and unused spaces inside
the metadata are filled with zeros. Thus, this mode is inappropriate, for
example, for forensic analyses.
.sp
.LP
Note that filenames are not removed. Because a filename might contain sensitive
information, consider the possibities for breaches of security or privacy
before sending out a metadata-only image.
.SH OPTIONS
.sp
.LP
Supported options are listed below. Most options have both single-letter and
full-name forms. Multiple single-letter options that do not take an argument
can be combined. For example, \fB-fv\fR is the equivalent of \fB-f\fR \fB-v\fR.
A full-name option can be abbreviated to a unique prefix of its name.
.sp
.ne 2
.na
\fB\fB-f\fR, \fB--force\fR\fR
.ad
.sp .6
.RS 4n
Forces \fBntfsclone\fR to proceed, even if the filesystem is marked "dirty"
following a consistency check.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR, \fB--help\fR\fR
.ad
.sp .6
.RS 4n
Show a list of options with a brief description of each one.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR, \fB--ignore-fs-check\fR\fR
.ad
.sp .6
.RS 4n
Ignore the result of the file system consistency check. This option can be used
only with the \fB--meta-data\fR option. Any clusters that cause an
inconsistency are saved.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR, \fB--metadata\fR\fR
.ad
.sp .6
.RS 4n
Clone only metadata. With this option, you must clone only to a file.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR, \fB--output\fR \fIfile\fR\fR
.ad
.sp .6
.RS 4n
Clone NTFS to the non-existent \fIfile\fR. If \fIfile\fR is a hyphen (\fB-\fR),
clone to the standard output.
.RE

.sp
.ne 2
.na
\fB\fB-O\fR, \fB--overwrite\fR \fIfile\fR\fR
.ad
.sp .6
.RS 4n
Clone NTFS to \fIfile\fR, overwriting \fIfile\fR if it already exists.
.RE

.sp
.ne 2
.na
\fB\fB--rescue\fR\fR
.ad
.sp .6
.RS 4n
Ignore disk read errors so that a disk having bad sectors, for example, a
failing disk, can be rescued with minimal impact on the disk. \fBntfsclone\fR
works at the lowest, sector level in this mode, enabling more data to be
rescued. The contents of the unreadable sectors are filled with the question
mark (\fB?\fR) character; the beginning of such sectors are marked by the
string: \fBBadSector\fR.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR, \fB--restore-image\fR \fIsource\fR\fR
.ad
.sp .6
.RS 4n
Restore from the special image format specified by \fIsource\fR. If
\fIsource\fR is a hyphen (\fB-\fR), the image is read from the standard input.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR, \fB--save-image\fR\fR
.ad
.sp .6
.RS 4n
Save to the special image format. In terms of space usage and speed, this is
the most efficient option if imaging is done to the standard output. This
option is useful for image compression, encryption, or streaming through a
network.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCloning with Overwrite Option
.sp
.LP
The following command clones with the \fB--overwrite\fR option.

.sp
.in +2
.nf
# \fBntfsclone --overwrite /dev/dsk/c0d2p1 /dev/dsk/c0d0p1\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRSaving to Special Image Format
.sp
.LP
The following command clones to the special image format to its original
partition.

.sp
.in +2
.nf
# \fBntfsclone --save-image --output backup.img /dev/dsk/c0d0p1\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRRestoring from a Special Image File
.sp
.LP
The following command restores an NTFS from a special image file.

.sp
.in +2
.nf
# \fBntfsclone --restore-image --overwrite /dev/dsk/c0d0p1 backup.img\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRSaving to a Compressed Image
.sp
.LP
The following command saves an NTFS to a compressed image file.

.sp
.in +2
.nf
# \fBntfsclone --save-image -o - /dev/dsk/c0d0p1\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fRRestoring from a Compressed Image
.sp
.LP
The following command restores an NTFS volume from a compressed image file.

.sp
.in +2
.nf
# \fBgunzip -c backup.img.gz | \e\fR
\fBntfsclone --restore-image --overwrite /dev/dsk/c0d0p1 -\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRBacking up to a Remote Host Using \fBssh\fR
.sp
.LP
The following command backs up to a remote host, using \fBssh\fR(1). Note that
\fBssh\fR will probably require a password.

.sp
.in +2
.nf
# \fBntfsclone --save-image --output - /dev/dsk/c0d0p1 | \e\fR
\fBgzip -c | ssh host `cat > backup.img.gz`\fR
.fi
.in -2
.sp

.LP
\fBExample 7 \fRRestoring from a Remote Host Using \fBssh\fR
.sp
.LP
The following command backs up to a remote host, using \fBssh\fR(1). Note that
\fBssh\fR will probably require a password.

.sp
.in +2
.nf
# \fBssh host `cat backup.img.gz` | gunzip -c  | \e\fR
\fBntfsclone --restore-image --overwrite /dev/dsk/c0d0p1 -\fR
.fi
.in -2
.sp

.LP
\fBExample 8 \fRStreaming an Image File from a Web Server
.sp
.LP
The following command streams an image file from a web server and restore it to
a partition.

.sp
.in +2
.nf
# \fBwget -qO - http://server/backup.img | \e\fR
\fBntfsclone --restore-image --overwrite /dev/dsk/c0d0p1 -\fR
.fi
.in -2
.sp

.LP
\fBExample 9 \fRCloning to a New File
.sp
.LP
The following command clones an NTFS volume to a non-existent file.

.sp
.in +2
.nf
# \fBntfsclone --output ntfs-clone.img /dev/dsk/c0d0p1\fR
.fi
.in -2
.sp

.LP
\fBExample 10 \fRPacking NTFS Metadata
.sp
.LP
The following command packs NTFS metadata into an image file. Note that
\fBbzip2\fR takes a much longer time than \fBgzip\fR, but produces an archive
that is up to ten times smaller than the latter produces.

.sp
.in +2
.nf
# \fBntfsclone --metadata --output ntfsmeta.img /dev/dsk/c0d0p1\fR
\fBbzip2 ntfsmeta.img\fR
.fi
.in -2
.sp

.LP
\fBExample 11 \fRUnpacking NTFS Metadata
.sp
.LP
The following command unpacks NTFS metadata into a sparse file.

.sp
.in +2
.nf
# \fBbunzip2 -c ntfsmeta.img.bz2 | \e\fR
\fBcp --sparse=always /proc/self/fd/0 ntfsmeta.img\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The return code is zero on success, non-zero otherwise.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Uncommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBdu\fR(1), \fBssh\fR(1), \fBntfsresize\fR(1M), \fBntfsundelete\fR(1M),
\fBparted\fR(1M), \fBattributes\fR(5)
.sp
.LP
http://wiki.linux-ntfs.org
.SH AUTHORS
.sp
.LP
\fBntfsclone\fR was written by Szabolcs Szakacsits with contributions from Per
Olofsson (special image format support) and Anton Altaparmakov.